MorphOS Library - User contributions [en]

An Introduction to MorphOS PPC Assembly

2011-02-16T08:40:06Z

AusPPC: Fixed bad link to source archive.

==Jump In The Deep End And Compile Something Right Now==

You could copy and paste but just entering the two lines below into a suitable text editor is probably quicker.

<pre>
.text
blr
</pre>

Save as ''shorty.s''

'''.text''' is an assembler directive - more about it later. '''blr''' is one of many branch instructions. This particular one means 'Branch to Link Register'. When a program terminates, this is the last instruction to be executed and it causes the sequence of instruction execution to pass back to the calling program or environment (shell, Ambient etc). Subroutines can also terminate with this instruction but, again, more about this later.

This is as good a time as any to ask if you've installed vbcc yet - if not, go and do it. [http://mail.pb-owl.de/~frank/vbcc/current/vbcc_bin_morphos.lha Download vbcc]

Once vbcc is installed, open a shell window and change directory to where shorty.s has been saved.

Enter:

<pre>
vasmppc_std -Felf -o ram:shorty.o shorty.s
</pre>

This tells vasm to generate an ELF formatted object file called ''shorty.o'' in ram: from the ''shorty.s'' source file.

==Hello? World's Shortest MorphOS Program - Or Is It?==

There are times when a linker is needed to further process an object file to generate an executable - this isn't one of those times.

Go ahead and enter this into the shell window:

<pre>
ram:shorty.o
</pre>

It will appear as if nothing happens - but at least it happens very quickly. However, something did happen. ''shorty.o'' was identified as an executable program and loaded into memory where the cpu instruction execution sequence passed to it. As mentioned above, the single '''blr''' instruction in this program caused the instruction execution sequence to pass directly back to where it was called from - in this case, the shell.

It may be of interest to know that all PPC instructions are four bytes long. In PPC nomenclature, this length is known as a '''word'''. But let's take a moment to have a look at the size of ''shorty.o''

Enter this into the shell window:

<pre>
list ram:shorty.o
</pre>

2664 bytes?! But this is typical for object files as they contain much additional information that is used in the process of debugging and linking. Linking, particularly with the '''-s''' 'strip all symbols' option, will generate an executable that is noticeably smaller.

Try entering this into the shell window:

<pre>
vlink -s -o ram:shorty ram:shorty.o

list ram:shorty
</pre>

The newly generated executable is 328 bytes - much smaller than its object file but what are those other 324 bytes doing there? They are the ELF 'container' that holds the single, four byte instruction of ''shorty''. ELF stands for Executable and Linkable Format and it is used by MorphOS, AmigaOS4 and AROS - not to forget, Linux, UNIX, BSD and even video game consoles. There is abundant information about this file format online but this topic will be discussed a little further when the use of the ''objdump'' program is introduced.

==The Old And The New==

Generally, in order to make a program that does something useful or to at least produce an observable result, it is necessary to use operating system library functions. Despite the markedly different cpu family that MorphOS runs on compared to the 68k family used by the classic AmigaOS, MorphOS is largely compatible with AmigaOS. This compatibility is reflected in a very similar API shared with AmigaOS and extends to using a MorphOS system structure as if it were the internal data and address registers of an actual 68k processor. This is called the EmulHandle structure and it is always available through the PPC GPR2 register. Also, as with 68k AmigaOS, the address of the Exec library base is always to be found at memory location 4. Many aspects of the AmigaOS API fit closely to the features available in the 68k cpu and the following code comparison should illustrate how it is echoed in the PPC MorphOS API.

A common task performed during the initialisation of many programs - opening the Dos library. It is a particularly simple example of library usage but most functions follow this form.

[[File:Old-and-new.png]]

'''@h''' '''@ha''' & '''@l''' attributes are needed to specify the high and low halfwords of 32 bit immediate values because the fixed 32 bit size of PPC instructions does not allow enough space for an instruction opcode and additional 32 bits of data. The difference between '''@h''' and '''@ha''' is due to the common use of the '''addi''' (add immediate) instruction, which only takes a signed immediate value, to provide the lower 16 bits of a 32 bit constant - such as an address. Sometimes these lower 16 bits will equate to a negative value and it is then that prior use of the '''@ha''' attribute will cause its immediate value to be adjusted to compensate. These details are only resolved before execution, when the program is loaded. The '''@h''' attribute just specifies the upper halfword of a 32 bit constant without regard for what follows. While I'm banging on about such intricacies, the meaning of ''zero'' in ''load word and zero'' of the '''lwz''' instruction is that on 64 bit PPC processors, this instruction will load a 32 bit value from memory into the lower word of a 64 bit GPR and then clear (or zero) its upper word. Something to consider when MorphOS is available on G5 class computers... 

One could be forgiven for thinking that the PPC code snippet looks a little ungainly compared to the former. Whereas every PPC instruction is four bytes long, 68k instructions can be as little as two bytes but up to as many as ten. A single 68k instruction can load a value from a 32 bit memory address specified by one instruction operand and store it at another 32 bit memory address specified by the second instruction operand. The 68k can also perform other operations beyond simple loads and stores directly on memory. Or at least appear to... In truth, computer memory only sends and receives data - no other data processing (like adding, subtracting & etc) occurs in memory. While the 68k instruction '''add.l #$12345678,(a0)''' appears to add the immediate value of it's first operand to whatever may already be stored at the address pointed to by a0, the contents of that address are actually loaded from memory into a private work register, the addition is performed and then the result is stored back to the same memory location. So this instruction actually performs two memory accesses where it might appear that there was only one. Contrast this with PPC assembly programming where memory loads and stores are all done explicitly. Before data can be operated upon it must be loaded from memory into a GPR (General Purpose Register), zero (in the case of a simple memory copy) or more operations can then be performed and then the data may be stored back to memory.

Unless you are brand-spanking-new to the topic of PPC assembly, you will already know that the PPC has 32 GPRs - r0 through r31. But did you know that the desired use of these registers is set out in something called the System V.4 ABI which MorphOS adheres to?

<pre>
r0 - volatile
r1 - stack pointer
r2 - for system use (with MorphOS, r2 points to the EmulHandle structure)

r3 - initialised with a pointer to a Dos command buffer
r4 - initialised with the length of the Dos command buffer
r5 - initialised with a pointer to an ELF structure

r3 ... r10 volatile & can be used to pass function arguments. If more
arguments are required, the stack is used.

r11 & r12 - volatile

r13 - small data area pointer. If this register is needed by a function or
subroutine, it must be saved first and then restored before
returning to where it was called from.

r14 ... r31 - No predefined purpose. If these registers are needed by a
function or subroutine, they must be saved first and then restored
before returning to where it was called from.
</pre>

The above use of the word 'volatile' means that functions are not expected to preserve the contents of these registers. r1 & r2 are the only registers that must be restored to their initial values by a terminating program, however, while most programs will modify r1 and later restore it, it is best to have not modified r2 in the first place.

This System V.4 ABI also sets out a particular way for programs and subroutines to organise their stack frames. When a program is loaded into memory and the instruction execution sequence passes to it, the stack pointer is still pointing to the calling program's stack frame and there is also an important address stored in the Link Register at this time. Unless this program is very simple (like ''shorty'') it must save the Link Register address and, most likely, create it's own stack frame. Somewhat conveniently, there is a special position in the caller's stack frame that a callee program can save the contents of the Link Register to. This is a fairly common example of a program or subroutine's very first instructions.

[[File:Awkward-program-initialisation.png]]

'Uh?' indeed... Let's try to visualise some memory being used as stack space.

[[File:Stack-diagram16.png]]

Note that '''stwu r1,-8(r1)''' creates a two-word stack frame which is the smallest stack that a program or subroutine can have if it, in turn, calls another program, subroutine or library function. More often, a larger stack frame is created although, '''stwu r1,-4(r1)''' could be used by a program or subroutine to create a one-word stack frame but this would be redundant and such a program must not call any other program, subroutine or library function. Such a program would not need to store the value in the Link Register (LR) to prevent it from being overwritten by subsequent calls and can terminate and return to it's caller with a simple '''blr''' instruction - just like ''shorty'' does.

A further note about larger stack frames and appropriate stack sizes: For reasons relating to PPC architecture, it is a good idea to choose stack frame sizes that are multiples of 16 bytes.

This is a less common example of a program's first instructions but it may better illustrate how to use stack frames.

[[File:Program-initialisation.png]]

Let's jump ahead and look at the last few instructions involved in program termination that would 'undo' the above instructions.

[[File:Program-termination.png]]

==A Little Less Talk And A Little More Action Please==

It's time to compile another program - this one will actually do something.

But wait...

Not another 'Hello World' program... I'm afraid so. This time, copy and paste is probably quicker. Alternatively, download this fully commented [http://aminet.net/dev/src/MorphOS_PPC_HelloWorld.lha source archive].

Note that this example does not use the MorphOS SDK. Instead, some 'quick and dirty' methods are used for the sake of simplicity and readability.

<pre>
# Various library function offsets
.set _LVOOpenLibrary,-552
.set _LVOCloseLibrary,-414
.set _LVOVPrintf,-954

.set _AbsExecBase,4

# EmulHandle structure (always pointed to by r2)
.set reg_d0,0
.set reg_d1,4
.set reg_d2,8
.set reg_d3,12
.set reg_d4,16
.set reg_d5,20
.set reg_d6,24
.set reg_d7,28
.set reg_a0,32
.set reg_a1,36
.set reg_a2,40
.set reg_a3,44
.set reg_a4,48
.set reg_a5,52
.set reg_a6,56
.set reg_a7,60
.set EmulCallDirectOS,100

# Stack frame offsets
.set stack_pos0_caller_stack,0
.set stack_pos1_callerLR,4
.set stack_pos2_ExecBase,8
.set stack_pos3_DosBase,12
.set new_4_word_stack,16

.text

mflr r0
stw r0,stack_pos1_callerLR(r1)
stwu r1,-new_4_word_stack(r1)

lis r3,dosName@ha
addi r3,r3,dosName@l
stw r3,reg_a1(r2)
li r3,0
stw r3,reg_d0(r2)
li r3,_AbsExecBase
lwz r3,0(r3)
stw r3,stack_pos2_ExecBase(r1)
stw r3,reg_a6(r2)
li r3,_LVOOpenLibrary
lwz r0,EmulCallDirectOS(r2)
mtctr r0
bctrl

cmpwi r3,0
beq exit

stw r3,stack_pos3_DosBase(r1)

lis r4,string1@ha
addi r4,r4,string1@l
stw r4,reg_d1(r2)
li r4,0
stw r4,reg_d2(r2)
stw r3,reg_a6(r2)
li r3,_LVOVPrintf
lwz r0,EmulCallDirectOS(r2)
mtctr r0
bctrl

lwz r3,stack_pos3_DosBase(r1)
stw r3,reg_a1(r2)
lwz r3,stack_pos2_ExecBase(r1)
stw r3,reg_a6(r2)
li r3,_LVOCloseLibrary
lwz r0,EmulCallDirectOS(r2)
mtctr r0
bctrl

li r3,0

exit: addi r1,r1,new_4_word_stack
lwz r0,stack_pos1_callerLR(r1)
mtlr r0
blr

.rodata

.global __abox__ #__abox__ is a special MorphOS symbol that will
__abox__: #differentiate this program from other PPC
.word 1 #executables that can run on MorphOS...
.type __abox__,@object #When linking, care should be taken
.size __abox__,4 #to avoid stripping this symbol.

dosName:
.string "dos.library"

string1:
.string "Hello World\n"
</pre>

Save this source file as ''HelloWorld.s'' and open a shell window. Change directory to where ''HelloWorld.s'' was just saved and enter:

<pre>
vasmppc_std -Felf -o ram:hw.o HelloWorld.s
</pre>

Once again, because of the simplicity of this program, linking isn't necessary so just enter the following in the shell window:

<pre>
ram:hw.o
</pre>

Are you impressed? Feel free to modify, experiment with and improve this source code. A not-too-difficult challenge might be to change this program so that it prints the arguments given to it in the shell window - a number of small but significant changes would be needed to do this. ''Hint: Have another look at the System V.4 register usage above.''

The commented version of ''HelloWorld.s'' in the downloadable source archive gives a brief description of why the '''mtctr''' (move to Count Register) & '''bctrl''' (branch to Count Register and link) instruction pair are used in preference to '''mtlr''' (move to Link Register) & '''blrl''' (branch to Link Register and link) - being that the latter pair can degrade performance optimisations of some PPC cpus. However, the primary use of the Count Register is as a 32 bit loop counter that can be automatically decremented by certain branch instructions.

When choosing which registers to use in your own programs, be aware that use of '''r0''' in some instruction operands will not always work as you might expect. In these instructions, the actual content of '''r0''' is ignored and the result is based on the constant value zero instead. For example, imagine that '''r0''' contains the value 100 when this instruction is executed: '''addi r0,r0,50''' It looks like the result should be '''r0 = r0 + 50 = 150''' The result will actually be '''r0 = 0 + 50 = 50''' This may seem odd but, as long as the programmer is aware of it, this behaviour can be useful. A good PPC instruction reference manual will explain this, and many other things, in much greater detail. There are many of these reference documents available online - this is one of them: [http://www.freescale.com/files/product/doc/MPCFPE32B.pdf MPCFPE32B.pdf]

==MorphOS SDK, Objdump, ELFs & Sections==

In addition to installing vbcc, it is also recommended to install the [http://www.morphos-team.net/files/sdk-20100617.lha MorphOS SDK] and the [http://mail.pb-owl.de/~frank/vbcc/current/vbcc_target_ppc-morphos.lha vbcc MorphOS compiler target].

The installer script of the latter seems to expect that there is a pre-existing assign for ''include:'' and, if your system already assigns ''include:'' to somewhere, please skip over this next part.

What follows is my ''S:user-startup'' after the installation of vbcc, it's MorphOS compiler target and an additional assign that I made preceded by this comment -

''; vbcc MorphOS target needs include: to be assigned to somewhere''

<pre>
;
; MorphOS user-startup
;
; This script is executed on system boot by
; startup-sequence. You can make personal
; changes in here.
;
; $VER: user-startup 1.1
;

; Enable the following to mount the inet-handler. Note that TCP: allows
; easy access to internet, and allows scripts to listen for incoming
; connections. Some malware could abuse this.
;Mount TCP:
;BEGIN vbcc
assign >NIL: vbcc: SYS:vbcc
assign >NIL: C: vbcc:bin ADD
setenv VBCC vbcc:
;END vbcc

; vbcc MorphOS target needs include: to be assigned to somewhere
assign include: SDK:GG/os-include

;BEGIN vbcc-ppc-morphos
assign >NIL: vincludemos: vbcc:targets/ppc-morphos/include
assign >NIL: vincludemos: include: add
assign >NIL: vlibmos: vbcc:targets/ppc-morphos/lib
;END vbcc-ppc-morphos
</pre>

At this point it would be useful to have a number of freshly generated object files and executables to look at with ''objdump'' although any ELF can be used for this purpose. Note that while MorphOS 2.x system files are compiled as ELFs, they are also signed to prevent their use on MorphOS 1.x where they may not work. This signing also has the effect of causing ''objdump'' not to recognise them as ELFs.

''objdump'' can be used to reveal a lot of interesting information about an ELF including listing any symbols and sections that are present as well as disassembling. Be aware that, when disassembled, seemingly small programs can produce more output than the shell window's history buffer can hold so either redirect the output to a file or specify start and stop addresses to limit the output. Having said that, none of the files generated so far in this tutorial are at risk of overwhelming the shell's history buffer when disassembled.

''more content needed here''

As mentioned just before the previous source code example, some quick and dirty methods were used for the sake of simplicity and readability and this refers to the way library function offsets were established. The approach used will quickly become detrimental as more offsets are added. There are a number of solutions to this problem but only one will be presented here and it involves the removal of the leading underscore character from function names so that, for example, '''li r3,_LVOOpenLibrary''' becomes '''li r3,LVOOpenLibrary'''. Remove or comment out the first three '''.set''' directives that define the library function offsets and assemble with ''vasm'' as before but note that the resulting object file is no longer executable. To make this object executable, ''vlink'' is needed.

<pre>
vlink -o <desired executable name> <existing object name> -lamiga
</pre>

In the above shell command, ''-lamiga'' refers to the ''libamiga.a'' file that ''vlink'' knows to look for in ''vlibmos:'' This file contains information used to resolve many library function names to numerical values. Note that any executable generated from the above ''vlink'' command will contain a lot of symbol information that, while potentially useful, increases the size of the executable. This can be avoided with a few additions to the above command.

<pre>
vlink -s -P__abox__ -o <desired executable name> <existing object name> -lamiga
</pre>

'''-s''' strip all symbols from the output file 
'''-P<symbol>''' preserve this symbol 

For more information, please refer to the documentation for ''vlink'' and other programs installed with ''vbcc''.

An Introduction to MorphOS PPC Assembly

2011-01-22T09:33:20Z

AusPPC: The __abox__ symbol was incorrectly defined in the source example.

==Jump In The Deep End And Compile Something Right Now==

You could copy and paste but just entering the two lines below into a suitable text editor is probably quicker.

<pre>
.text
blr
</pre>

Save as ''shorty.s''

'''.text''' is an assembler directive - more about it later. '''blr''' is one of many branch instructions. This particular one means 'Branch to Link Register'. When a program terminates, this is the last instruction to be executed and it causes the sequence of instruction execution to pass back to the calling program or environment (shell, Ambient etc). Subroutines can also terminate with this instruction but, again, more about this later.

This is as good a time as any to ask if you've installed vbcc yet - if not, go and do it. [http://mail.pb-owl.de/~frank/vbcc/current/vbcc_bin_morphos.lha Download vbcc]

Once vbcc is installed, open a shell window and change directory to where shorty.s has been saved.

Enter:

<pre>
vasmppc_std -Felf -o ram:shorty.o shorty.s
</pre>

This tells vasm to generate an ELF formatted object file called ''shorty.o'' in ram: from the ''shorty.s'' source file.

==Hello? World's Shortest MorphOS Program - Or Is It?==

There are times when a linker is needed to further process an object file to generate an executable - this isn't one of those times.

Go ahead and enter this into the shell window:

<pre>
ram:shorty.o
</pre>

It will appear as if nothing happens - but at least it happens very quickly. However, something did happen. ''shorty.o'' was identified as an executable program and loaded into memory where the cpu instruction execution sequence passed to it. As mentioned above, the single '''blr''' instruction in this program caused the instruction execution sequence to pass directly back to where it was called from - in this case, the shell.

It may be of interest to know that all PPC instructions are four bytes long. In PPC nomenclature, this length is known as a '''word'''. But let's take a moment to have a look at the size of ''shorty.o''

Enter this into the shell window:

<pre>
list ram:shorty.o
</pre>

2664 bytes?! But this is typical for object files as they contain much additional information that is used in the process of debugging and linking. Linking, particularly with the '''-s''' 'strip all symbols' option, will generate an executable that is noticeably smaller.

Try entering this into the shell window:

<pre>
vlink -s -o ram:shorty ram:shorty.o

list ram:shorty
</pre>

The newly generated executable is 328 bytes - much smaller than its object file but what are those other 324 bytes doing there? They are the ELF 'container' that holds the single, four byte instruction of ''shorty''. ELF stands for Executable and Linkable Format and it is used by MorphOS, AmigaOS4 and AROS - not to forget, Linux, UNIX, BSD and even video game consoles. There is abundant information about this file format online but this topic will be discussed a little further when the use of the ''objdump'' program is introduced.

==The Old And The New==

Generally, in order to make a program that does something useful or to at least produce an observable result, it is necessary to use operating system library functions. Despite the markedly different cpu family that MorphOS runs on compared to the 68k family used by the classic AmigaOS, MorphOS is largely compatible with AmigaOS. This compatibility is reflected in a very similar API shared with AmigaOS and extends to using a MorphOS system structure as if it were the internal data and address registers of an actual 68k processor. This is called the EmulHandle structure and it is always available through the PPC GPR2 register. Also, as with 68k AmigaOS, the address of the Exec library base is always to be found at memory location 4. Many aspects of the AmigaOS API fit closely to the features available in the 68k cpu and the following code comparison should illustrate how it is echoed in the PPC MorphOS API.

A common task performed during the initialisation of many programs - opening the Dos library. It is a particularly simple example of library usage but most functions follow this form.

[[File:Old-and-new.png]]

'''@h''' '''@ha''' & '''@l''' attributes are needed to specify the high and low halfwords of 32 bit immediate values because the fixed 32 bit size of PPC instructions does not allow enough space for an instruction opcode and additional 32 bits of data. The difference between '''@h''' and '''@ha''' is due to the common use of the '''addi''' (add immediate) instruction, which only takes a signed immediate value, to provide the lower 16 bits of a 32 bit constant - such as an address. Sometimes these lower 16 bits will equate to a negative value and it is then that prior use of the '''@ha''' attribute will cause its immediate value to be adjusted to compensate. These details are only resolved before execution, when the program is loaded. The '''@h''' attribute just specifies the upper halfword of a 32 bit constant without regard for what follows. While I'm banging on about such intricacies, the meaning of ''zero'' in ''load word and zero'' of the '''lwz''' instruction is that on 64 bit PPC processors, this instruction will load a 32 bit value from memory into the lower word of a 64 bit GPR and then clear (or zero) its upper word. Something to consider when MorphOS is available on G5 class computers... 

One could be forgiven for thinking that the PPC code snippet looks a little ungainly compared to the former. Whereas every PPC instruction is four bytes long, 68k instructions can be as little as two bytes but up to as many as ten. A single 68k instruction can load a value from a 32 bit memory address specified by one instruction operand and store it at another 32 bit memory address specified by the second instruction operand. The 68k can also perform other operations beyond simple loads and stores directly on memory. Or at least appear to... In truth, computer memory only sends and receives data - no other data processing (like adding, subtracting & etc) occurs in memory. While the 68k instruction '''add.l #$12345678,(a0)''' appears to add the immediate value of it's first operand to whatever may already be stored at the address pointed to by a0, the contents of that address are actually loaded from memory into a private work register, the addition is performed and then the result is stored back to the same memory location. So this instruction actually performs two memory accesses where it might appear that there was only one. Contrast this with PPC assembly programming where memory loads and stores are all done explicitly. Before data can be operated upon it must be loaded from memory into a GPR (General Purpose Register), zero (in the case of a simple memory copy) or more operations can then be performed and then the data may be stored back to memory.

Unless you are brand-spanking-new to the topic of PPC assembly, you will already know that the PPC has 32 GPRs - r0 through r31. But did you know that the desired use of these registers is set out in something called the System V.4 ABI which MorphOS adheres to?

<pre>
r0 - volatile
r1 - stack pointer
r2 - for system use (with MorphOS, r2 points to the EmulHandle structure)

r3 - initialised with a pointer to a Dos command buffer
r4 - initialised with the length of the Dos command buffer
r5 - initialised with a pointer to an ELF structure

r3 ... r10 volatile & can be used to pass function arguments. If more
arguments are required, the stack is used.

r11 & r12 - volatile

r13 - small data area pointer. If this register is needed by a function or
subroutine, it must be saved first and then restored before
returning to where it was called from.

r14 ... r31 - No predefined purpose. If these registers are needed by a
function or subroutine, they must be saved first and then restored
before returning to where it was called from.
</pre>

The above use of the word 'volatile' means that functions are not expected to preserve the contents of these registers. r1 & r2 are the only registers that must be restored to their initial values by a terminating program, however, while most programs will modify r1 and later restore it, it is best to have not modified r2 in the first place.

This System V.4 ABI also sets out a particular way for programs and subroutines to organise their stack frames. When a program is loaded into memory and the instruction execution sequence passes to it, the stack pointer is still pointing to the calling program's stack frame and there is also an important address stored in the Link Register at this time. Unless this program is very simple (like ''shorty'') it must save the Link Register address and, most likely, create it's own stack frame. Somewhat conveniently, there is a special position in the caller's stack frame that a callee program can save the contents of the Link Register to. This is a fairly common example of a program or subroutine's very first instructions.

[[File:Awkward-program-initialisation.png]]

'Uh?' indeed... Let's try to visualise some memory being used as stack space.

[[File:Stack-diagram16.png]]

Note that '''stwu r1,-8(r1)''' creates a two-word stack frame which is the smallest stack that a program or subroutine can have if it, in turn, calls another program, subroutine or library function. More often, a larger stack frame is created although, '''stwu r1,-4(r1)''' could be used by a program or subroutine to create a one-word stack frame but this would be redundant and such a program must not call any other program, subroutine or library function. Such a program would not need to store the value in the Link Register (LR) to prevent it from being overwritten by subsequent calls and can terminate and return to it's caller with a simple '''blr''' instruction - just like ''shorty'' does.

A further note about larger stack frames and appropriate stack sizes: For reasons relating to PPC architecture, it is a good idea to choose stack frame sizes that are multiples of 16 bytes.

This is a less common example of a program's first instructions but it may better illustrate how to use stack frames.

[[File:Program-initialisation.png]]

Let's jump ahead and look at the last few instructions involved in program termination that would 'undo' the above instructions.

[[File:Program-termination.png]]

==A Little Less Talk And A Little More Action Please==

It's time to compile another program - this one will actually do something.

But wait...

Not another 'Hello World' program... I'm afraid so. This time, copy and paste is probably quicker. Alternatively, download this fully commented [http://aminet.net/dev/src/MorphOS-PPC-HelloWorld.lha source archive].

Note that this example does not use the MorphOS SDK. Instead, some 'quick and dirty' methods are used for the sake of simplicity and readability.

<pre>
# Various library function offsets
.set _LVOOpenLibrary,-552
.set _LVOCloseLibrary,-414
.set _LVOVPrintf,-954

.set _AbsExecBase,4

# EmulHandle structure (always pointed to by r2)
.set reg_d0,0
.set reg_d1,4
.set reg_d2,8
.set reg_d3,12
.set reg_d4,16
.set reg_d5,20
.set reg_d6,24
.set reg_d7,28
.set reg_a0,32
.set reg_a1,36
.set reg_a2,40
.set reg_a3,44
.set reg_a4,48
.set reg_a5,52
.set reg_a6,56
.set reg_a7,60
.set EmulCallDirectOS,100

# Stack frame offsets
.set stack_pos0_caller_stack,0
.set stack_pos1_callerLR,4
.set stack_pos2_ExecBase,8
.set stack_pos3_DosBase,12
.set new_4_word_stack,16

.text

mflr r0
stw r0,stack_pos1_callerLR(r1)
stwu r1,-new_4_word_stack(r1)

lis r3,dosName@ha
addi r3,r3,dosName@l
stw r3,reg_a1(r2)
li r3,0
stw r3,reg_d0(r2)
li r3,_AbsExecBase
lwz r3,0(r3)
stw r3,stack_pos2_ExecBase(r1)
stw r3,reg_a6(r2)
li r3,_LVOOpenLibrary
lwz r0,EmulCallDirectOS(r2)
mtctr r0
bctrl

cmpwi r3,0
beq exit

stw r3,stack_pos3_DosBase(r1)

lis r4,string1@ha
addi r4,r4,string1@l
stw r4,reg_d1(r2)
li r4,0
stw r4,reg_d2(r2)
stw r3,reg_a6(r2)
li r3,_LVOVPrintf
lwz r0,EmulCallDirectOS(r2)
mtctr r0
bctrl

lwz r3,stack_pos3_DosBase(r1)
stw r3,reg_a1(r2)
lwz r3,stack_pos2_ExecBase(r1)
stw r3,reg_a6(r2)
li r3,_LVOCloseLibrary
lwz r0,EmulCallDirectOS(r2)
mtctr r0
bctrl

li r3,0

exit: addi r1,r1,new_4_word_stack
lwz r0,stack_pos1_callerLR(r1)
mtlr r0
blr

.rodata

.global __abox__ #__abox__ is a special MorphOS symbol that will
__abox__: #differentiate this program from other PPC
.word 1 #executables that can run on MorphOS...
.type __abox__,@object #When linking, care should be taken
.size __abox__,4 #to avoid stripping this symbol.

dosName:
.string "dos.library"

string1:
.string "Hello World\n"
</pre>

Save this source file as ''HelloWorld.s'' and open a shell window. Change directory to where ''HelloWorld.s'' was just saved and enter:

<pre>
vasmppc_std -Felf -o ram:hw.o HelloWorld.s
</pre>

Once again, because of the simplicity of this program, linking isn't necessary so just enter the following in the shell window:

<pre>
ram:hw.o
</pre>

Are you impressed? Feel free to modify, experiment with and improve this source code. A not-too-difficult challenge might be to change this program so that it prints the arguments given to it in the shell window - a number of small but significant changes would be needed to do this. ''Hint: Have another look at the System V.4 register usage above.''

The commented version of ''HelloWorld.s'' in the downloadable source archive gives a brief description of why the '''mtctr''' (move to Count Register) & '''bctrl''' (branch to Count Register and link) instruction pair are used in preference to '''mtlr''' (move to Link Register) & '''blrl''' (branch to Link Register and link) - being that the latter pair can degrade performance optimisations of some PPC cpus. However, the primary use of the Count Register is as a 32 bit loop counter that can be automatically decremented by certain branch instructions.

When choosing which registers to use in your own programs, be aware that use of '''r0''' in some instruction operands will not always work as you might expect. In these instructions, the actual content of '''r0''' is ignored and the result is based on the constant value zero instead. For example, imagine that '''r0''' contains the value 100 when this instruction is executed: '''addi r0,r0,50''' It looks like the result should be '''r0 = r0 + 50 = 150''' The result will actually be '''r0 = 0 + 50 = 50''' This may seem odd but, as long as the programmer is aware of it, this behaviour can be useful. A good PPC instruction reference manual will explain this, and many other things, in much greater detail. There are many of these reference documents available online - this is one of them: [http://www.freescale.com/files/product/doc/MPCFPE32B.pdf MPCFPE32B.pdf]

==MorphOS SDK, Objdump, ELFs & Sections==

In addition to installing vbcc, it is also recommended to install the [http://www.morphos-team.net/files/sdk-20100617.lha MorphOS SDK] and the [http://mail.pb-owl.de/~frank/vbcc/current/vbcc_target_ppc-morphos.lha vbcc MorphOS compiler target].

The installer script of the latter seems to expect that there is a pre-existing assign for ''include:'' and, if your system already assigns ''include:'' to somewhere, please skip over this next part.

What follows is my ''S:user-startup'' after the installation of vbcc, it's MorphOS compiler target and an additional assign that I made preceded by this comment -

''; vbcc MorphOS target needs include: to be assigned to somewhere''

<pre>
;
; MorphOS user-startup
;
; This script is executed on system boot by
; startup-sequence. You can make personal
; changes in here.
;
; $VER: user-startup 1.1
;

; Enable the following to mount the inet-handler. Note that TCP: allows
; easy access to internet, and allows scripts to listen for incoming
; connections. Some malware could abuse this.
;Mount TCP:
;BEGIN vbcc
assign >NIL: vbcc: SYS:vbcc
assign >NIL: C: vbcc:bin ADD
setenv VBCC vbcc:
;END vbcc

; vbcc MorphOS target needs include: to be assigned to somewhere
assign include: SDK:GG/os-include

;BEGIN vbcc-ppc-morphos
assign >NIL: vincludemos: vbcc:targets/ppc-morphos/include
assign >NIL: vincludemos: include: add
assign >NIL: vlibmos: vbcc:targets/ppc-morphos/lib
;END vbcc-ppc-morphos
</pre>

At this point it would be useful to have a number of freshly generated object files and executables to look at with ''objdump'' although any ELF can be used for this purpose. Note that while MorphOS 2.x system files are compiled as ELFs, they are also signed to prevent their use on MorphOS 1.x where they may not work. This signing also has the effect of causing ''objdump'' not to recognise them as ELFs.

''objdump'' can be used to reveal a lot of interesting information about an ELF including listing any symbols and sections that are present as well as disassembling. Be aware that, when disassembled, seemingly small programs can produce more output than the shell window's history buffer can hold so either redirect the output to a file or specify start and stop addresses to limit the output. Having said that, none of the files generated so far in this tutorial are at risk of overwhelming the shell's history buffer when disassembled.

''more content needed here''

As mentioned just before the previous source code example, some quick and dirty methods were used for the sake of simplicity and readability and this refers to the way library function offsets were established. The approach used will quickly become detrimental as more offsets are added. There are a number of solutions to this problem but only one will be presented here and it involves the removal of the leading underscore character from function names so that, for example, '''li r3,_LVOOpenLibrary''' becomes '''li r3,LVOOpenLibrary'''. Remove or comment out the first three '''.set''' directives that define the library function offsets and assemble with ''vasm'' as before but note that the resulting object file is no longer executable. To make this object executable, ''vlink'' is needed.

<pre>
vlink -o <desired executable name> <existing object name> -lamiga
</pre>

In the above shell command, ''-lamiga'' refers to the ''libamiga.a'' file that ''vlink'' knows to look for in ''vlibmos:'' This file contains information used to resolve many library function names to numerical values. Note that any executable generated from the above ''vlink'' command will contain a lot of symbol information that, while potentially useful, increases the size of the executable. This can be avoided with a few additions to the above command.

<pre>
vlink -s -P__abox__ -o <desired executable name> <existing object name> -lamiga
</pre>

'''-s''' strip all symbols from the output file 
'''-P<symbol>''' preserve this symbol 

For more information, please refer to the documentation for ''vlink'' and other programs installed with ''vbcc''.

Text Class: Buttons, Textfields, Labels

2011-01-07T07:34:20Z

AusPPC: /* Buttons */

''Grzegorz Kraszewski''

==Introduction==
The ''Text'' class is the most commonly used one for creating gadgets. This is because it not only creates plain labels (also called "static text" in other GUI engines), but also framed read-only text gadgets and textual buttons. In fact MUI has no special class for buttons, a button is just a ''Text'' object with a proper frame and background and user input activated. This versatility can have the disadvantage of allowing for creation of style guide nonconforming interfaces.

The ''Text'' class uses the [[MUI Text Rendering Engine]] for text output. It allows for multiline text, using styles (bold, italic), colors and inlined images. These features should be used sparingly to keep user interfaces consistent and comfortable to use. The rendering engine is controlled by inserting escape sequences in the text. Another engine feature is aligning the text inside the object rectangle (left, right, centered).

==Common Attributes==

*'''''MUIA_Background''''' and '''''MUIA_Frame''''' are attributes inherited from the ''Area'' class. They specify a background and frame used for an object.
*'''''MUIA_Text_Contents''''' specifies the text. It may contain formatting engine escape sequences. The text is buffered internally, so the value of this attribute may point to a local variable or a dynamically allocated buffer.
*'''''MUIA_Text_PreParse''''' may be considered a fixed prefix, which is always added at the start of text before rendering. It is usually used for applying constant styles and formatting, for example setting it to "\33c" will always center the text. This attribute simplifies text handling when the text displayed is not constant (for example is loaded from a locale catalog).
*'''''MUIA_Font''''' is another attribute inherited from the ''Area'' class and specifies a font to be used for text rendering. In most cases it is one of the fonts predefined by the user in MUI settings.

For more attributes and detailed descriptions refer to the ''Text'' class autodoc in the SDK.

==Labels==

Labels are the simplest form of ''Text'' instances. They have no frame and inherit their background from the parent object (neither ''MUIA_Frame'' nor ''MUIA_Background'' is specified). They use the standard MUI font in most cases, so ''MUIA_Font'' does not need to be specified either. An important (and often forgotten) detail is a proper text baseline align when a label is used with some framed gadget also containing text (a ''String'' gadget for example). The default MUI behaviour for vertical text positioning is to center it. If the framed gadget uses uneven vertical padding, baselines of the label and the gadget may be unaligned. A special attribute ''MUIA_FramePhantomHoriz'' solves this problem. It is specified for a label with a ''TRUE'' value. The label also has ''MUIA_Frame'' specified with the same frame type as the gadget. Then the label gets an invisible frame of this type (frame horizontal parts to be exact, hence the attribute name) and the text is laid out accordingly. As a result the label and the gadget text are always aligned vertically, assuming they use the same font.

[[File:Label_align.png|center]]

The magnified screenshot above illustrates the label align problem. The string gadget uses uneven padding (top padding is 2 pixels, bottom padding is 0 pixels), which causes the text baseline to misalign by 1 pixel shown on the left. The label on the right has been defined with two additional tags:

MUIA_FramePhantomHoriz, TRUE,
MUIA_Frame, MUIV_Frame_String,

A label can have one character underlined with the ''MUIA_Text_HiChar'' attribute. It is used to create a visual hint for a hotkey of a labeled gadget. See [[#Buttons|Buttons]] section below for details.

==Textfields==

A textfield is a read-only framed area showing some (usually changing at runtime) text. The difference between a label and a textfield is that the latter has a frame and a background specified:

MUIA_Frame, MUIV_Frame_Text,
MUIA_Background, MUII_TextBack,

==Buttons==
A text button is an instance of the ''Text'' class too. It has more attributes than a plain label however, because it handles user input. MUI has a predefined background and frame for buttons:

MUIA_Frame, MUIV_Frame_Button,
MUIA_Background, MUII_ButtonBack,

These attributes also specify a frame and background for the "pressed" state. MUI also has separate font settings for buttons. Forgetting the ''MUIA_Font'' attribute for buttons is one of most common errors in MUI design.

MUIA_Font, MUIV_Font_Button,

Many users (and programmers) just have the default font defined for buttons, so the bug is not visible. It is recommended to always test a GUI with some unusual font settings for buttons, so the problem is easily visible. Button text is usually centered, which may be done either by inserting the "\33c" sequence at the start of the button label, or using ''MUIA_Text_PreParse''.

MUIA_Text_PreParse, "\33c",

After definition of the button appearance it is time to handle user input. The button behaviour is defined by the ''MUIA_InputMode'' attribute with three values:
*'''''MUIV_InputMode_None''''' – The default value, button does not react on anything.
*'''''MUIV_InputMode_RelVerify''''' – A simple pushbutton activated by a left mouse button click.
*'''''MUIV_InputMode_Toggle''''' – A two-state button, one click switches it on, another one switches it off.

Another common bug with MUI buttons is to omit keyboard handling. The mouse is not everything. The first, obligatory step is to enter the button into the window's TAB key cycle chain:

MUIA_CycleChain, TRUE,

Any gadget entered into the chain may be selected by pressing the TAB key (for default MUI keyboard settings). The selected object has a special frame drawn around it. Then it may be activated by some key set in MUI preferences. For buttons the default "pressing" key is the return key. A rule of thumb for cycle chaining:

<big><center>'''Every''' gadget accepting user input '''must''' be added to the TAB cycle chain.</center></big>

Another keyboard handling feature provided by MUI is hotkeys. A hotkey just activates a button associated to it. Hotkeys have the following features:
*MUI provides a visual hint of a button hotkey by underlining the hotkey letter in the button label. It implies that the hotkey letter must exist in the label.
*There is visual feedback for using a hotkey, the button is pressed as if it has been clicked with the mouse.
Not every button in a GUI has to have a hotkey. The best practice is to assign hotkeys only for the most used buttons, especially if there are many buttons in a window. A hotkey is defined with two attributes:
*'''''MUIA_Text_HiChar''''' – this attribute specifies a letter to be underlined in the label. It is case insensitive.
*'''''MUIA_ControlChar''''' – this attribute specifies a hotkey. Of course it should be the same as the above one. It should be a lowercase letter, as uppercase forces a user to press SHIFT, making the hotkey less comfortable to use. There is also no visual hint for SHIFT requirement. Digits may be also used as hotkeys if the label contains them. Using punctuation and other characters should be avoided. An example of use:

MUIA_Text_Contents, "Destroy All",
MUIA_Text_HiChar, 'a',
MUIA_Text_ControlChar, 'a'

Note that these attributes take a single char, not a string.

Text Class: Buttons, Textfields, Labels

2011-01-07T07:26:08Z

AusPPC: /* Labels */

''Grzegorz Kraszewski''

==Introduction==
The ''Text'' class is the most commonly used one for creating gadgets. This is because it not only creates plain labels (also called "static text" in other GUI engines), but also framed read-only text gadgets and textual buttons. In fact MUI has no special class for buttons, a button is just a ''Text'' object with a proper frame and background and user input activated. This versatility can have the disadvantage of allowing for creation of style guide nonconforming interfaces.

The ''Text'' class uses the [[MUI Text Rendering Engine]] for text output. It allows for multiline text, using styles (bold, italic), colors and inlined images. These features should be used sparingly to keep user interfaces consistent and comfortable to use. The rendering engine is controlled by inserting escape sequences in the text. Another engine feature is aligning the text inside the object rectangle (left, right, centered).

==Common Attributes==

*'''''MUIA_Background''''' and '''''MUIA_Frame''''' are attributes inherited from the ''Area'' class. They specify a background and frame used for an object.
*'''''MUIA_Text_Contents''''' specifies the text. It may contain formatting engine escape sequences. The text is buffered internally, so the value of this attribute may point to a local variable or a dynamically allocated buffer.
*'''''MUIA_Text_PreParse''''' may be considered a fixed prefix, which is always added at the start of text before rendering. It is usually used for applying constant styles and formatting, for example setting it to "\33c" will always center the text. This attribute simplifies text handling when the text displayed is not constant (for example is loaded from a locale catalog).
*'''''MUIA_Font''''' is another attribute inherited from the ''Area'' class and specifies a font to be used for text rendering. In most cases it is one of the fonts predefined by the user in MUI settings.

For more attributes and detailed descriptions refer to the ''Text'' class autodoc in the SDK.

==Labels==

Labels are the simplest form of ''Text'' instances. They have no frame and inherit their background from the parent object (neither ''MUIA_Frame'' nor ''MUIA_Background'' is specified). They use the standard MUI font in most cases, so ''MUIA_Font'' does not need to be specified either. An important (and often forgotten) detail is a proper text baseline align when a label is used with some framed gadget also containing text (a ''String'' gadget for example). The default MUI behaviour for vertical text positioning is to center it. If the framed gadget uses uneven vertical padding, baselines of the label and the gadget may be unaligned. A special attribute ''MUIA_FramePhantomHoriz'' solves this problem. It is specified for a label with a ''TRUE'' value. The label also has ''MUIA_Frame'' specified with the same frame type as the gadget. Then the label gets an invisible frame of this type (frame horizontal parts to be exact, hence the attribute name) and the text is laid out accordingly. As a result the label and the gadget text are always aligned vertically, assuming they use the same font.

[[File:Label_align.png|center]]

The magnified screenshot above illustrates the label align problem. The string gadget uses uneven padding (top padding is 2 pixels, bottom padding is 0 pixels), which causes the text baseline to misalign by 1 pixel shown on the left. The label on the right has been defined with two additional tags:

MUIA_FramePhantomHoriz, TRUE,
MUIA_Frame, MUIV_Frame_String,

A label can have one character underlined with the ''MUIA_Text_HiChar'' attribute. It is used to create a visual hint for a hotkey of a labeled gadget. See [[#Buttons|Buttons]] section below for details.

==Textfields==

A textfield is a read-only framed area showing some (usually changing at runtime) text. The difference between a label and a textfield is that the latter has a frame and a background specified:

MUIA_Frame, MUIV_Frame_Text,
MUIA_Background, MUII_TextBack,

==Buttons==
A text button is an instance of the ''Text'' class too. It has more attributes than a plain label however, because it handles user input. MUI has a predefined background and frame for buttons:

MUIA_Frame, MUIV_Frame_Button,
MUIA_Background, MUII_ButtonBack,

These attributes specify also frame and background for "pressed" state. MUI has also a separate font settings for buttons. Forgetting ''MUIA_Font'' attribute for buttons is one of most common errors in MUI design.

MUIA_Font, MUIV_Font_Button,

Many users (and programmers) have just the default font defined for buttons, so the bug is not visible. It is recommended to always check a GUI with some unusual font settings for buttons, so the problem is easily visible. Button text is usually centered, which may be done either by inserting "\33c" sequence at the start of button label, or using ''MUIA_Text_PreParse''.

MUIA_Text_PreParse, "\33c",

After definition of the button appearance it is time to handle user input. The button behaviour is defined by ''MUIA_InputMode'' attribute with three values:
*'''''MUIV_InputMode_None''''' – The default value, button does not react on anything.
*'''''MUIV_InputMode_RelVerify''''' – A simple pushbutton activated by a left mouse button click.
*'''''MUIV_InputMode_Toggle''''' – A two-state button, one click switches it on, another one switches off.

Another common bug with MUI buttons is to ommit keyboard handling. Mouse is not everything. The first, obligatory step is to enter the button into the window's TAB key cycle chain:

MUIA_CycleChain, TRUE,

Any gadget entered into the chain may be selected by pressing the TAB key (for default MUI keyboard settings). The selected object has a special frame drawn around it. Then it may be activated by some key set in MUI preferences. For buttons the default "pressing" key is the return key. A rule of thumb for cycle chaining:

<big><center>'''Every''' gadget accepting user input '''must''' be added to the TAB cycle chain.</center></big>

Another keyboard handling feature provided by MUI are hotkeys. A hotkey just activates a button associated to it. Hotkeys have following features:
*MUI provides a visual hint of a button hotkey by underlining the hotkey letter in the button label. It implies that the hotkey letter must exist in the label.
*There is a visual feedback of using a hotkey, the button is pressed as if it has been clicked with the mouse.
Not every button in a GUI has to have a hotkey. The best practice is to assign hotkeys only for most used buttons, especially if there are many buttons in a window. A hotkey is defined with two attributes:
*'''''MUIA_Text_HiChar''''' – this attribute specifies a letter to be underlined in the label. It is case insensitive.
*'''''MUIA_ControlChar''''' – this attribute specifies a hotkey. Of course it should be the same as the above one. It should be a lowercase letter, as uppercase forces a user to press SHIFT, making the hotkey less comfortable. There is also no visual hint for SHIFT requirement. Digits may be also used as hotkeys if the label contains them. Using punctuation and other characters should be avoided. An example of use:

MUIA_Text_Contents, "Destroy All",
MUIA_Text_HiChar, 'a',
MUIA_Text_ControlChar, 'a'

Note that these attributes take a single char, not a string.

Text Class: Buttons, Textfields, Labels

2011-01-07T07:19:50Z

AusPPC: /* Common Attributes */

''Grzegorz Kraszewski''

==Introduction==
The ''Text'' class is the most commonly used one for creating gadgets. This is because it not only creates plain labels (also called "static text" in other GUI engines), but also framed read-only text gadgets and textual buttons. In fact MUI has no special class for buttons, a button is just a ''Text'' object with a proper frame and background and user input activated. This versatility can have the disadvantage of allowing for creation of style guide nonconforming interfaces.

The ''Text'' class uses the [[MUI Text Rendering Engine]] for text output. It allows for multiline text, using styles (bold, italic), colors and inlined images. These features should be used sparingly to keep user interfaces consistent and comfortable to use. The rendering engine is controlled by inserting escape sequences in the text. Another engine feature is aligning the text inside the object rectangle (left, right, centered).

==Common Attributes==

*'''''MUIA_Background''''' and '''''MUIA_Frame''''' are attributes inherited from the ''Area'' class. They specify a background and frame used for an object.
*'''''MUIA_Text_Contents''''' specifies the text. It may contain formatting engine escape sequences. The text is buffered internally, so the value of this attribute may point to a local variable or a dynamically allocated buffer.
*'''''MUIA_Text_PreParse''''' may be considered a fixed prefix, which is always added at the start of text before rendering. It is usually used for applying constant styles and formatting, for example setting it to "\33c" will always center the text. This attribute simplifies text handling when the text displayed is not constant (for example is loaded from a locale catalog).
*'''''MUIA_Font''''' is another attribute inherited from the ''Area'' class and specifies a font to be used for text rendering. In most cases it is one of the fonts predefined by the user in MUI settings.

For more attributes and detailed descriptions refer to the ''Text'' class autodoc in the SDK.

==Labels==

Labels are the simplest form of ''Text'' instances. They have no frame and inherit their background from the parent object (neither ''MUIA_Frame'' nor ''MUIA_Background'' is specified). They use the standard MUI font in most cases, so ''MUIA_Font'' needs not to be specified too. An important (and often forgotten) detail is a proper text baseline align when a label is used with some framed gadget containing text as well (a ''String'' gadget for example). The default MUI behaviour for vertical text positioning is to center it. If the framed gadget uses uneven vertical padding, baselines of the label and the gadget may be unaligned. A special attribute ''MUIA_FramePhantomHoriz'' solves this problem. It is specified for a label with ''TRUE'' value. The label has also ''MUIA_Frame'' specified with the same frame type as the gadget. Then the label gets an invisible frame of this type (frame horizontal parts to be exact, hence the attribute name) and the text is layouted accordingly. As a result the label and the gadget text are always aligned vertically, assuming they use the same font.

[[File:Label_align.png|center]]

The magnified screenshot above illustrates the label align problem. The string gadget uses uneven padding (top padding is 2 pixels, bottom padding is 0 pixels), which causes text baseline misalign by 1 pixel shown on the left. The label on the right has been defined with two additional tags:

MUIA_FramePhantomHoriz, TRUE,
MUIA_Frame, MUIV_Frame_String,

A label can have one character underlined with ''MUIA_Text_HiChar'' attribute. It is used to create a visual hint for a hotkey of labelled gadget. See [[#Buttons|Buttons]] section below for details.

==Textfields==

A textfield is a read-only framed area showing some (usually changing at runtime) text. The difference between a label and a textfield is that the latter has a frame and a background specified:

MUIA_Frame, MUIV_Frame_Text,
MUIA_Background, MUII_TextBack,

==Buttons==
A text button is an instance of the ''Text'' class too. It has more attributes than a plain label however, because it handles user input. MUI has a predefined background and frame for buttons:

MUIA_Frame, MUIV_Frame_Button,
MUIA_Background, MUII_ButtonBack,

These attributes specify also frame and background for "pressed" state. MUI has also a separate font settings for buttons. Forgetting ''MUIA_Font'' attribute for buttons is one of most common errors in MUI design.

MUIA_Font, MUIV_Font_Button,

Many users (and programmers) have just the default font defined for buttons, so the bug is not visible. It is recommended to always check a GUI with some unusual font settings for buttons, so the problem is easily visible. Button text is usually centered, which may be done either by inserting "\33c" sequence at the start of button label, or using ''MUIA_Text_PreParse''.

MUIA_Text_PreParse, "\33c",

After definition of the button appearance it is time to handle user input. The button behaviour is defined by ''MUIA_InputMode'' attribute with three values:
*'''''MUIV_InputMode_None''''' – The default value, button does not react on anything.
*'''''MUIV_InputMode_RelVerify''''' – A simple pushbutton activated by a left mouse button click.
*'''''MUIV_InputMode_Toggle''''' – A two-state button, one click switches it on, another one switches off.

Another common bug with MUI buttons is to ommit keyboard handling. Mouse is not everything. The first, obligatory step is to enter the button into the window's TAB key cycle chain:

MUIA_CycleChain, TRUE,

Any gadget entered into the chain may be selected by pressing the TAB key (for default MUI keyboard settings). The selected object has a special frame drawn around it. Then it may be activated by some key set in MUI preferences. For buttons the default "pressing" key is the return key. A rule of thumb for cycle chaining:

<big><center>'''Every''' gadget accepting user input '''must''' be added to the TAB cycle chain.</center></big>

Another keyboard handling feature provided by MUI are hotkeys. A hotkey just activates a button associated to it. Hotkeys have following features:
*MUI provides a visual hint of a button hotkey by underlining the hotkey letter in the button label. It implies that the hotkey letter must exist in the label.
*There is a visual feedback of using a hotkey, the button is pressed as if it has been clicked with the mouse.
Not every button in a GUI has to have a hotkey. The best practice is to assign hotkeys only for most used buttons, especially if there are many buttons in a window. A hotkey is defined with two attributes:
*'''''MUIA_Text_HiChar''''' – this attribute specifies a letter to be underlined in the label. It is case insensitive.
*'''''MUIA_ControlChar''''' – this attribute specifies a hotkey. Of course it should be the same as the above one. It should be a lowercase letter, as uppercase forces a user to press SHIFT, making the hotkey less comfortable. There is also no visual hint for SHIFT requirement. Digits may be also used as hotkeys if the label contains them. Using punctuation and other characters should be avoided. An example of use:

MUIA_Text_Contents, "Destroy All",
MUIA_Text_HiChar, 'a',
MUIA_Text_ControlChar, 'a'

Note that these attributes take a single char, not a string.

Text Class: Buttons, Textfields, Labels

2011-01-07T07:17:18Z

AusPPC: /* Introduction */

''Grzegorz Kraszewski''

==Introduction==
The ''Text'' class is the most commonly used one for creating gadgets. This is because it not only creates plain labels (also called "static text" in other GUI engines), but also framed read-only text gadgets and textual buttons. In fact MUI has no special class for buttons, a button is just a ''Text'' object with a proper frame and background and user input activated. This versatility can have the disadvantage of allowing for creation of style guide nonconforming interfaces.

The ''Text'' class uses the [[MUI Text Rendering Engine]] for text output. It allows for multiline text, using styles (bold, italic), colors and inlined images. These features should be used sparingly to keep user interfaces consistent and comfortable to use. The rendering engine is controlled by inserting escape sequences in the text. Another engine feature is aligning the text inside the object rectangle (left, right, centered).

==Common Attributes==

*'''''MUIA_Background''''' and '''''MUIA_Frame''''' are attributes inherited from the ''Area'' class. They specify a background and frame used for an object.
*'''''MUIA_Text_Contents''''' specifies the text. It may contain formatting engine escape sequences. The text is buffered internally, so the value of this attribute may point to a local variable or a dynamically allocated buffer.
*'''''MUIA_Text_PreParse''''' may be considered a fixed prefix, which is always added at the start of text before rendering. It is usually used for applying a constant styles and formatting, for example setting it to "\33c" will always center the text. This attribute simplifies text handling when the text displayed is not constant (for example is loaded from a locale catalog).
*'''''MUIA_Font''''' is another attribute inherited from the ''Area'' class and specifies a font to be used for text rendeding. In most cases it is one of fonts predefined by user in MUI settings.

For more attributes and detailed descriptions refer to the ''Text'' class autodoc in the SDK.

==Labels==

Labels are the simplest form of ''Text'' instances. They have no frame and inherit their background from the parent object (neither ''MUIA_Frame'' nor ''MUIA_Background'' is specified). They use the standard MUI font in most cases, so ''MUIA_Font'' needs not to be specified too. An important (and often forgotten) detail is a proper text baseline align when a label is used with some framed gadget containing text as well (a ''String'' gadget for example). The default MUI behaviour for vertical text positioning is to center it. If the framed gadget uses uneven vertical padding, baselines of the label and the gadget may be unaligned. A special attribute ''MUIA_FramePhantomHoriz'' solves this problem. It is specified for a label with ''TRUE'' value. The label has also ''MUIA_Frame'' specified with the same frame type as the gadget. Then the label gets an invisible frame of this type (frame horizontal parts to be exact, hence the attribute name) and the text is layouted accordingly. As a result the label and the gadget text are always aligned vertically, assuming they use the same font.

[[File:Label_align.png|center]]

The magnified screenshot above illustrates the label align problem. The string gadget uses uneven padding (top padding is 2 pixels, bottom padding is 0 pixels), which causes text baseline misalign by 1 pixel shown on the left. The label on the right has been defined with two additional tags:

MUIA_FramePhantomHoriz, TRUE,
MUIA_Frame, MUIV_Frame_String,

A label can have one character underlined with ''MUIA_Text_HiChar'' attribute. It is used to create a visual hint for a hotkey of labelled gadget. See [[#Buttons|Buttons]] section below for details.

==Textfields==

A textfield is a read-only framed area showing some (usually changing at runtime) text. The difference between a label and a textfield is that the latter has a frame and a background specified:

MUIA_Frame, MUIV_Frame_Text,
MUIA_Background, MUII_TextBack,

==Buttons==
A text button is an instance of the ''Text'' class too. It has more attributes than a plain label however, because it handles user input. MUI has a predefined background and frame for buttons:

MUIA_Frame, MUIV_Frame_Button,
MUIA_Background, MUII_ButtonBack,

These attributes specify also frame and background for "pressed" state. MUI has also a separate font settings for buttons. Forgetting ''MUIA_Font'' attribute for buttons is one of most common errors in MUI design.

MUIA_Font, MUIV_Font_Button,

Many users (and programmers) have just the default font defined for buttons, so the bug is not visible. It is recommended to always check a GUI with some unusual font settings for buttons, so the problem is easily visible. Button text is usually centered, which may be done either by inserting "\33c" sequence at the start of button label, or using ''MUIA_Text_PreParse''.

MUIA_Text_PreParse, "\33c",

After definition of the button appearance it is time to handle user input. The button behaviour is defined by ''MUIA_InputMode'' attribute with three values:
*'''''MUIV_InputMode_None''''' – The default value, button does not react on anything.
*'''''MUIV_InputMode_RelVerify''''' – A simple pushbutton activated by a left mouse button click.
*'''''MUIV_InputMode_Toggle''''' – A two-state button, one click switches it on, another one switches off.

Another common bug with MUI buttons is to ommit keyboard handling. Mouse is not everything. The first, obligatory step is to enter the button into the window's TAB key cycle chain:

MUIA_CycleChain, TRUE,

Any gadget entered into the chain may be selected by pressing the TAB key (for default MUI keyboard settings). The selected object has a special frame drawn around it. Then it may be activated by some key set in MUI preferences. For buttons the default "pressing" key is the return key. A rule of thumb for cycle chaining:

<big><center>'''Every''' gadget accepting user input '''must''' be added to the TAB cycle chain.</center></big>

Another keyboard handling feature provided by MUI are hotkeys. A hotkey just activates a button associated to it. Hotkeys have following features:
*MUI provides a visual hint of a button hotkey by underlining the hotkey letter in the button label. It implies that the hotkey letter must exist in the label.
*There is a visual feedback of using a hotkey, the button is pressed as if it has been clicked with the mouse.
Not every button in a GUI has to have a hotkey. The best practice is to assign hotkeys only for most used buttons, especially if there are many buttons in a window. A hotkey is defined with two attributes:
*'''''MUIA_Text_HiChar''''' – this attribute specifies a letter to be underlined in the label. It is case insensitive.
*'''''MUIA_ControlChar''''' – this attribute specifies a hotkey. Of course it should be the same as the above one. It should be a lowercase letter, as uppercase forces a user to press SHIFT, making the hotkey less comfortable. There is also no visual hint for SHIFT requirement. Digits may be also used as hotkeys if the label contains them. Using punctuation and other characters should be avoided. An example of use:

MUIA_Text_Contents, "Destroy All",
MUIA_Text_HiChar, 'a',
MUIA_Text_ControlChar, 'a'

Note that these attributes take a single char, not a string.

Locating Objects in the Object Tree

2011-01-07T06:53:09Z

AusPPC:

After the complete object tree is created, there is no direct access to any object except the main ''Application'' object. A way to access other objects is needed. There are a few ways to do this:
* Storing pointers to objects in global variables. This is the simplest way and may work well in simple projects. The disadvantage is it breaks object oriented design principles (like data encapsulation) and creates a mess when the number of global variables reaches 50, 100 or more.
* Store pointers in fields of some subclass instance data (for example the ''Application'' instance). A good idea, but a bit tedious to implement. An object's instance data area does not exist until the object is fully created and the ''Application'' object is created as the last one. Then pointers to subobjects have to be stored in some temporary variables. This technique also requires that a parent object of the cached one is an instance of a custom (subclassed) class and the parent creates its subobjects inside the constructor, which is not always true.
* Use the ''MUIA_UserData'' attribute and the ''MUIM_FindUData()'' method to find objects dynamically. This is the best solution when objects are accessed rarely (for example once, just to set notifications). For frequently accessed objects (let's say several times a second) it may be combined with caching objects' pointers in an instance data of some subclassed object.
The last approach works as follows: every object to be searched has the ''MUIA_UserData'' attribute set to some predefined unique value. Then at any time the object may be found by this value using the ''MUIM_FindUData()'' method on a direct or indirect parent object, for example on the master ''Application'' object.

#define OBJ_SOME_BUTTON 36

/* Somewhere in the initial tags for the button */
MUIA_UserData, OBJ_SOME_BUTTON,
/* ... */

/* Let's get the pointer to the button now */

Object *some_button;

some_button = (Object*)DoMethod(App, MUIM_FindUData, OBJ_SOME_BUTTON);

This operation is so common that it is usually encapsulated in a macro:

#define findobj(id, parent) (Object*)DoMethod(parent, MUIM_FindUData, id)

some_button = findobj(OBJ_SOME_BUTTON, App);

The macro may of course be used directly in other functions, like in this example changing the button label:

set(findobj(OBJ_SOME_BUTTON, App), MUIA_Text_Contents, "Press Me");

Note that the ''findobj()'' macro is not defined in the system MUI headers, so it should be defined in the application code.

MUI Subclassing Tutorial: SciMark2 Port

2011-01-07T06:47:05Z

AusPPC: /* Implementing Functionality */

''Grzegorz Kraszewski''

==The Application==
Many programming tutorials tend to bore readers with some useless examples. In this one a "real world" application will be ported to MorphOS and "MUI-fied". The application is [http://math.nist.gov/scimark2/index.html SciMark 2]. SciMark is yet another CPU/memory benchmark. It performs some typical scientific calculations like Fast Fourier Transform, matrix LU decomposition, sparse matrix multiplication and so on. The benchmark measures mainly CPU speed at floating point calculations, cache efficiency and memory speed. Being written in Java initially, it has been rewritten in C (and in fact in many other languages). The C source is available on the [http://math.nist.gov/scimark2/download_c.html project homepage].

The source uses only the pure ANSI C standard, so it is easily compilable on MorphOS using the provided ''Makefile''. One has just to replace the ''$CC = cc'' line to ''$CC = gcc'', to match the name of the MorphOS compiler. As a result, a typical shell-based application is obtained. Here are example results for a Pegasos 2 machine with G4 processor:

[[File: scimark_cli_noopt.png|center]]

Not very impressive in fact. This is because no optimizaton flags are passed to the compiler in the makefile. They can be added by inserting the line ''$CFLAGS = -O3'' below the ''$CC = gcc'' line. Let's also link with ''libnix'' (a statically linked unix environment emulation, see [[Installation_of_Software_Development_Kit_and_its_basic_usage#Standard_C_and_C.2B.2B_Libraries|Standard C and C++ Libraries]]) by adding ''-noixemul'' to ''CFLAGS'' and ''LDFLAGS''. After rebuilding the program and running it again the results are significantly improved (the program has been compiled with GCC 4.4.4 from the official SDK).

[[File: scimark_cli_opt.png|center]]

This shows how important optimization of the code is, especially for computationally intensive programs. Optimized code is '''more than 4 times faster'''!

==Code Inspection==
The original source code is well modularized. Five files: ''FFT.c'', ''LU.c'', ''MonteCarlo.c'', ''SOR.c'' and ''SparseCompRow.c'' implement the five single benchmarks. Files ''array.c'' and ''Random.c'' contain auxiliary functions used in the benchmarks. The file ''Stopwatch.c'' implements time measurement. An important file ''kernel.c'' gathers all the above and provides timing for the five functions performing all the benchmarks. Finally ''scimark2.c'' contains the ''main()'' function and implements the shell interface.

The planned MUI interface should allow the user to run every benchmark separately or run all of them. There is also a ''-large'' option, which increases memory sizes for calculated problems, so they do not fit into the processor cache. A general rule of porting is that as few files as possible should be modified. The rule makes it easier to upgrade the port when a new version of the original program is released. In the case of SciMark, only one file, ''scimark2.c'' has to be replaced. An advanced port may also replace ''Stopwatch.c'' with code using ''timer.device'' directly for improved accuracy of time measurements however, this is out of scope of this tutorial.

A closer look at "scimark2.c" reveals that there is a ''Random'' object (a structure defined in "Random.h"), which is required for all the benchmarks. In the original code it is created with ''new_Random_seed()'' at the program start and disposed with ''delete_Random()'' at exit. The best place for it in the MUI-ified version is the instance data area of the subclassed ''Application'' class. Then it can be created in ''OM_NEW()'' of the class and deleted in ''OM_DISPOSE()''. These two methods should then be overridden.

==GUI Design==
[[File:scimark_gui.png|left]] Of course there is no one and only proper GUI design for SciMark. A simple design, using a limited set of MUI classes is shown on the left. There are five buttons for individual benchmarks and one for running all of them. All these buttons are instances of the ''Text'' class. On the right there are gadgets for displaying benchmark results. These gadgets also belong to the ''Text'' class, just having different attributes. The "Large Data" button, of the ''Text'' class of course, is a toggle button. Surprisingly the status bar (displaying "Ready.") is not an instance of the ''Text'' class, but instead the ''Gauge'' class. Then it will be able to display a progress bar when running all five tests. Spacing horizontal bars above the "All Benchmarks" button are instances of the ''Rectangle'' class. There are also three invisible objects of the ''Group'' class. The first is a vertical, main group, being the root object of the window. It contains two sub-groups. The upper one is the table group with two columns and contains all the benchmark buttons and result display gadgets. The lower group contains the "Large Data" toggle button and the status bar.

The simplest way to start with GUI design is just to copy the "Hello World" [["Hello world!" in MUI|example]]. Then MUI objects may be added to the ''build_gui()'' function. The [http://krashan.ppa.pl/morphzone_tutorials/scimark2_mui.c modified example] is ready to compile and run. It is not a complete program of course, just a GUI model without any functionality added.

A quick view into the ''build_gui()'' function reveals that it does not contain all the GUI code. Code for some subobjects is placed in functions called from the main ''MUI_NewObject()''. Splitting the GUI building function into many subfunctions has a few important advantages:
* Improved code readability and easier modifications. A single ''MUI_NewObject()'' call gets longer and longer quickly as the project evolves. Editing a large function spanning over a few screens is uncomfortable. Adding and removing GUI objects in such a function becomes a nightmare even with indentation used consequently. On the other hand the function can have 10 or more indentation levels, which makes it hard to read as well.
* Code size reduction. Instead of writing very similar code multiple times, for example buttons with different labels, a subroutine may be called with a label as an argument.
* Debugging. It happens sometimes that MUI refuses to create the application object because of some buggy tags or values passed to it. If the main ''MUI_NewObject()'' call is split into subfunctions, it is easy to isolate the buggy object by inserting some ''Printf()''-s in subfunctions.

==Methods and Attributes==
The SciMark GUI just designed, defines six actions for the application. There are five actions for running individual benchmarks and the sixth one for running all the tests and calculating the global result. Actions will be directly mapped to ''Application'' subclass methods. There is also one attribute connected with the "Large Data" button, it determines the sizes of problems solved by benchmarks. Methods do not need any parameters, so there is no need to define method messages. An attribute may be applicable at initialisation time (in the object constructor), may be also settable (needs ''OM_SET()'' [[Overriding OM_SET()|method overriding]]) and gettable (needs ''OM_GET()'' [[Overriding OM_GET()|method overriding]]). Our new attribute, named ''APPA_LargeData'' in the code only needs to be settable. In the constructor it can be implicitly set to ''FALSE'', as the button is switched off initially. GET-ability is not needed, because this attribute will be used only inside the ''Application'' subclass.

It is recommended that every subclass in the application is placed in a separate source file. It helps to keep code modularity and also allows for [[Short BOOPSI Overview#Classes|hiding class private data]]. This requires writing a makefile, but one is needed anyway, as the original SciMark code consists of multiple files. Implementing the design directions discussed above a [http://krashan.ppa.pl/morphzone_tutorials/scimark2_application.h class header file] and [http://krashan.ppa.pl/morphzone_tutorials/scimark2_application.c class code] can be written. The class still does nothing, just implements six empty methods and overrides ''[[Overriding OM_SET()|OM_SET()]]'', ''[[Overriding Constructors|OM_NEW()]]'' and ''[[Overriding Destructors|OM_DISPOSE()]]''. In fact it is a boring template example and as such it has been generated with the [http://downloads.morphzone.org/find.php?find=chocolatecastle ChocolateCastle] template generator. Unfortunately ChocolateCastle is still beta, so files had to be tweaked manually after generation.

The next step in the application design is to connect methods and attributes with GUI elements using [[Event Driven Programming, Notifications#Notifications in MUI|notifications]]. Notifications must of course be created after both source and target object are created. In the SciMark code they are just set up after executing ''build_gui()''. All the six action buttons have very similar notifications, so only one is shown here:

DoMethod(findobj(OBJ_BUTTON_FFT, App), MUIM_Notify, MUIA_Pressed, FALSE,
App, 1, APPM_FastFourierTransform);

The "Large Data" button has a notification setting the corresponding attribute:

DoMethod(findobj(OBJ_BUTTON_LDATA, App), MUIM_Notify, MUIA_Selected, MUIV_EveryTime,
App, 3, MUIM_Set, APPA_LargeData, MUIV_TriggerValue);

Notified objects are accessed with [[Locating Objects in the Object Tree|dynamic search]] (the ''findobj()'' macro), which saves the programmer from defining global variables for all of them.

==Implementing Functionality==
The five methods implementing single SciMark benchmarks are very similar, so only one, running the Fast Fourier Transform has been shown:

IPTR ApplicationFastFourierTransform(Class *cl, Object *obj)
{
struct ApplicationData *d = INST_DATA(cl, obj);
double result;
LONG fft_size;

if (d->LargeData) fft_size = LG_FFT_SIZE;
else fft_size = FFT_SIZE;

SetAttrs(findobj(OBJ_STATUS_BAR, obj),
MUIA_Gauge_InfoText, (LONG)"Performing Fast Fourier Transform test...",
MUIA_Gauge_Current, 0,
TAG_END);

set(findobj(OBJ_RESULT_FFT, obj), MUIA_Text_Contents, "");
set(obj, MUIA_Application_Sleep, TRUE);
result = kernel_measureFFT(fft_size, RESOLUTION_DEFAULT, d->R);
NewRawDoFmt("%.2f MFlops (N = %ld)", RAWFMTFUNC_STRING, d->Buf, result, fft_size);
set(findobj(OBJ_RESULT_FFT, obj), MUIA_Text_Contents, d->Buf);
set(obj, MUIA_Application_Sleep, FALSE);
set(findobj(OBJ_STATUS_BAR, obj), MUIA_Gauge_InfoText, "Ready.");
return 0;
}

The code uses [[Locating Objects in the Object Tree|dynamic object tree search]] for accessing MUI objects.

The method sets the benchmark data size first, based on the ''d->LargeData'' switch variable. This variable is set with the ''APPA_LargeData'' attribute, which in turn is bound to the "Large Data" button via a notification. Then the status bar progress is cleared and some text is set to inform the user what is being done. The result textfield for the benchmark is cleared as well.

The next step is to put the application in the "busy" state. It should be always done, when the application may not be responding to user input for anything longer than, let's say half a second. Setting ''MUIA_Application_Sleep'' to ''TRUE'' locks the GUI and displays the busy mouse pointer when the application window is active. Of course offloading processor intensive tasks to a subprocess is a better solution in general cases, but for a benchmark it makes little sense. A user has to wait for the benchmark result anyway before doing anything else, like starting another benchmark. The only usability problem is that a benchmark can't be stopped before it finishes. Let's leave it as is for now, for a benchmark, where the computer is expected to use all its computing power for benchmarking, a few seconds of GUI being unresponsive is not such a big problem.

The next line of code runs the benchmark, by calling ''kernel_measureFFT()'' function from the original SciMark code. After the benchmark is done, the result is formatted and displayed in the result field using ''NewRawDoFmt()'', which is a low-level string formatting function from ''exec.library'' and with the ''RAWFMTFUNC_STRING'' constant, it works just like ''sprintf()''. It uses a fixed buffer of 128 characters (which is much more than needed, but adds a safety margin) located in the object instance data. Unsleeping the application and setting the status bar text to "Ready." ends the method.

The ''APPM_AllBenchmarks()'' method code is longer so it is not repeated here. The method is very similar to the single benchmark method anyway. The difference is it runs all 5 tests accumulating their results in a table. It also updates the progress bar after every benchmark. Finally it calculates a mean score and displays it.

==Final Port==
[http://krashan.ppa.pl/morphzone_tutorials/scimark2_mui.lha The complete source of SciMark2 MUI port]

The program may be built by running ''make'' in the source directory.

MUI Subclassing Tutorial: SciMark2 Port

2011-01-07T06:38:13Z

AusPPC: /* Methods and Attributes */

''Grzegorz Kraszewski''

==The Application==
Many programming tutorials tend to bore readers with some useless examples. In this one a "real world" application will be ported to MorphOS and "MUI-fied". The application is [http://math.nist.gov/scimark2/index.html SciMark 2]. SciMark is yet another CPU/memory benchmark. It performs some typical scientific calculations like Fast Fourier Transform, matrix LU decomposition, sparse matrix multiplication and so on. The benchmark measures mainly CPU speed at floating point calculations, cache efficiency and memory speed. Being written in Java initially, it has been rewritten in C (and in fact in many other languages). The C source is available on the [http://math.nist.gov/scimark2/download_c.html project homepage].

The source uses only the pure ANSI C standard, so it is easily compilable on MorphOS using the provided ''Makefile''. One has just to replace the ''$CC = cc'' line to ''$CC = gcc'', to match the name of the MorphOS compiler. As a result, a typical shell-based application is obtained. Here are example results for a Pegasos 2 machine with G4 processor:

[[File: scimark_cli_noopt.png|center]]

Not very impressive in fact. This is because no optimizaton flags are passed to the compiler in the makefile. They can be added by inserting the line ''$CFLAGS = -O3'' below the ''$CC = gcc'' line. Let's also link with ''libnix'' (a statically linked unix environment emulation, see [[Installation_of_Software_Development_Kit_and_its_basic_usage#Standard_C_and_C.2B.2B_Libraries|Standard C and C++ Libraries]]) by adding ''-noixemul'' to ''CFLAGS'' and ''LDFLAGS''. After rebuilding the program and running it again the results are significantly improved (the program has been compiled with GCC 4.4.4 from the official SDK).

[[File: scimark_cli_opt.png|center]]

This shows how important optimization of the code is, especially for computationally intensive programs. Optimized code is '''more than 4 times faster'''!

==Code Inspection==
The original source code is well modularized. Five files: ''FFT.c'', ''LU.c'', ''MonteCarlo.c'', ''SOR.c'' and ''SparseCompRow.c'' implement the five single benchmarks. Files ''array.c'' and ''Random.c'' contain auxiliary functions used in the benchmarks. The file ''Stopwatch.c'' implements time measurement. An important file ''kernel.c'' gathers all the above and provides timing for the five functions performing all the benchmarks. Finally ''scimark2.c'' contains the ''main()'' function and implements the shell interface.

The planned MUI interface should allow the user to run every benchmark separately or run all of them. There is also a ''-large'' option, which increases memory sizes for calculated problems, so they do not fit into the processor cache. A general rule of porting is that as few files as possible should be modified. The rule makes it easier to upgrade the port when a new version of the original program is released. In the case of SciMark, only one file, ''scimark2.c'' has to be replaced. An advanced port may also replace ''Stopwatch.c'' with code using ''timer.device'' directly for improved accuracy of time measurements however, this is out of scope of this tutorial.

A closer look at "scimark2.c" reveals that there is a ''Random'' object (a structure defined in "Random.h"), which is required for all the benchmarks. In the original code it is created with ''new_Random_seed()'' at the program start and disposed with ''delete_Random()'' at exit. The best place for it in the MUI-ified version is the instance data area of the subclassed ''Application'' class. Then it can be created in ''OM_NEW()'' of the class and deleted in ''OM_DISPOSE()''. These two methods should then be overridden.

==GUI Design==
[[File:scimark_gui.png|left]] Of course there is no one and only proper GUI design for SciMark. A simple design, using a limited set of MUI classes is shown on the left. There are five buttons for individual benchmarks and one for running all of them. All these buttons are instances of the ''Text'' class. On the right there are gadgets for displaying benchmark results. These gadgets also belong to the ''Text'' class, just having different attributes. The "Large Data" button, of the ''Text'' class of course, is a toggle button. Surprisingly the status bar (displaying "Ready.") is not an instance of the ''Text'' class, but instead the ''Gauge'' class. Then it will be able to display a progress bar when running all five tests. Spacing horizontal bars above the "All Benchmarks" button are instances of the ''Rectangle'' class. There are also three invisible objects of the ''Group'' class. The first is a vertical, main group, being the root object of the window. It contains two sub-groups. The upper one is the table group with two columns and contains all the benchmark buttons and result display gadgets. The lower group contains the "Large Data" toggle button and the status bar.

The simplest way to start with GUI design is just to copy the "Hello World" [["Hello world!" in MUI|example]]. Then MUI objects may be added to the ''build_gui()'' function. The [http://krashan.ppa.pl/morphzone_tutorials/scimark2_mui.c modified example] is ready to compile and run. It is not a complete program of course, just a GUI model without any functionality added.

A quick view into the ''build_gui()'' function reveals that it does not contain all the GUI code. Code for some subobjects is placed in functions called from the main ''MUI_NewObject()''. Splitting the GUI building function into many subfunctions has a few important advantages:
* Improved code readability and easier modifications. A single ''MUI_NewObject()'' call gets longer and longer quickly as the project evolves. Editing a large function spanning over a few screens is uncomfortable. Adding and removing GUI objects in such a function becomes a nightmare even with indentation used consequently. On the other hand the function can have 10 or more indentation levels, which makes it hard to read as well.
* Code size reduction. Instead of writing very similar code multiple times, for example buttons with different labels, a subroutine may be called with a label as an argument.
* Debugging. It happens sometimes that MUI refuses to create the application object because of some buggy tags or values passed to it. If the main ''MUI_NewObject()'' call is split into subfunctions, it is easy to isolate the buggy object by inserting some ''Printf()''-s in subfunctions.

==Methods and Attributes==
The SciMark GUI just designed, defines six actions for the application. There are five actions for running individual benchmarks and the sixth one for running all the tests and calculating the global result. Actions will be directly mapped to ''Application'' subclass methods. There is also one attribute connected with the "Large Data" button, it determines the sizes of problems solved by benchmarks. Methods do not need any parameters, so there is no need to define method messages. An attribute may be applicable at initialisation time (in the object constructor), may be also settable (needs ''OM_SET()'' [[Overriding OM_SET()|method overriding]]) and gettable (needs ''OM_GET()'' [[Overriding OM_GET()|method overriding]]). Our new attribute, named ''APPA_LargeData'' in the code only needs to be settable. In the constructor it can be implicitly set to ''FALSE'', as the button is switched off initially. GET-ability is not needed, because this attribute will be used only inside the ''Application'' subclass.

It is recommended that every subclass in the application is placed in a separate source file. It helps to keep code modularity and also allows for [[Short BOOPSI Overview#Classes|hiding class private data]]. This requires writing a makefile, but one is needed anyway, as the original SciMark code consists of multiple files. Implementing the design directions discussed above a [http://krashan.ppa.pl/morphzone_tutorials/scimark2_application.h class header file] and [http://krashan.ppa.pl/morphzone_tutorials/scimark2_application.c class code] can be written. The class still does nothing, just implements six empty methods and overrides ''[[Overriding OM_SET()|OM_SET()]]'', ''[[Overriding Constructors|OM_NEW()]]'' and ''[[Overriding Destructors|OM_DISPOSE()]]''. In fact it is a boring template example and as such it has been generated with the [http://downloads.morphzone.org/find.php?find=chocolatecastle ChocolateCastle] template generator. Unfortunately ChocolateCastle is still beta, so files had to be tweaked manually after generation.

The next step in the application design is to connect methods and attributes with GUI elements using [[Event Driven Programming, Notifications#Notifications in MUI|notifications]]. Notifications must of course be created after both source and target object are created. In the SciMark code they are just set up after executing ''build_gui()''. All the six action buttons have very similar notifications, so only one is shown here:

DoMethod(findobj(OBJ_BUTTON_FFT, App), MUIM_Notify, MUIA_Pressed, FALSE,
App, 1, APPM_FastFourierTransform);

The "Large Data" button has a notification setting the corresponding attribute:

DoMethod(findobj(OBJ_BUTTON_LDATA, App), MUIM_Notify, MUIA_Selected, MUIV_EveryTime,
App, 3, MUIM_Set, APPA_LargeData, MUIV_TriggerValue);

Notified objects are accessed with [[Locating Objects in the Object Tree|dynamic search]] (the ''findobj()'' macro), which saves the programmer from defining global variables for all of them.

==Implementing Functionality==
Five methods implementing single SciMark benchmarks are very similar, so only one, running the Fast Fourier Transform has been shown:

IPTR ApplicationFastFourierTransform(Class *cl, Object *obj)
{
struct ApplicationData *d = INST_DATA(cl, obj);
double result;
LONG fft_size;

if (d->LargeData) fft_size = LG_FFT_SIZE;
else fft_size = FFT_SIZE;

SetAttrs(findobj(OBJ_STATUS_BAR, obj),
MUIA_Gauge_InfoText, (LONG)"Performing Fast Fourier Transform test...",
MUIA_Gauge_Current, 0,
TAG_END);

set(findobj(OBJ_RESULT_FFT, obj), MUIA_Text_Contents, "");
set(obj, MUIA_Application_Sleep, TRUE);
result = kernel_measureFFT(fft_size, RESOLUTION_DEFAULT, d->R);
NewRawDoFmt("%.2f MFlops (N = %ld)", RAWFMTFUNC_STRING, d->Buf, result, fft_size);
set(findobj(OBJ_RESULT_FFT, obj), MUIA_Text_Contents, d->Buf);
set(obj, MUIA_Application_Sleep, FALSE);
set(findobj(OBJ_STATUS_BAR, obj), MUIA_Gauge_InfoText, "Ready.");
return 0;
}

The code uses [[Locating Objects in the Object Tree|dynamic object tree search]] for accessing MUI objects.

The method sets the benchmark data size first, based on ''d->LargeData'' switch variable. This variable is set with ''APPA_LargeData'' attribute, which in turn is bound to the "Large Data" button via notification. Then the status bar progress is cleared and a text is set to inform a user what is being done. The result textfield for the benchmark is cleared as well.

The next step is to put the application in the "busy" state. It should be always done, when the application may be not responding for user input for a time longer than, let's say half a second. Setting ''MUIA_Application_Sleep'' to ''TRUE'' locks the GUI and displays the busy mouse pointer, when the application window is active. Of course offloading processor intenstve task to a subprocess is a better solution in general case, but for a benchmark it makes little sense. A user has to wait for the benchmark result anyway before doing anything else, like starting another benchmark. The only usablility problem is that a benchmark can't be stopped before it finishes. Let's leave it as is for now, for a benchmark, where the computer is expected to use all its computing power for benchmarking, a few seconds of GUI being unresponsive is not such a big problem.

The next line of code runs the benchmark, by calling ''kernel_measureFFT()'' function from the original SciMark code. After the benchmark is done, the result is formatted and displayed in the result field using ''NewRawDoFmt()'', which is a low-level string formatting function from ''exec.library'' and with ''RAWFMTFUNC_STRING'' constant works just like ''sprintf()''. It uses a fixed buffer of 128 characters (which is much more than needed, but adds a safety margin) located in the object instance data. Unsleeping the application and setting status bar text to "Ready." ends the method.

The ''APPM_AllBenchmarks()'' method code is longer so it is not repeated here. The method is very similar to a single benchmark one anyway. The difference is it runs all 5 tests accumulatig their results in a table. It also updates the progress bar after every benchmark. Finally it calculates a mean score and displays it.

==Final Port==
[http://krashan.ppa.pl/morphzone_tutorials/scimark2_mui.lha The complete source of SciMark2 MUI port]

The program may be built by running ''make'' in the source directory.

MUI Subclassing Tutorial: SciMark2 Port

2011-01-07T06:35:48Z

AusPPC: /* Methods and Attributes */

''Grzegorz Kraszewski''

==The Application==
Many programming tutorials tend to bore readers with some useless examples. In this one a "real world" application will be ported to MorphOS and "MUI-fied". The application is [http://math.nist.gov/scimark2/index.html SciMark 2]. SciMark is yet another CPU/memory benchmark. It performs some typical scientific calculations like Fast Fourier Transform, matrix LU decomposition, sparse matrix multiplication and so on. The benchmark measures mainly CPU speed at floating point calculations, cache efficiency and memory speed. Being written in Java initially, it has been rewritten in C (and in fact in many other languages). The C source is available on the [http://math.nist.gov/scimark2/download_c.html project homepage].

The source uses only the pure ANSI C standard, so it is easily compilable on MorphOS using the provided ''Makefile''. One has just to replace the ''$CC = cc'' line to ''$CC = gcc'', to match the name of the MorphOS compiler. As a result, a typical shell-based application is obtained. Here are example results for a Pegasos 2 machine with G4 processor:

[[File: scimark_cli_noopt.png|center]]

Not very impressive in fact. This is because no optimizaton flags are passed to the compiler in the makefile. They can be added by inserting the line ''$CFLAGS = -O3'' below the ''$CC = gcc'' line. Let's also link with ''libnix'' (a statically linked unix environment emulation, see [[Installation_of_Software_Development_Kit_and_its_basic_usage#Standard_C_and_C.2B.2B_Libraries|Standard C and C++ Libraries]]) by adding ''-noixemul'' to ''CFLAGS'' and ''LDFLAGS''. After rebuilding the program and running it again the results are significantly improved (the program has been compiled with GCC 4.4.4 from the official SDK).

[[File: scimark_cli_opt.png|center]]

This shows how important optimization of the code is, especially for computationally intensive programs. Optimized code is '''more than 4 times faster'''!

==Code Inspection==
The original source code is well modularized. Five files: ''FFT.c'', ''LU.c'', ''MonteCarlo.c'', ''SOR.c'' and ''SparseCompRow.c'' implement the five single benchmarks. Files ''array.c'' and ''Random.c'' contain auxiliary functions used in the benchmarks. The file ''Stopwatch.c'' implements time measurement. An important file ''kernel.c'' gathers all the above and provides timing for the five functions performing all the benchmarks. Finally ''scimark2.c'' contains the ''main()'' function and implements the shell interface.

The planned MUI interface should allow the user to run every benchmark separately or run all of them. There is also a ''-large'' option, which increases memory sizes for calculated problems, so they do not fit into the processor cache. A general rule of porting is that as few files as possible should be modified. The rule makes it easier to upgrade the port when a new version of the original program is released. In the case of SciMark, only one file, ''scimark2.c'' has to be replaced. An advanced port may also replace ''Stopwatch.c'' with code using ''timer.device'' directly for improved accuracy of time measurements however, this is out of scope of this tutorial.

A closer look at "scimark2.c" reveals that there is a ''Random'' object (a structure defined in "Random.h"), which is required for all the benchmarks. In the original code it is created with ''new_Random_seed()'' at the program start and disposed with ''delete_Random()'' at exit. The best place for it in the MUI-ified version is the instance data area of the subclassed ''Application'' class. Then it can be created in ''OM_NEW()'' of the class and deleted in ''OM_DISPOSE()''. These two methods should then be overridden.

==GUI Design==
[[File:scimark_gui.png|left]] Of course there is no one and only proper GUI design for SciMark. A simple design, using a limited set of MUI classes is shown on the left. There are five buttons for individual benchmarks and one for running all of them. All these buttons are instances of the ''Text'' class. On the right there are gadgets for displaying benchmark results. These gadgets also belong to the ''Text'' class, just having different attributes. The "Large Data" button, of the ''Text'' class of course, is a toggle button. Surprisingly the status bar (displaying "Ready.") is not an instance of the ''Text'' class, but instead the ''Gauge'' class. Then it will be able to display a progress bar when running all five tests. Spacing horizontal bars above the "All Benchmarks" button are instances of the ''Rectangle'' class. There are also three invisible objects of the ''Group'' class. The first is a vertical, main group, being the root object of the window. It contains two sub-groups. The upper one is the table group with two columns and contains all the benchmark buttons and result display gadgets. The lower group contains the "Large Data" toggle button and the status bar.

The simplest way to start with GUI design is just to copy the "Hello World" [["Hello world!" in MUI|example]]. Then MUI objects may be added to the ''build_gui()'' function. The [http://krashan.ppa.pl/morphzone_tutorials/scimark2_mui.c modified example] is ready to compile and run. It is not a complete program of course, just a GUI model without any functionality added.

A quick view into the ''build_gui()'' function reveals that it does not contain all the GUI code. Code for some subobjects is placed in functions called from the main ''MUI_NewObject()''. Splitting the GUI building function into many subfunctions has a few important advantages:
* Improved code readability and easier modifications. A single ''MUI_NewObject()'' call gets longer and longer quickly as the project evolves. Editing a large function spanning over a few screens is uncomfortable. Adding and removing GUI objects in such a function becomes a nightmare even with indentation used consequently. On the other hand the function can have 10 or more indentation levels, which makes it hard to read as well.
* Code size reduction. Instead of writing very similar code multiple times, for example buttons with different labels, a subroutine may be called with a label as an argument.
* Debugging. It happens sometimes that MUI refuses to create the application object because of some buggy tags or values passed to it. If the main ''MUI_NewObject()'' call is split into subfunctions, it is easy to isolate the buggy object by inserting some ''Printf()''-s in subfunctions.

==Methods and Attributes==
The SciMark GUI just designed, defines six actions for the application. There are five actions for running individual benchmarks and the sixth one for running all the tests and calculating the global result. Actions will be directly mapped to ''Application'' subclass methods. There is also one attribute connected with the "Large Data" button, it determines the sizes of problems solved by benchmarks. Methods do not need any parameters, so there is no need to define method messages. An attribute may be applicable at initialisation time (in the object constructor), may be also settable (needs ''OM_SET()'' [[Overriding OM_SET()|method overriding]]) and gettable (needs ''OM_GET()'' [[Overriding OM_GET()|method overriding]]). Our new attribute, named ''APPA_LargeData'' in the code only needs to be settable. In the constructor it can be implicitly set to ''FALSE'', as the button is switched off initially. GET-ability is not needed, because this attribute will be used only inside the ''Application'' subclass.

It is recommended that every subclass in the application is placed in a separate source file. It helps to keep code modularity and also allows for [[Short BOOPSI Overview#Classes|hiding class private data]]. This requires writing a makefile, but one is needed anyway, as the original SciMark code consists of multiple files. Implementing the design directions discussed above a [http://krashan.ppa.pl/morphzone_tutorials/scimark2_application.h class header file] and [http://krashan.ppa.pl/morphzone_tutorials/scimark2_application.c class code] can be written. The class still does nothing, just implements six empty methods and overrides ''[[Overriding OM_SET()|OM_SET()]]'', ''[[Overriding Constructors|OM_NEW()]]'' and ''[[Overriding Destructors|OM_DISPOSE()]]''. In fact it is a boring template example and as such it has been generated with the [http://downloads.morphzone.org/find.php?find=chocolatecastle ChocolateCastle] template generator. Unfortunately ChocolateCastle is still beta, so files had to be tweaked manually after generation.

The next step in the application design is to connect methods and attributes with GUI elements using [[Event Driven Programming, Notifications#Notifications in MUI|notifications]]. Notifications must be of course created after both source and target object are created. In the SciMark code they are just set up after executing ''build_gui()''. All the six action buttons have very similar notifications, so only one is shown here:

DoMethod(findobj(OBJ_BUTTON_FFT, App), MUIM_Notify, MUIA_Pressed, FALSE,
App, 1, APPM_FastFourierTransform);

"Large Data" button has a notification setting the corresponding attribute:

DoMethod(findobj(OBJ_BUTTON_LDATA, App), MUIM_Notify, MUIA_Selected, MUIV_EveryTime,
App, 3, MUIM_Set, APPA_LargeData, MUIV_TriggerValue);

Notified objects are accessed with [[Locating Objects in the Object Tree|dynamic search]] (the ''findobj()'' macro), which saves from defining global variables for all of them.

==Implementing Functionality==
Five methods implementing single SciMark benchmarks are very similar, so only one, running the Fast Fourier Transform has been shown:

IPTR ApplicationFastFourierTransform(Class *cl, Object *obj)
{
struct ApplicationData *d = INST_DATA(cl, obj);
double result;
LONG fft_size;

if (d->LargeData) fft_size = LG_FFT_SIZE;
else fft_size = FFT_SIZE;

SetAttrs(findobj(OBJ_STATUS_BAR, obj),
MUIA_Gauge_InfoText, (LONG)"Performing Fast Fourier Transform test...",
MUIA_Gauge_Current, 0,
TAG_END);

set(findobj(OBJ_RESULT_FFT, obj), MUIA_Text_Contents, "");
set(obj, MUIA_Application_Sleep, TRUE);
result = kernel_measureFFT(fft_size, RESOLUTION_DEFAULT, d->R);
NewRawDoFmt("%.2f MFlops (N = %ld)", RAWFMTFUNC_STRING, d->Buf, result, fft_size);
set(findobj(OBJ_RESULT_FFT, obj), MUIA_Text_Contents, d->Buf);
set(obj, MUIA_Application_Sleep, FALSE);
set(findobj(OBJ_STATUS_BAR, obj), MUIA_Gauge_InfoText, "Ready.");
return 0;
}

The code uses [[Locating Objects in the Object Tree|dynamic object tree search]] for accessing MUI objects.

The method sets the benchmark data size first, based on ''d->LargeData'' switch variable. This variable is set with ''APPA_LargeData'' attribute, which in turn is bound to the "Large Data" button via notification. Then the status bar progress is cleared and a text is set to inform a user what is being done. The result textfield for the benchmark is cleared as well.

The next step is to put the application in the "busy" state. It should be always done, when the application may be not responding for user input for a time longer than, let's say half a second. Setting ''MUIA_Application_Sleep'' to ''TRUE'' locks the GUI and displays the busy mouse pointer, when the application window is active. Of course offloading processor intenstve task to a subprocess is a better solution in general case, but for a benchmark it makes little sense. A user has to wait for the benchmark result anyway before doing anything else, like starting another benchmark. The only usablility problem is that a benchmark can't be stopped before it finishes. Let's leave it as is for now, for a benchmark, where the computer is expected to use all its computing power for benchmarking, a few seconds of GUI being unresponsive is not such a big problem.

The next line of code runs the benchmark, by calling ''kernel_measureFFT()'' function from the original SciMark code. After the benchmark is done, the result is formatted and displayed in the result field using ''NewRawDoFmt()'', which is a low-level string formatting function from ''exec.library'' and with ''RAWFMTFUNC_STRING'' constant works just like ''sprintf()''. It uses a fixed buffer of 128 characters (which is much more than needed, but adds a safety margin) located in the object instance data. Unsleeping the application and setting status bar text to "Ready." ends the method.

The ''APPM_AllBenchmarks()'' method code is longer so it is not repeated here. The method is very similar to a single benchmark one anyway. The difference is it runs all 5 tests accumulatig their results in a table. It also updates the progress bar after every benchmark. Finally it calculates a mean score and displays it.

==Final Port==
[http://krashan.ppa.pl/morphzone_tutorials/scimark2_mui.lha The complete source of SciMark2 MUI port]

The program may be built by running ''make'' in the source directory.

MUI Subclassing Tutorial: SciMark2 Port

2011-01-07T06:30:35Z

AusPPC: /* GUI Design */

''Grzegorz Kraszewski''

==The Application==
Many programming tutorials tend to bore readers with some useless examples. In this one a "real world" application will be ported to MorphOS and "MUI-fied". The application is [http://math.nist.gov/scimark2/index.html SciMark 2]. SciMark is yet another CPU/memory benchmark. It performs some typical scientific calculations like Fast Fourier Transform, matrix LU decomposition, sparse matrix multiplication and so on. The benchmark measures mainly CPU speed at floating point calculations, cache efficiency and memory speed. Being written in Java initially, it has been rewritten in C (and in fact in many other languages). The C source is available on the [http://math.nist.gov/scimark2/download_c.html project homepage].

The source uses only the pure ANSI C standard, so it is easily compilable on MorphOS using the provided ''Makefile''. One has just to replace the ''$CC = cc'' line to ''$CC = gcc'', to match the name of the MorphOS compiler. As a result, a typical shell-based application is obtained. Here are example results for a Pegasos 2 machine with G4 processor:

[[File: scimark_cli_noopt.png|center]]

Not very impressive in fact. This is because no optimizaton flags are passed to the compiler in the makefile. They can be added by inserting the line ''$CFLAGS = -O3'' below the ''$CC = gcc'' line. Let's also link with ''libnix'' (a statically linked unix environment emulation, see [[Installation_of_Software_Development_Kit_and_its_basic_usage#Standard_C_and_C.2B.2B_Libraries|Standard C and C++ Libraries]]) by adding ''-noixemul'' to ''CFLAGS'' and ''LDFLAGS''. After rebuilding the program and running it again the results are significantly improved (the program has been compiled with GCC 4.4.4 from the official SDK).

[[File: scimark_cli_opt.png|center]]

This shows how important optimization of the code is, especially for computationally intensive programs. Optimized code is '''more than 4 times faster'''!

==Code Inspection==
The original source code is well modularized. Five files: ''FFT.c'', ''LU.c'', ''MonteCarlo.c'', ''SOR.c'' and ''SparseCompRow.c'' implement the five single benchmarks. Files ''array.c'' and ''Random.c'' contain auxiliary functions used in the benchmarks. The file ''Stopwatch.c'' implements time measurement. An important file ''kernel.c'' gathers all the above and provides timing for the five functions performing all the benchmarks. Finally ''scimark2.c'' contains the ''main()'' function and implements the shell interface.

The planned MUI interface should allow the user to run every benchmark separately or run all of them. There is also a ''-large'' option, which increases memory sizes for calculated problems, so they do not fit into the processor cache. A general rule of porting is that as few files as possible should be modified. The rule makes it easier to upgrade the port when a new version of the original program is released. In the case of SciMark, only one file, ''scimark2.c'' has to be replaced. An advanced port may also replace ''Stopwatch.c'' with code using ''timer.device'' directly for improved accuracy of time measurements however, this is out of scope of this tutorial.

A closer look at "scimark2.c" reveals that there is a ''Random'' object (a structure defined in "Random.h"), which is required for all the benchmarks. In the original code it is created with ''new_Random_seed()'' at the program start and disposed with ''delete_Random()'' at exit. The best place for it in the MUI-ified version is the instance data area of the subclassed ''Application'' class. Then it can be created in ''OM_NEW()'' of the class and deleted in ''OM_DISPOSE()''. These two methods should then be overridden.

==GUI Design==
[[File:scimark_gui.png|left]] Of course there is no one and only proper GUI design for SciMark. A simple design, using a limited set of MUI classes is shown on the left. There are five buttons for individual benchmarks and one for running all of them. All these buttons are instances of the ''Text'' class. On the right there are gadgets for displaying benchmark results. These gadgets also belong to the ''Text'' class, just having different attributes. The "Large Data" button, of the ''Text'' class of course, is a toggle button. Surprisingly the status bar (displaying "Ready.") is not an instance of the ''Text'' class, but instead the ''Gauge'' class. Then it will be able to display a progress bar when running all five tests. Spacing horizontal bars above the "All Benchmarks" button are instances of the ''Rectangle'' class. There are also three invisible objects of the ''Group'' class. The first is a vertical, main group, being the root object of the window. It contains two sub-groups. The upper one is the table group with two columns and contains all the benchmark buttons and result display gadgets. The lower group contains the "Large Data" toggle button and the status bar.

The simplest way to start with GUI design is just to copy the "Hello World" [["Hello world!" in MUI|example]]. Then MUI objects may be added to the ''build_gui()'' function. The [http://krashan.ppa.pl/morphzone_tutorials/scimark2_mui.c modified example] is ready to compile and run. It is not a complete program of course, just a GUI model without any functionality added.

A quick view into the ''build_gui()'' function reveals that it does not contain all the GUI code. Code for some subobjects is placed in functions called from the main ''MUI_NewObject()''. Splitting the GUI building function into many subfunctions has a few important advantages:
* Improved code readability and easier modifications. A single ''MUI_NewObject()'' call gets longer and longer quickly as the project evolves. Editing a large function spanning over a few screens is uncomfortable. Adding and removing GUI objects in such a function becomes a nightmare even with indentation used consequently. On the other hand the function can have 10 or more indentation levels, which makes it hard to read as well.
* Code size reduction. Instead of writing very similar code multiple times, for example buttons with different labels, a subroutine may be called with a label as an argument.
* Debugging. It happens sometimes that MUI refuses to create the application object because of some buggy tags or values passed to it. If the main ''MUI_NewObject()'' call is split into subfunctions, it is easy to isolate the buggy object by inserting some ''Printf()''-s in subfunctions.

==Methods and Attributes==
The SciMark GUI just designed, defines six actions of the application. There are five actions of running individual benchmarks and the sixth one of running all the tests and calculate the global result. Actions will be directly mapped to an ''Application'' subclass methods. There is also one attribute connected with "Large Data" button, it determines sizes of problems solved by benchmarks. Methods do not need any parameters, so there is no need to define method messages. An attribute may be applicable at init time (in the object constructor), may be also settable (needs ''OM_SET()'' [[Overriding OM_SET()|method overriding]]) and gettable (needs ''OM_GET()'' [[Overriding OM_GET()|method overriding]]). Our new attribute, named ''APPA_LargeData'' in the code only needs to be settable. In the constructor it can be implicitly set to ''FALSE'', as the button is switched off initially. Gettability is not needed, because this attribute will be used only inside the ''Application'' subclass.

It is recommended that every subclass in the application is placed in a separate source file. It helps to keep code modularity and also allows for [[Short BOOPSI Overview#Classes|hiding class private data]]. This requires writing a makefile, but one is needed anyway, as the original SciMark code consists of multiple files. Implementing the design directions discussed above a [http://krashan.ppa.pl/morphzone_tutorials/scimark2_application.h class header file] and [http://krashan.ppa.pl/morphzone_tutorials/scimark2_application.c class code] can be written. The class still does nothing, just implements six empty methods and overrides ''[[Overriding OM_SET()|OM_SET()]]'', ''[[Overriding Constructors|OM_NEW()]]'' and ''[[Overriding Destructors|OM_DISPOSE()]]''. In fact it is a boring template work and as such it has been generated with [http://downloads.morphzone.org/find.php?find=chocolatecastle ChocolateCastle] template generator. Unfortunately ChocolateCastle is still beta, so files had to be tweaked manually after generation.

The next step in the application design is to connect methods and attributes with GUI elements using [[Event Driven Programming, Notifications#Notifications in MUI|notifications]]. Notifications must be of course created after both source and target object are created. In the SciMark code they are just set up after executing ''build_gui()''. All the six action buttons have very similar notifications, so only one is shown here:

DoMethod(findobj(OBJ_BUTTON_FFT, App), MUIM_Notify, MUIA_Pressed, FALSE,
App, 1, APPM_FastFourierTransform);

"Large Data" button has a notification setting the corresponding attribute:

DoMethod(findobj(OBJ_BUTTON_LDATA, App), MUIM_Notify, MUIA_Selected, MUIV_EveryTime,
App, 3, MUIM_Set, APPA_LargeData, MUIV_TriggerValue);

Notified objects are accessed with [[Locating Objects in the Object Tree|dynamic search]] (the ''findobj()'' macro), which saves from defining global variables for all of them.

==Implementing Functionality==
Five methods implementing single SciMark benchmarks are very similar, so only one, running the Fast Fourier Transform has been shown:

IPTR ApplicationFastFourierTransform(Class *cl, Object *obj)
{
struct ApplicationData *d = INST_DATA(cl, obj);
double result;
LONG fft_size;

if (d->LargeData) fft_size = LG_FFT_SIZE;
else fft_size = FFT_SIZE;

SetAttrs(findobj(OBJ_STATUS_BAR, obj),
MUIA_Gauge_InfoText, (LONG)"Performing Fast Fourier Transform test...",
MUIA_Gauge_Current, 0,
TAG_END);

set(findobj(OBJ_RESULT_FFT, obj), MUIA_Text_Contents, "");
set(obj, MUIA_Application_Sleep, TRUE);
result = kernel_measureFFT(fft_size, RESOLUTION_DEFAULT, d->R);
NewRawDoFmt("%.2f MFlops (N = %ld)", RAWFMTFUNC_STRING, d->Buf, result, fft_size);
set(findobj(OBJ_RESULT_FFT, obj), MUIA_Text_Contents, d->Buf);
set(obj, MUIA_Application_Sleep, FALSE);
set(findobj(OBJ_STATUS_BAR, obj), MUIA_Gauge_InfoText, "Ready.");
return 0;
}

The code uses [[Locating Objects in the Object Tree|dynamic object tree search]] for accessing MUI objects.

The method sets the benchmark data size first, based on ''d->LargeData'' switch variable. This variable is set with ''APPA_LargeData'' attribute, which in turn is bound to the "Large Data" button via notification. Then the status bar progress is cleared and a text is set to inform a user what is being done. The result textfield for the benchmark is cleared as well.

The next step is to put the application in the "busy" state. It should be always done, when the application may be not responding for user input for a time longer than, let's say half a second. Setting ''MUIA_Application_Sleep'' to ''TRUE'' locks the GUI and displays the busy mouse pointer, when the application window is active. Of course offloading processor intenstve task to a subprocess is a better solution in general case, but for a benchmark it makes little sense. A user has to wait for the benchmark result anyway before doing anything else, like starting another benchmark. The only usablility problem is that a benchmark can't be stopped before it finishes. Let's leave it as is for now, for a benchmark, where the computer is expected to use all its computing power for benchmarking, a few seconds of GUI being unresponsive is not such a big problem.

The next line of code runs the benchmark, by calling ''kernel_measureFFT()'' function from the original SciMark code. After the benchmark is done, the result is formatted and displayed in the result field using ''NewRawDoFmt()'', which is a low-level string formatting function from ''exec.library'' and with ''RAWFMTFUNC_STRING'' constant works just like ''sprintf()''. It uses a fixed buffer of 128 characters (which is much more than needed, but adds a safety margin) located in the object instance data. Unsleeping the application and setting status bar text to "Ready." ends the method.

The ''APPM_AllBenchmarks()'' method code is longer so it is not repeated here. The method is very similar to a single benchmark one anyway. The difference is it runs all 5 tests accumulatig their results in a table. It also updates the progress bar after every benchmark. Finally it calculates a mean score and displays it.

==Final Port==
[http://krashan.ppa.pl/morphzone_tutorials/scimark2_mui.lha The complete source of SciMark2 MUI port]

The program may be built by running ''make'' in the source directory.

MUI Subclassing Tutorial: SciMark2 Port

2011-01-07T06:22:53Z

AusPPC: /* Code Inspection */

''Grzegorz Kraszewski''

==The Application==
Many programming tutorials tend to bore readers with some useless examples. In this one a "real world" application will be ported to MorphOS and "MUI-fied". The application is [http://math.nist.gov/scimark2/index.html SciMark 2]. SciMark is yet another CPU/memory benchmark. It performs some typical scientific calculations like Fast Fourier Transform, matrix LU decomposition, sparse matrix multiplication and so on. The benchmark measures mainly CPU speed at floating point calculations, cache efficiency and memory speed. Being written in Java initially, it has been rewritten in C (and in fact in many other languages). The C source is available on the [http://math.nist.gov/scimark2/download_c.html project homepage].

The source uses only the pure ANSI C standard, so it is easily compilable on MorphOS using the provided ''Makefile''. One has just to replace the ''$CC = cc'' line to ''$CC = gcc'', to match the name of the MorphOS compiler. As a result, a typical shell-based application is obtained. Here are example results for a Pegasos 2 machine with G4 processor:

[[File: scimark_cli_noopt.png|center]]

Not very impressive in fact. This is because no optimizaton flags are passed to the compiler in the makefile. They can be added by inserting the line ''$CFLAGS = -O3'' below the ''$CC = gcc'' line. Let's also link with ''libnix'' (a statically linked unix environment emulation, see [[Installation_of_Software_Development_Kit_and_its_basic_usage#Standard_C_and_C.2B.2B_Libraries|Standard C and C++ Libraries]]) by adding ''-noixemul'' to ''CFLAGS'' and ''LDFLAGS''. After rebuilding the program and running it again the results are significantly improved (the program has been compiled with GCC 4.4.4 from the official SDK).

[[File: scimark_cli_opt.png|center]]

This shows how important optimization of the code is, especially for computationally intensive programs. Optimized code is '''more than 4 times faster'''!

==Code Inspection==
The original source code is well modularized. Five files: ''FFT.c'', ''LU.c'', ''MonteCarlo.c'', ''SOR.c'' and ''SparseCompRow.c'' implement the five single benchmarks. Files ''array.c'' and ''Random.c'' contain auxiliary functions used in the benchmarks. The file ''Stopwatch.c'' implements time measurement. An important file ''kernel.c'' gathers all the above and provides timing for the five functions performing all the benchmarks. Finally ''scimark2.c'' contains the ''main()'' function and implements the shell interface.

The planned MUI interface should allow the user to run every benchmark separately or run all of them. There is also a ''-large'' option, which increases memory sizes for calculated problems, so they do not fit into the processor cache. A general rule of porting is that as few files as possible should be modified. The rule makes it easier to upgrade the port when a new version of the original program is released. In the case of SciMark, only one file, ''scimark2.c'' has to be replaced. An advanced port may also replace ''Stopwatch.c'' with code using ''timer.device'' directly for improved accuracy of time measurements however, this is out of scope of this tutorial.

A closer look at "scimark2.c" reveals that there is a ''Random'' object (a structure defined in "Random.h"), which is required for all the benchmarks. In the original code it is created with ''new_Random_seed()'' at the program start and disposed with ''delete_Random()'' at exit. The best place for it in the MUI-ified version is the instance data area of the subclassed ''Application'' class. Then it can be created in ''OM_NEW()'' of the class and deleted in ''OM_DISPOSE()''. These two methods should then be overridden.

==GUI Design==
[[File:scimark_gui.png|left]] Of course there is no one and only proper GUI design for SciMark. A simple design, using a limited set of MUI classes is shown on the left. There are five buttons for individual benchmarks and one for running all of them. All these buttons are instances of the ''Text'' class. On the right there are gadgets for displaying benchmark results. These gadgets belong to ''Text'' class too, just having different attributes. The "Large Data" button, of ''Text'' class of course, is a toggle one. Surprisingly the status bar (displaying "Ready.") is not an instance of the ''Text'' class, but ''Gauge'' class. Then it will be able to display a progress bar when running all five tests. Spacing horizontal bars above the "All Benchmarks" button are instances of the ''Rectangle'' class. There are also three invisible objects of the ''Group'' class. The first is a vertical, main group, being the root object of the window. It contains two sub-groups. The upper one is the table group with two columns and contains all the benchmark buttons and result display gadgets. The lower group contains "Large Data" toggle button and the status bar.

The simplest way to start with GUI design is just to copy the "Hello World" [["Hello world!" in MUI|example]]. Then MUI objects may be added to ''build_gui()'' function. The [http://krashan.ppa.pl/morphzone_tutorials/scimark2_mui.c modified example] is ready to compile and run. It is not a complete program of course, just a GUI model without any functionality added.

A quick view into the ''build_gui()'' function reveals that it does not contain all the GUI code. Code for some subobjects is placed in functions called from the main ''MUI_NewObject()''. Splitting the GUI building function into many subfunctions has a few important advantages:
* Improved code readability and easier modifications. A single ''MUI_NewObject()'' call gets longer and longer quickly as the project evolves. Editing a large function spanning over a few screens is uncomfortable. Adding and removing GUI objects in such a function becomes nightmare even with indentation used consequently. On the other hand the function can have 10 or more indentation levels, which makes it hard to read as well.
* Code size reduction. Instead of writing very similar code multiple times, for example buttons with different labels, a subroutine may be called with label as an argument.
* Debugging. It happens sometimes that MUI refuses to create the application object because of some buggy tags or values passed. If the main ''MUI_NewObject()'' call is split into subfunctions, it is easy to isolate the buggy object by inserting some ''Printf()''-s in subfunctions.

==Methods and Attributes==
The SciMark GUI just designed, defines six actions of the application. There are five actions of running individual benchmarks and the sixth one of running all the tests and calculate the global result. Actions will be directly mapped to an ''Application'' subclass methods. There is also one attribute connected with "Large Data" button, it determines sizes of problems solved by benchmarks. Methods do not need any parameters, so there is no need to define method messages. An attribute may be applicable at init time (in the object constructor), may be also settable (needs ''OM_SET()'' [[Overriding OM_SET()|method overriding]]) and gettable (needs ''OM_GET()'' [[Overriding OM_GET()|method overriding]]). Our new attribute, named ''APPA_LargeData'' in the code only needs to be settable. In the constructor it can be implicitly set to ''FALSE'', as the button is switched off initially. Gettability is not needed, because this attribute will be used only inside the ''Application'' subclass.

It is recommended that every subclass in the application is placed in a separate source file. It helps to keep code modularity and also allows for [[Short BOOPSI Overview#Classes|hiding class private data]]. This requires writing a makefile, but one is needed anyway, as the original SciMark code consists of multiple files. Implementing the design directions discussed above a [http://krashan.ppa.pl/morphzone_tutorials/scimark2_application.h class header file] and [http://krashan.ppa.pl/morphzone_tutorials/scimark2_application.c class code] can be written. The class still does nothing, just implements six empty methods and overrides ''[[Overriding OM_SET()|OM_SET()]]'', ''[[Overriding Constructors|OM_NEW()]]'' and ''[[Overriding Destructors|OM_DISPOSE()]]''. In fact it is a boring template work and as such it has been generated with [http://downloads.morphzone.org/find.php?find=chocolatecastle ChocolateCastle] template generator. Unfortunately ChocolateCastle is still beta, so files had to be tweaked manually after generation.

The next step in the application design is to connect methods and attributes with GUI elements using [[Event Driven Programming, Notifications#Notifications in MUI|notifications]]. Notifications must be of course created after both source and target object are created. In the SciMark code they are just set up after executing ''build_gui()''. All the six action buttons have very similar notifications, so only one is shown here:

DoMethod(findobj(OBJ_BUTTON_FFT, App), MUIM_Notify, MUIA_Pressed, FALSE,
App, 1, APPM_FastFourierTransform);

"Large Data" button has a notification setting the corresponding attribute:

DoMethod(findobj(OBJ_BUTTON_LDATA, App), MUIM_Notify, MUIA_Selected, MUIV_EveryTime,
App, 3, MUIM_Set, APPA_LargeData, MUIV_TriggerValue);

Notified objects are accessed with [[Locating Objects in the Object Tree|dynamic search]] (the ''findobj()'' macro), which saves from defining global variables for all of them.

==Implementing Functionality==
Five methods implementing single SciMark benchmarks are very similar, so only one, running the Fast Fourier Transform has been shown:

IPTR ApplicationFastFourierTransform(Class *cl, Object *obj)
{
struct ApplicationData *d = INST_DATA(cl, obj);
double result;
LONG fft_size;

if (d->LargeData) fft_size = LG_FFT_SIZE;
else fft_size = FFT_SIZE;

SetAttrs(findobj(OBJ_STATUS_BAR, obj),
MUIA_Gauge_InfoText, (LONG)"Performing Fast Fourier Transform test...",
MUIA_Gauge_Current, 0,
TAG_END);

set(findobj(OBJ_RESULT_FFT, obj), MUIA_Text_Contents, "");
set(obj, MUIA_Application_Sleep, TRUE);
result = kernel_measureFFT(fft_size, RESOLUTION_DEFAULT, d->R);
NewRawDoFmt("%.2f MFlops (N = %ld)", RAWFMTFUNC_STRING, d->Buf, result, fft_size);
set(findobj(OBJ_RESULT_FFT, obj), MUIA_Text_Contents, d->Buf);
set(obj, MUIA_Application_Sleep, FALSE);
set(findobj(OBJ_STATUS_BAR, obj), MUIA_Gauge_InfoText, "Ready.");
return 0;
}

The code uses [[Locating Objects in the Object Tree|dynamic object tree search]] for accessing MUI objects.

The method sets the benchmark data size first, based on ''d->LargeData'' switch variable. This variable is set with ''APPA_LargeData'' attribute, which in turn is bound to the "Large Data" button via notification. Then the status bar progress is cleared and a text is set to inform a user what is being done. The result textfield for the benchmark is cleared as well.

The next step is to put the application in the "busy" state. It should be always done, when the application may be not responding for user input for a time longer than, let's say half a second. Setting ''MUIA_Application_Sleep'' to ''TRUE'' locks the GUI and displays the busy mouse pointer, when the application window is active. Of course offloading processor intenstve task to a subprocess is a better solution in general case, but for a benchmark it makes little sense. A user has to wait for the benchmark result anyway before doing anything else, like starting another benchmark. The only usablility problem is that a benchmark can't be stopped before it finishes. Let's leave it as is for now, for a benchmark, where the computer is expected to use all its computing power for benchmarking, a few seconds of GUI being unresponsive is not such a big problem.

The next line of code runs the benchmark, by calling ''kernel_measureFFT()'' function from the original SciMark code. After the benchmark is done, the result is formatted and displayed in the result field using ''NewRawDoFmt()'', which is a low-level string formatting function from ''exec.library'' and with ''RAWFMTFUNC_STRING'' constant works just like ''sprintf()''. It uses a fixed buffer of 128 characters (which is much more than needed, but adds a safety margin) located in the object instance data. Unsleeping the application and setting status bar text to "Ready." ends the method.

The ''APPM_AllBenchmarks()'' method code is longer so it is not repeated here. The method is very similar to a single benchmark one anyway. The difference is it runs all 5 tests accumulatig their results in a table. It also updates the progress bar after every benchmark. Finally it calculates a mean score and displays it.

==Final Port==
[http://krashan.ppa.pl/morphzone_tutorials/scimark2_mui.lha The complete source of SciMark2 MUI port]

The program may be built by running ''make'' in the source directory.

MUI Subclassing Tutorial: SciMark2 Port

2011-01-07T06:15:50Z

AusPPC: /* The Application */

''Grzegorz Kraszewski''

==The Application==
Many programming tutorials tend to bore readers with some useless examples. In this one a "real world" application will be ported to MorphOS and "MUI-fied". The application is [http://math.nist.gov/scimark2/index.html SciMark 2]. SciMark is yet another CPU/memory benchmark. It performs some typical scientific calculations like Fast Fourier Transform, matrix LU decomposition, sparse matrix multiplication and so on. The benchmark measures mainly CPU speed at floating point calculations, cache efficiency and memory speed. Being written in Java initially, it has been rewritten in C (and in fact in many other languages). The C source is available on the [http://math.nist.gov/scimark2/download_c.html project homepage].

The source uses only the pure ANSI C standard, so it is easily compilable on MorphOS using the provided ''Makefile''. One has just to replace the ''$CC = cc'' line to ''$CC = gcc'', to match the name of the MorphOS compiler. As a result, a typical shell-based application is obtained. Here are example results for a Pegasos 2 machine with G4 processor:

[[File: scimark_cli_noopt.png|center]]

Not very impressive in fact. This is because no optimizaton flags are passed to the compiler in the makefile. They can be added by inserting the line ''$CFLAGS = -O3'' below the ''$CC = gcc'' line. Let's also link with ''libnix'' (a statically linked unix environment emulation, see [[Installation_of_Software_Development_Kit_and_its_basic_usage#Standard_C_and_C.2B.2B_Libraries|Standard C and C++ Libraries]]) by adding ''-noixemul'' to ''CFLAGS'' and ''LDFLAGS''. After rebuilding the program and running it again the results are significantly improved (the program has been compiled with GCC 4.4.4 from the official SDK).

[[File: scimark_cli_opt.png|center]]

This shows how important optimization of the code is, especially for computationally intensive programs. Optimized code is '''more than 4 times faster'''!

==Code Inspection==
The original source code is well modularized. Five files: ''FFT.c'', ''LU.c'', ''MonteCarlo.c'', ''SOR.c'' and ''SparseCompRow.c'' implement the five of single benchmarks. Files ''array.c'' and ''Random.c'' contain auxiliary functions used in benchmarks. File ''Stopwatch.c'' implements time measurement. An important file ''kernel.c'' gathers all the above and provides five functions performing complete benchmarks with timing. Finally ''scimark2.c'' contains the ''main()'' function and implements the shell interface.

A planned MUI interface should allow to run every benchmark separately and run all of them. There is also ''-large'' option, which increases memory sizes of calculated problems, so they do not fit into the processor cache. A general rule of porting is that as few files as possible should be modified. The rule makes it easier to upgrade the port when a new version of original program is released. In the case of SciMark, only one file, ''scimark2.c'' has to be replaced. An advanced port may also replace ''Stopwatch.c'' with code using ''timer.device'' directly for improved time measurements accuracy, this is out of scope of this tutorial however.

A closer look at "scimark2.c" reveals that there is a ''Random'' object (a structure defined in "Random.h"), which is required for all the benchmarks. In the original code it is created with ''new_Random_seed()'' at the program start and disposed with ''delete_Random()'' at exit. The best place for it in the MUI-fied version is the instance data area of subclassed ''Application'' class. Then it can be created in ''OM_NEW()'' of the class and deleted in ''OM_DISPOSE()''. These two methods should be overridden then.

==GUI Design==
[[File:scimark_gui.png|left]] Of course there is no one and only proper GUI design for SciMark. A simple design, using a limited set of MUI classes is shown on the left. There are five buttons for individual benchmarks and one for running all of them. All these buttons are instances of the ''Text'' class. On the right there are gadgets for displaying benchmark results. These gadgets belong to ''Text'' class too, just having different attributes. The "Large Data" button, of ''Text'' class of course, is a toggle one. Surprisingly the status bar (displaying "Ready.") is not an instance of the ''Text'' class, but ''Gauge'' class. Then it will be able to display a progress bar when running all five tests. Spacing horizontal bars above the "All Benchmarks" button are instances of the ''Rectangle'' class. There are also three invisible objects of the ''Group'' class. The first is a vertical, main group, being the root object of the window. It contains two sub-groups. The upper one is the table group with two columns and contains all the benchmark buttons and result display gadgets. The lower group contains "Large Data" toggle button and the status bar.

The simplest way to start with GUI design is just to copy the "Hello World" [["Hello world!" in MUI|example]]. Then MUI objects may be added to ''build_gui()'' function. The [http://krashan.ppa.pl/morphzone_tutorials/scimark2_mui.c modified example] is ready to compile and run. It is not a complete program of course, just a GUI model without any functionality added.

A quick view into the ''build_gui()'' function reveals that it does not contain all the GUI code. Code for some subobjects is placed in functions called from the main ''MUI_NewObject()''. Splitting the GUI building function into many subfunctions has a few important advantages:
* Improved code readability and easier modifications. A single ''MUI_NewObject()'' call gets longer and longer quickly as the project evolves. Editing a large function spanning over a few screens is uncomfortable. Adding and removing GUI objects in such a function becomes nightmare even with indentation used consequently. On the other hand the function can have 10 or more indentation levels, which makes it hard to read as well.
* Code size reduction. Instead of writing very similar code multiple times, for example buttons with different labels, a subroutine may be called with label as an argument.
* Debugging. It happens sometimes that MUI refuses to create the application object because of some buggy tags or values passed. If the main ''MUI_NewObject()'' call is split into subfunctions, it is easy to isolate the buggy object by inserting some ''Printf()''-s in subfunctions.

==Methods and Attributes==
The SciMark GUI just designed, defines six actions of the application. There are five actions of running individual benchmarks and the sixth one of running all the tests and calculate the global result. Actions will be directly mapped to an ''Application'' subclass methods. There is also one attribute connected with "Large Data" button, it determines sizes of problems solved by benchmarks. Methods do not need any parameters, so there is no need to define method messages. An attribute may be applicable at init time (in the object constructor), may be also settable (needs ''OM_SET()'' [[Overriding OM_SET()|method overriding]]) and gettable (needs ''OM_GET()'' [[Overriding OM_GET()|method overriding]]). Our new attribute, named ''APPA_LargeData'' in the code only needs to be settable. In the constructor it can be implicitly set to ''FALSE'', as the button is switched off initially. Gettability is not needed, because this attribute will be used only inside the ''Application'' subclass.

It is recommended that every subclass in the application is placed in a separate source file. It helps to keep code modularity and also allows for [[Short BOOPSI Overview#Classes|hiding class private data]]. This requires writing a makefile, but one is needed anyway, as the original SciMark code consists of multiple files. Implementing the design directions discussed above a [http://krashan.ppa.pl/morphzone_tutorials/scimark2_application.h class header file] and [http://krashan.ppa.pl/morphzone_tutorials/scimark2_application.c class code] can be written. The class still does nothing, just implements six empty methods and overrides ''[[Overriding OM_SET()|OM_SET()]]'', ''[[Overriding Constructors|OM_NEW()]]'' and ''[[Overriding Destructors|OM_DISPOSE()]]''. In fact it is a boring template work and as such it has been generated with [http://downloads.morphzone.org/find.php?find=chocolatecastle ChocolateCastle] template generator. Unfortunately ChocolateCastle is still beta, so files had to be tweaked manually after generation.

The next step in the application design is to connect methods and attributes with GUI elements using [[Event Driven Programming, Notifications#Notifications in MUI|notifications]]. Notifications must be of course created after both source and target object are created. In the SciMark code they are just set up after executing ''build_gui()''. All the six action buttons have very similar notifications, so only one is shown here:

DoMethod(findobj(OBJ_BUTTON_FFT, App), MUIM_Notify, MUIA_Pressed, FALSE,
App, 1, APPM_FastFourierTransform);

"Large Data" button has a notification setting the corresponding attribute:

DoMethod(findobj(OBJ_BUTTON_LDATA, App), MUIM_Notify, MUIA_Selected, MUIV_EveryTime,
App, 3, MUIM_Set, APPA_LargeData, MUIV_TriggerValue);

Notified objects are accessed with [[Locating Objects in the Object Tree|dynamic search]] (the ''findobj()'' macro), which saves from defining global variables for all of them.

==Implementing Functionality==
Five methods implementing single SciMark benchmarks are very similar, so only one, running the Fast Fourier Transform has been shown:

IPTR ApplicationFastFourierTransform(Class *cl, Object *obj)
{
struct ApplicationData *d = INST_DATA(cl, obj);
double result;
LONG fft_size;

if (d->LargeData) fft_size = LG_FFT_SIZE;
else fft_size = FFT_SIZE;

SetAttrs(findobj(OBJ_STATUS_BAR, obj),
MUIA_Gauge_InfoText, (LONG)"Performing Fast Fourier Transform test...",
MUIA_Gauge_Current, 0,
TAG_END);

set(findobj(OBJ_RESULT_FFT, obj), MUIA_Text_Contents, "");
set(obj, MUIA_Application_Sleep, TRUE);
result = kernel_measureFFT(fft_size, RESOLUTION_DEFAULT, d->R);
NewRawDoFmt("%.2f MFlops (N = %ld)", RAWFMTFUNC_STRING, d->Buf, result, fft_size);
set(findobj(OBJ_RESULT_FFT, obj), MUIA_Text_Contents, d->Buf);
set(obj, MUIA_Application_Sleep, FALSE);
set(findobj(OBJ_STATUS_BAR, obj), MUIA_Gauge_InfoText, "Ready.");
return 0;
}

The code uses [[Locating Objects in the Object Tree|dynamic object tree search]] for accessing MUI objects.

The method sets the benchmark data size first, based on ''d->LargeData'' switch variable. This variable is set with ''APPA_LargeData'' attribute, which in turn is bound to the "Large Data" button via notification. Then the status bar progress is cleared and a text is set to inform a user what is being done. The result textfield for the benchmark is cleared as well.

The next step is to put the application in the "busy" state. It should be always done, when the application may be not responding for user input for a time longer than, let's say half a second. Setting ''MUIA_Application_Sleep'' to ''TRUE'' locks the GUI and displays the busy mouse pointer, when the application window is active. Of course offloading processor intenstve task to a subprocess is a better solution in general case, but for a benchmark it makes little sense. A user has to wait for the benchmark result anyway before doing anything else, like starting another benchmark. The only usablility problem is that a benchmark can't be stopped before it finishes. Let's leave it as is for now, for a benchmark, where the computer is expected to use all its computing power for benchmarking, a few seconds of GUI being unresponsive is not such a big problem.

The next line of code runs the benchmark, by calling ''kernel_measureFFT()'' function from the original SciMark code. After the benchmark is done, the result is formatted and displayed in the result field using ''NewRawDoFmt()'', which is a low-level string formatting function from ''exec.library'' and with ''RAWFMTFUNC_STRING'' constant works just like ''sprintf()''. It uses a fixed buffer of 128 characters (which is much more than needed, but adds a safety margin) located in the object instance data. Unsleeping the application and setting status bar text to "Ready." ends the method.

The ''APPM_AllBenchmarks()'' method code is longer so it is not repeated here. The method is very similar to a single benchmark one anyway. The difference is it runs all 5 tests accumulatig their results in a table. It also updates the progress bar after every benchmark. Finally it calculates a mean score and displays it.

==Final Port==
[http://krashan.ppa.pl/morphzone_tutorials/scimark2_mui.lha The complete source of SciMark2 MUI port]

The program may be built by running ''make'' in the source directory.

Subclassing Application Class

2011-01-07T06:10:16Z

AusPPC:

''Grzegorz Kraszewski''

Every MUI application is (or at least should be) an event driven one. This means the application provides a set of actions, which may be triggered with user activity (like using the mouse and keyboard). The straightforward way of implementing this set of actions is to implement it as a set of methods added to some MUI object. For simple programs, the best candidate for adding such methods is the master ''Application'' object. More complex programs (for example ones using a multi-document interface) may add actions to other classes, for example the ''Window'' class.

Why methods? Implementing actions as methods has many advantages:
* Methods may be used directly as notification actions. It saves a programmer from using hook tricks or cluttering the main loop with lots of ''ReturnID'' values.
* Methods may be coupled directly with scripting language interface (formerly known as ARexx interface) commands.
* Methods used in notifications are executed immediately in response to user actions. No delay is introduced by the main loop (especially if it is not empty).
* A notification triggering attribute value may be [[Event Driven Programming, Notifications#Reusing Triggering Value|passed directly]] to a method as its parameter.
* Using methods improves code modularity and object encapsulation. Functionality meant to be handled in the scope of an object is handled in its method, without the code spreading across the project.

In a well designed MUI program, all program actions and functionality are implemented as methods and the program internal state is stored as a set of attributes and internal application instance data fields. An example of such a program is discussed throughly in the [[MUI Subclassing Tutorial: SciMark2 Port]] article.

Overriding OM GET()

2011-01-07T06:05:14Z

AusPPC:

''Grzegorz Kraszewski''

The ''OM_GET()'' method, used for getting an attribute from an object, receives an opGet structure as its message. The structure is defined in the ''<intuition/classusr.h>'' header file:

struct opGet
{
ULONG MethodID; /* always OM_GET (0x104) */
ULONG opg_AttrID;
ULONG *opg_Storage;
};

Unlike ''[[Overriding OM_SET()|OM_SET()]]'', this method handles only one attribute at a time. The attribute is placed in the ''opg_AttrID'' field. The field ''opg_Storage'' is a '''pointer''' to a place where the attribute value should be stored. It is defined as a pointer to ULONG, but it may point to anything (for example to some larger structure). It allows for passing attributes not fitting in a 32-bit variable. Because ''OM_GET()'' does not have a taglist iteration loop, its implementation is simple:

IPTR MyClassGet(Class *cl, Object *obj, struct opGet *msg)
{
switch (msg->opg_AttrID)
{
case Some_Integer_Tag:
*msg->opg_Storage = /* value of the tag */;
return TRUE;

case Some_String_Tag:
*(char**)msg->opg_Storage = "a fixed string value";
return TRUE;
}

return DoSuperMethodA(cl, obj, (Msg)msg);
}

The implementation consists of a ''switch'' statement with ''cases'' for all recognized attributes. If an attribute is recognized, the method should return ''TRUE''. It is very important, as [[Event Driven Programming, Notifications#Notifications in MUI|MUI notifications]] rely on OM_GET() and will not work on the attribute if ''TRUE'' is not returned. Unknown attributes are passed to the superclass. The ''DoSuperMethodA()'' call may be alternatively placed as the ''default'' clause of the ''switch'' statement. It is important that ''msg->opg_Storage'' is '''dereferenced''' when storing the attribute value. If the value type is not integer, a typecast is needed. For a value type ''T'', the dereferencing combined with typecast is denoted as ''*(T*)''.

An Introduction to MorphOS PPC Assembly

2011-01-07T06:00:00Z

AusPPC: /* The Old And The New */

==Jump In The Deep End And Compile Something Right Now==

You could copy and paste but just entering the two lines below into a suitable text editor is probably quicker.

<pre>
.text
blr
</pre>

Save as ''shorty.s''

'''.text''' is an assembler directive - more about it later. '''blr''' is one of many branch instructions. This particular one means 'Branch to Link Register'. When a program terminates, this is the last instruction to be executed and it causes the sequence of instruction execution to pass back to the calling program or environment (shell, Ambient etc). Subroutines can also terminate with this instruction but, again, more about this later.

This is as good a time as any to ask if you've installed vbcc yet - if not, go and do it. [http://mail.pb-owl.de/~frank/vbcc/current/vbcc_bin_morphos.lha Download vbcc]

Once vbcc is installed, open a shell window and change directory to where shorty.s has been saved.

Enter:

<pre>
vasmppc_std -Felf -o ram:shorty.o shorty.s
</pre>

This tells vasm to generate an ELF formatted object file called ''shorty.o'' in ram: from the ''shorty.s'' source file.

==Hello? World's Shortest MorphOS Program - Or Is It?==

There are times when a linker is needed to further process an object file to generate an executable - this isn't one of those times.

Go ahead and enter this into the shell window:

<pre>
ram:shorty.o
</pre>

It will appear as if nothing happens - but at least it happens very quickly. However, something did happen. ''shorty.o'' was identified as an executable program and loaded into memory where the cpu instruction execution sequence passed to it. As mentioned above, the single '''blr''' instruction in this program caused the instruction execution sequence to pass directly back to where it was called from - in this case, the shell.

It may be of interest to know that all PPC instructions are four bytes long. In PPC nomenclature, this length is known as a '''word'''. But let's take a moment to have a look at the size of ''shorty.o''

Enter this into the shell window:

<pre>
list ram:shorty.o
</pre>

2664 bytes?! But this is typical for object files as they contain much additional information that is used in the process of debugging and linking. Linking, particularly with the '''-s''' 'strip all symbols' option, will generate an executable that is noticeably smaller.

Try entering this into the shell window:

<pre>
vlink -s -o ram:shorty ram:shorty.o

list ram:shorty
</pre>

The newly generated executable is 328 bytes - much smaller than its object file but what are those other 324 bytes doing there? They are the ELF 'container' that holds the single, four byte instruction of ''shorty''. ELF stands for Executable and Linkable Format and it is used by MorphOS, AmigaOS4 and AROS - not to forget, Linux, UNIX, BSD and even video game consoles. There is abundant information about this file format online but this topic will be discussed a little further when the use of the ''objdump'' program is introduced.

==The Old And The New==

Generally, in order to make a program that does something useful or to at least produce an observable result, it is necessary to use operating system library functions. Despite the markedly different cpu family that MorphOS runs on compared to the 68k family used by the classic AmigaOS, MorphOS is largely compatible with AmigaOS. This compatibility is reflected in a very similar API shared with AmigaOS and extends to using a MorphOS system structure as if it were the internal data and address registers of an actual 68k processor. This is called the EmulHandle structure and it is always available through the PPC GPR2 register. Also, as with 68k AmigaOS, the address of the Exec library base is always to be found at memory location 4. Many aspects of the AmigaOS API fit closely to the features available in the 68k cpu and the following code comparison should illustrate how it is echoed in the PPC MorphOS API.

A common task performed during the initialisation of many programs - opening the Dos library. It is a particularly simple example of library usage but most functions follow this form.

[[File:Old-and-new.png]]

'''@h''' '''@ha''' & '''@l''' attributes are needed to specify the high and low halfwords of 32 bit immediate values because the fixed 32 bit size of PPC instructions does not allow enough space for an instruction opcode and additional 32 bits of data. The difference between '''@h''' and '''@ha''' is due to the common use of the '''addi''' (add immediate) instruction, which only takes a signed immediate value, to provide the lower 16 bits of a 32 bit constant - such as an address. Sometimes these lower 16 bits will equate to a negative value and it is then that prior use of the '''@ha''' attribute will cause its immediate value to be adjusted to compensate. These details are only resolved before execution, when the program is loaded. The '''@h''' attribute just specifies the upper halfword of a 32 bit constant without regard for what follows. While I'm banging on about such intricacies, the meaning of ''zero'' in ''load word and zero'' of the '''lwz''' instruction is that on 64 bit PPC processors, this instruction will load a 32 bit value from memory into the lower word of a 64 bit GPR and then clear (or zero) its upper word. Something to consider when MorphOS is available on G5 class computers... 

One could be forgiven for thinking that the PPC code snippet looks a little ungainly compared to the former. Whereas every PPC instruction is four bytes long, 68k instructions can be as little as two bytes but up to as many as ten. A single 68k instruction can load a value from a 32 bit memory address specified by one instruction operand and store it at another 32 bit memory address specified by the second instruction operand. The 68k can also perform other operations beyond simple loads and stores directly on memory. Or at least appear to... In truth, computer memory only sends and receives data - no other data processing (like adding, subtracting & etc) occurs in memory. While the 68k instruction '''add.l #$12345678,(a0)''' appears to add the immediate value of it's first operand to whatever may already be stored at the address pointed to by a0, the contents of that address are actually loaded from memory into a private work register, the addition is performed and then the result is stored back to the same memory location. So this instruction actually performs two memory accesses where it might appear that there was only one. Contrast this with PPC assembly programming where memory loads and stores are all done explicitly. Before data can be operated upon it must be loaded from memory into a GPR (General Purpose Register), zero (in the case of a simple memory copy) or more operations can then be performed and then the data may be stored back to memory.

Unless you are brand-spanking-new to the topic of PPC assembly, you will already know that the PPC has 32 GPRs - r0 through r31. But did you know that the desired use of these registers is set out in something called the System V.4 ABI which MorphOS adheres to?

<pre>
r0 - volatile
r1 - stack pointer
r2 - for system use (with MorphOS, r2 points to the EmulHandle structure)

r3 - initialised with a pointer to a Dos command buffer
r4 - initialised with the length of the Dos command buffer
r5 - initialised with a pointer to an ELF structure

r3 ... r10 volatile & can be used to pass function arguments. If more
arguments are required, the stack is used.

r11 & r12 - volatile

r13 - small data area pointer. If this register is needed by a function or
subroutine, it must be saved first and then restored before
returning to where it was called from.

r14 ... r31 - No predefined purpose. If these registers are needed by a
function or subroutine, they must be saved first and then restored
before returning to where it was called from.
</pre>

The above use of the word 'volatile' means that functions are not expected to preserve the contents of these registers. r1 & r2 are the only registers that must be restored to their initial values by a terminating program, however, while most programs will modify r1 and later restore it, it is best to have not modified r2 in the first place.

This System V.4 ABI also sets out a particular way for programs and subroutines to organise their stack frames. When a program is loaded into memory and the instruction execution sequence passes to it, the stack pointer is still pointing to the calling program's stack frame and there is also an important address stored in the Link Register at this time. Unless this program is very simple (like ''shorty'') it must save the Link Register address and, most likely, create it's own stack frame. Somewhat conveniently, there is a special position in the caller's stack frame that a callee program can save the contents of the Link Register to. This is a fairly common example of a program or subroutine's very first instructions.

[[File:Awkward-program-initialisation.png]]

'Uh?' indeed... Let's try to visualise some memory being used as stack space.

[[File:Stack-diagram16.png]]

Note that '''stwu r1,-8(r1)''' creates a two-word stack frame which is the smallest stack that a program or subroutine can have if it, in turn, calls another program, subroutine or library function. More often, a larger stack frame is created although, '''stwu r1,-4(r1)''' could be used by a program or subroutine to create a one-word stack frame but this would be redundant and such a program must not call any other program, subroutine or library function. Such a program would not need to store the value in the Link Register (LR) to prevent it from being overwritten by subsequent calls and can terminate and return to it's caller with a simple '''blr''' instruction - just like ''shorty'' does.

A further note about larger stack frames and appropriate stack sizes: For reasons relating to PPC architecture, it is a good idea to choose stack frame sizes that are multiples of 16 bytes.

This is a less common example of a program's first instructions but it may better illustrate how to use stack frames.

[[File:Program-initialisation.png]]

Let's jump ahead and look at the last few instructions involved in program termination that would 'undo' the above instructions.

[[File:Program-termination.png]]

==A Little Less Talk And A Little More Action Please==

It's time to compile another program - this one will actually do something.

But wait...

Not another 'Hello World' program... I'm afraid so. This time, copy and paste is probably quicker. Alternatively, download this fully commented [http://aminet.net/dev/src/MorphOS-PPC-HelloWorld.lha source archive].

Note that this example does not use the MorphOS SDK. Instead, some 'quick and dirty' methods are used for the sake of simplicity and readability.

<pre>
# Various library function offsets
.set _LVOOpenLibrary,-552
.set _LVOCloseLibrary,-414
.set _LVOVPrintf,-954

.set _AbsExecBase,4

# EmulHandle structure (always pointed to by r2)
.set reg_d0,0
.set reg_d1,4
.set reg_d2,8
.set reg_d3,12
.set reg_d4,16
.set reg_d5,20
.set reg_d6,24
.set reg_d7,28
.set reg_a0,32
.set reg_a1,36
.set reg_a2,40
.set reg_a3,44
.set reg_a4,48
.set reg_a5,52
.set reg_a6,56
.set reg_a7,60
.set EmulCallDirectOS,100

# Stack frame offsets
.set stack_pos0_caller_stack,0
.set stack_pos1_callerLR,4
.set stack_pos2_ExecBase,8
.set stack_pos3_DosBase,12
.set new_4_word_stack,16

.text

mflr r0
stw r0,stack_pos1_callerLR(r1)
stwu r1,-new_4_word_stack(r1)

lis r3,dosName@ha
addi r3,r3,dosName@l
stw r3,reg_a1(r2)
li r3,0
stw r3,reg_d0(r2)
li r3,_AbsExecBase
lwz r3,0(r3)
stw r3,stack_pos2_ExecBase(r1)
stw r3,reg_a6(r2)
li r3,_LVOOpenLibrary
lwz r0,EmulCallDirectOS(r2)
mtctr r0
bctrl

cmpwi r3,0
beq exit

stw r3,stack_pos3_DosBase(r1)

lis r4,string1@ha
addi r4,r4,string1@l
stw r4,reg_d1(r2)
li r4,0
stw r4,reg_d2(r2)
stw r3,reg_a6(r2)
li r3,_LVOVPrintf
lwz r0,EmulCallDirectOS(r2)
mtctr r0
bctrl

lwz r3,stack_pos3_DosBase(r1)
stw r3,reg_a1(r2)
lwz r3,stack_pos2_ExecBase(r1)
stw r3,reg_a6(r2)
li r3,_LVOCloseLibrary
lwz r0,EmulCallDirectOS(r2)
mtctr r0
bctrl

li r3,0

exit: addi r1,r1,new_4_word_stack
lwz r0,stack_pos1_callerLR(r1)
mtlr r0
blr

.rodata
#__abox__ is a special MorphOS symbol that will differentiate
__abox__: #this program from other PPC executables that can run on MorphOS...
#When linking, care should be taken to avoid stripping this symbol.
dosName:
.string "dos.library"

string1:
.string "Hello World\n"
</pre>

Save this source file as ''HelloWorld.s'' and open a shell window. Change directory to where ''HelloWorld.s'' was just saved and enter:

<pre>
vasmppc_std -Felf -o ram:hw.o HelloWorld.s
</pre>

Once again, because of the simplicity of this program, linking isn't necessary so just enter the following in the shell window:

<pre>
ram:hw.o
</pre>

Are you impressed? Feel free to modify, experiment with and improve this source code. A not-too-difficult challenge might be to change this program so that it prints the arguments given to it in the shell window - a number of small but significant changes would be needed to do this. ''Hint: Have another look at the System V.4 register usage above.''

The commented version of ''HelloWorld.s'' in the downloadable source archive gives a brief description of why the '''mtctr''' (move to Count Register) & '''bctrl''' (branch to Count Register and link) instruction pair are used in preference to '''mtlr''' (move to Link Register) & '''blrl''' (branch to Link Register and link) - being that the latter pair can degrade performance optimisations of some PPC cpus. However, the primary use of the Count Register is as a 32 bit loop counter that can be automatically decremented by certain branch instructions.

When choosing which registers to use in your own programs, be aware that use of '''r0''' in some instruction operands will not always work as you might expect. In these instructions, the actual content of '''r0''' is ignored and the result is based on the constant value zero instead. For example, imagine that '''r0''' contains the value 100 when this instruction is executed: '''addi r0,r0,50''' It looks like the result should be '''r0 = r0 + 50 = 150''' The result will actually be '''r0 = 0 + 50 = 50''' This may seem odd but, as long as the programmer is aware of it, this behaviour can be useful. A good PPC instruction reference manual will explain this, and many other things, in much greater detail. There are many of these reference documents available online - this is one of them: [http://www.freescale.com/files/product/doc/MPCFPE32B.pdf MPCFPE32B.pdf]

==MorphOS SDK, Objdump, ELFs & Sections==

In addition to installing vbcc, it is also recommended to install the [http://www.morphos-team.net/files/sdk-20100617.lha MorphOS SDK] and the [http://mail.pb-owl.de/~frank/vbcc/current/vbcc_target_ppc-morphos.lha vbcc MorphOS compiler target].

The installer script of the latter seems to expect that there is a pre-existing assign for ''include:'' and, if your system already assigns ''include:'' to somewhere, please skip over this next part.

What follows is my ''S:user-startup'' after the installation of vbcc, it's MorphOS compiler target and an additional assign that I made preceded by this comment -

''; vbcc MorphOS target needs include: to be assigned to somewhere''

<pre>
;
; MorphOS user-startup
;
; This script is executed on system boot by
; startup-sequence. You can make personal
; changes in here.
;
; $VER: user-startup 1.1
;

; Enable the following to mount the inet-handler. Note that TCP: allows
; easy access to internet, and allows scripts to listen for incoming
; connections. Some malware could abuse this.
;Mount TCP:
;BEGIN vbcc
assign >NIL: vbcc: SYS:vbcc
assign >NIL: C: vbcc:bin ADD
setenv VBCC vbcc:
;END vbcc

; vbcc MorphOS target needs include: to be assigned to somewhere
assign include: SDK:GG/os-include

;BEGIN vbcc-ppc-morphos
assign >NIL: vincludemos: vbcc:targets/ppc-morphos/include
assign >NIL: vincludemos: include: add
assign >NIL: vlibmos: vbcc:targets/ppc-morphos/lib
;END vbcc-ppc-morphos
</pre>

At this point it would be useful to have a number of freshly generated object files and executables to look at with ''objdump'' although any ELF can be used for this purpose. Note that while MorphOS 2.x system files are compiled as ELFs, they are also signed to prevent their use on MorphOS 1.x where they may not work. This signing also has the effect of causing ''objdump'' not to recognise them as ELFs.

''objdump'' can be used to reveal a lot of interesting information about an ELF including listing any symbols and sections that are present as well as disassembling. Be aware that, when disassembled, seemingly small programs can produce more output than the shell window's history buffer can hold so either redirect the output to a file or specify start and stop addresses to limit the output. Having said that, none of the files generated so far in this tutorial are at risk of overwhelming the shell's history buffer when disassembled.

''more content needed here''

As mentioned just before the previous source code example, some quick and dirty methods were used for the sake of simplicity and readability and this refers to the way library function offsets were established. The approach used will quickly become detrimental as more offsets are added. There are a number of solutions to this problem but only one will be presented here and it involves the removal of the leading underscore character from function names so that, for example, '''li r3,_LVOOpenLibrary''' becomes '''li r3,LVOOpenLibrary'''. Remove or comment out the first three '''.set''' directives that define the library function offsets and assemble with ''vasm'' as before but note that the resulting object file is no longer executable. To make this object executable, ''vlink'' is needed.

<pre>
vlink -o <desired executable name> <existing object name> -lamiga
</pre>

In the above shell command, ''-lamiga'' refers to the ''libamiga.a'' file that ''vlink'' knows to look for in ''vlibmos:'' This file contains information used to resolve many library function names to numerical values. Note that any executable generated from the above ''vlink'' command will contain a lot of symbol information that, while potentially useful, increases the size of the executable. This can be avoided with a few additions to the above command.

<pre>
vlink -s -P__abox__ -o <desired executable name> <existing object name> -lamiga
</pre>

'''-s''' strip all symbols from the output file 
'''-P<symbol>''' preserve this symbol 

For more information, please refer to the documentation for ''vlink'' and other programs installed with ''vbcc''.

Overriding OM SET()

2011-01-07T05:57:01Z

AusPPC:

''Grzegorz Kraszewski''

The ''OM_SET()'' method receives an ''opSet'' structure as its message. The structure is defined in the ''<intuition/classusr.h>'' header.

struct opSet
{
ULONG MethodID; /* always OM_SET (0x103) */
struct TagItem *ops_AttrList;
struct GadgetInfo *ops_GInfo;
};

The most important field is ''ops_AttrList''. It is a pointer to a [[Taglists|taglist]] containing attributes and values to be set. The ''ops_GInfo'' field is an obsolete legacy thing and is not used by modern components like MUI or Reggae. The method implementation should iterate the taglist and set all attributes recognized. The operation of setting an attribute may be just setting some field in an object instance data, it may also trigger some actions (like for example object redrawing). It is recommended however that complex actions are implemented as methods rather than attribute changes. A reference implementation of ''OM_SET()'' may look like this:

IPTR MyClassSet(Class *cl, Object *obj, struct opSet *msg)
{
struct TagItem *tag, *tagptr;
IPTR tagcount = 0;

tagptr = msg->ops_AttrList;

while ((tag = '''NextTagItem'''(&tagptr)) != NULL)
{
switch (tag->ti_Tag)
{
case SOME_TAG:
/* attribute setting actions for SOME_TAG */
tagcount++;
break;

/* more tags here */
}
}

tagcount += '''DoSuperMethodA'''(cl, obj, (Msg)msg);
return tagcount;
}

The taglist iteration is done with the ''NextTagItem()'' function from the utility.library. The function returns a pointer to the next tag each time it is called and keeps the current position in ''tagptr''. The advantage of this function is automatic handling of special tag values (''TAG_MORE'', ''TAG_IGNORE'', ''TAG_SKIP''), they are not returned, but their actions are performed instead.

The ''OM_SET()'' function returns the total number of recognized tags. It is implemented with ''tagcounter''. It gets incremented on every tag recognized and finally the number of tags recognized by superclass(es) is added.

Common bugs in ''OM_SET()'' implementation are: ignoring tag counting and calling the super method in the ''default'' case of a ''switch'' statement. The second bug causes the supermethod to be called multiple times, once for every tag not handled by the subclass.

----
In some rare cases a subclass may want to override an attribute completely, so it is not passed to superclasses. This can be done by replacing the tag (not value!) by ''TAG_IGNORE''. There is one caveat however. In most cases in C and C++, the taglist is built dynamically on the stack from variable arguments of a function like ''SetAttrs()''. It is possible however, that a taglist is a static object (for example a global one, or created in an allocated chunk of free memory). In this case changing a tag is a '''permanent''' operation, which may have unexpected results. This remark also applies for changing a value of a tag before passing it to a superclass. A safe solution is to clone the taglist with the ''CloneTagItems()'' function from the ''utility.library''. Then changes are made in the copy and this copy is passed to the superclass. The copy is then freed with ''FreeTagItems()''. The disadvantage of this solution is that cloning a taglist may fail due to lack of free memory and this possibility must be handled somehow.

Overriding Destructors

2011-01-07T05:50:46Z

AusPPC:

''Grzegorz Kraszewski''

The only task of a destructor is freeing resources allocated by the constructor and other methods (some resources may be allocated on-demand only). In any case the destructor must leave the object in the same state as right after ''DoSuperMethod()/DoSuperNew()'' in the constructor. After that the destructor calls a super class destructor. The destructor receives an empty message.

IPTR MyClassDispose(Class *cl, Object *obj, Msg msg)
{
struct MyClassData *d = (struct MyClassData*)INST_DATA(cl, obj);

if (d->ResourceA) FreeResourceA();
if (d->ResourceB) FreeResourceB();
if (d->ResourceC) FreeResourceC();
return DoSuperMethodA(cl, obj, msg);
}

The example destructor follows the example of the constructor in the [[Overriding Constructors]] article. Three resources obtained in the constructor are freed here. The destructor is also prepared for a partially constructed object, every resource is checked against ''NULL'' before freeing. If for some type of resource NULL is a valid handle, an additional flag may be added to the object instance data area.

Overriding Constructors

2011-01-07T05:45:38Z

AusPPC: Small typo and readability fixes.

''Grzegorz Kraszewski''

==Objects without child objects==

An object constructor (''OM_NEW()'' method), takes the same message structure ''opSet'' as the ''[[Overriding OM_SET()|OM_SET()]]'' method. The message contains the ''ops_AttrList'' field, being a pointer to a [[Taglists|taglist]] containing the initial object's attributes. Implementation of a constructor for an object without child objects is simple. The superclass constructor is called first, then, if it succeeds, the constructor initializes object instance data, allocates resources needed and sets initial values of attributes from tags passed via ''ops_AttrList''.

A rule of thumb when overriding constructors is to '''never leave a half-constructed object'''. The constructor should either return a fully constructed object, or fail completely, freeing all successfully obtained resources. This is important if the object obtains more than one resource and any of the resource allocation has failed (for example allocating a big chunk of memory or opening a file). An example implementation below obtains three resources: ''A'', ''B'' and ''C'':

IPTR MyClassNew(Class *cl, Object *obj, struct opSet *msg)
{
if (obj = DoSuperMethodA(cl, obj, (Msg)msg))
{
struct MyClassData *d = (struct MyClassData*)INST_DATA(cl, obj);

if ((d->ResourceA = ObtainResourceA()
&& (d->ResourceB = ObtainResourceB()
&& (d->ResourceC = ObtainResourceC())
{
return (IPTR)obj; /* success */
}
else CoerceMethod(cl, obj, OM_DISPOSE);
}
return NULL;
}

If the object destructor frees resources ''A'', ''B'' and ''C'' (which would be logical considering the constructor allocates them), the cleanup job may be delegated to the destructor. It requires however, that the destructor must be prepared for destruction of a not fully constructed object. It can't assume all three resources have been allocated, so it should check every resource pointer against ''NULL'' before calling a freeing function. The destructor also takes care of calling a superclass destructor when resources are freed. See [[Overriding Destructors]] for some destructor example code and explanation.

The only question remaining is what ''CoerceMethod()'' does and why it is used instead of a plain ''DoMethod()''? The ''CoerceMethod()'' call works exactly the same as ''DoMethod()'', but performs '''method coercion''' by a forced call to the dispatcher of the class specified as the first argument instead of the dispatcher of the object's true class. It makes a difference, when the class in question is later subclassed. The flowchart below explains the problem:

[[File:Coercemethod.png|center]]

The class ''B'' on the diagram is a subclass of the class ''A'' and similarly, the class ''C'' is a subclass of ''B''. Let's assume an object of the class ''C'' is being constructed. As every constructor calls the superclass first, the call goes up to ''rootclass'' (the root of all BOOPSI classes) first. Then going down the class tree, every class constructor allocates its resources. Unfortunately the constructor of class ''A'' has been unable to allocate one of its resources and decided to fail. If it had just called ''DoMethod(obj, OM_DISPOSE)'' it will unnecessarily execute destructors in classes ''B'' and ''C'', while constructors in these classes have been not yet fully executed. Even if these destructors can cope with this, calling them is superfluous. With the ''CoerceMethod()'' the destructor in the class ''A'' is called directly. Then class ''A'' constructor returns NULL, which causes constructors in classes ''B'' and ''C'' to fail immediately without resource allocation attempts.

==Objects with child objects==

While retaining the same principles, the constructor of an object with subobjects is designed a bit differently. The most commonly subclassed classes able to have child objects are ''Application'', and ''Group''. The ''Window'' class is also often subclassed in a similar way. While a ''Window'' object can have only one child, specified by ''MUIA_Window_RootObject'', this child often has multiple subobjects. The constructor should create its child objects first, then insert them into the ''ops_AttrList'' [[Taglists|taglist]] and call the superclass constructor. If it succeeds, then resources may be allocated if needed. As any of the three constructor stages may fail, proper handling of errors becomes complicated. Also inserting objects created into the taglist as values of child tags (like ''MUIA_Group_Child'') is cumbersome. Fortunately one can use the ''DoSuperNew()'' function, which merges the creation of subobjects and the calling of the superclass into one operation. It also provides automatic handling of failed child object construction. An example below is a constructor for a ''Group'' subclass putting two ''Text'' objects in the group.

IPTR MyClassNew(Class *cl, Object *obj, struct opSet *msg)
{
if (obj = DoSuperNew(cl, obj,
MUIA_Group_Child, MUI_NewObject(MUIC_Text,
/* attributes for the first subobject */
TAG_END),
MUIA_Group_Child, MUI_NewObject(MUIC_Text,
/* attributes for the second subobject */
TAG_END),
TAG_MORE, msg->ops_AttrList))
{
struct MyClassData *d = (struct MyClassData*)INST_DATA(cl, obj);

if ((d->ResourceA = ObtainResourceA()
&& (d->ResourceB = ObtainResourceB()
&& (d->ResourceC = ObtainResourceC())
{
return (IPTR)obj; /* success */
}
else CoerceMethod(cl, obj, OM_DISPOSE);
}
return NULL;
}

An important thing to observe is the fact, that ''DoSuperNew()'' '''merges''' the taglist passed to the constructor via the message ''ops_AttrList'' field and the one specified in the function arguments list. It is done with a special ''TAG_MORE'' tag, which directs a taglist iterator (like ''NextTagItem()'' function) to jump to another taglist pointed by the value of this tag. Taglist merging allows for modifying the object being constructed with tags passed to ''NewObject()'', for example adding a frame or background to the group in the above example.

The automatic handling of failed child objects works in the following way: when a subobject fails, its constructor returns ''NULL''. This ''NULL'' value is then inserted as the value of a "child" tag (''MUIA_Group_Child'') in the example. All MUI classes able to have child objects are designed in a way that:
* the constructor fails if any "child" tag has a ''NULL'' value,
* the constructor disposes any successfully constructed child objects before exiting.
Finally ''DoSuperNew()'' returns ''NULL'' as well. This design ensures that in case of any fail while building the application, all objects created are disposed and there are no orphaned ones.

Overriding Constructors

2011-01-07T05:36:33Z

AusPPC: Small typos and readability changes

''Grzegorz Kraszewski''

==Objects without child objects==

An object constructor (''OM_NEW()'' method), takes the same message structure ''opSet'' as the ''[[Overriding OM_SET()|OM_SET()]]'' method. The message contains the ''ops_AttrList'' field, being a pointer to a [[Taglists|taglist]] containing the initial object's attributes. Implementation of a constructor for an object without child objects is simple. The superclass constructor is called first, then, if it succeeds, the constructor initializes object instance data, allocates resources needed and sets initial values of attributes from tags passed via ''ops_AttrList''.

A rule of thumb when overriding constructors is to '''never leave a half-constructed object'''. The constructor should either return a fully constructed object, or fail completely, freeing all successfully obtained resources. This is important if the object obtains more than one resource and any of the resource allocation has failed (for example allocating a big chunk of memory or opening a file). An example implementation below obtains three resources: ''A'', ''B'' and ''C'':

IPTR MyClassNew(Class *cl, Object *obj, struct opSet *msg)
{
if (obj = DoSuperMethodA(cl, obj, (Msg)msg))
{
struct MyClassData *d = (struct MyClassData*)INST_DATA(cl, obj);

if ((d->ResourceA = ObtainResourceA()
&& (d->ResourceB = ObtainResourceB()
&& (d->ResourceC = ObtainResourceC())
{
return (IPTR)obj; /* success */
}
else CoerceMethod(cl, obj, OM_DISPOSE);
}
return NULL;
}

If the object destructor frees resources ''A'', ''B'' and ''C'' (which would be logical considering the constructor allocates them), the cleanup job may be delegated to the destructor. It requires however, that the destructor must be prepared for destruction of a not fully constructed object. It can't assume all three resources have been allocated, so it should check every resource pointer against ''NULL'' before calling a freeing function. The destructor also takes care of calling a superclass destructor when resources are freed. See [[Overriding Destructors]] for some destructor example code and explanation.

The only question remaining is what ''CoerceMethod()'' does and why it is used instead of a plain ''DoMethod()''? The ''CoerceMethod()'' call works exactly the same as ''DoMethod()'', but performs '''method coercion''' by a forced call to the dispatcher of the class specified as the first argument instead of the dispatcher of the object's true class. It makes a difference, when the class in question is later subclassed. The flowchart below explains the problem:

[[File:Coercemethod.png|center]]

The class ''B'' on the diagram is a subclass of the class ''A'' and similarly, the class ''C'' is a subclass of ''B''. Let's assume an object of the class ''C'' is being constructed. As every constructor calls the superclass first, the call goes up to ''rootclass'' (the root of all BOOPSI classes) first. Then going down the class tree, every class constructor allocates its resources. Unfortunately the constructor of class ''A'' has been unable to allocate one of its resources and decided to fail. If it had just called ''DoMethod(obj, OM_DISPOSE)'' it will unnecessarily execute destructors in classes ''B'' and ''C'', while constructors in these classes have been not yet fully executed. Even if these destructors can cope with this, calling them is superfluous. With the ''CoerceMethod()'' the destructor in the class ''A'' is called directly. Then class ''A'' constructor returns NULL, which causes constructors in classes ''B'' and ''C'' to fail immediately without resource allocation attempts.

==Objects with child objects==

While retaining the same principles, a constructor of object having subobjects is designed a bit differently. The most commonly subclassed classes able to have child objects are ''Application'', and ''Group''. The ''Window'' class is also often subclassed similar way. While a ''Window'' object can have only one child, specified by ''MUIA_Window_RootObject'', this child has multiple subobjects usually. The constructor should create its child objects first, then insert them into the ''ops_AttrList'' [[Taglists|taglist]] and call the superclass constructor. If it succeeds, then resources may be allocated if needed. As any of the three constructor stages may fail, proper handling of errors becomes complicated. Also inserting objects created into the taglist as values of child tags (like ''MUIA_Group_Child'') is cumbersome. Fortunately one can use the ''DoSuperNew()'' function, which merges subobjects creation and calling the superclass into one operation. It also provides automatic handling of failed child object construction. An example below is a constructor for a ''Group'' subclass putting two ''Text'' objects in the group.

IPTR MyClassNew(Class *cl, Object *obj, struct opSet *msg)
{
if (obj = DoSuperNew(cl, obj,
MUIA_Group_Child, MUI_NewObject(MUIC_Text,
/* attributes for the first subobject */
TAG_END),
MUIA_Group_Child, MUI_NewObject(MUIC_Text,
/* attributes for the second subobject */
TAG_END),
TAG_MORE, msg->ops_AttrList))
{
struct MyClassData *d = (struct MyClassData*)INST_DATA(cl, obj);

if ((d->ResourceA = ObtainResourceA()
&& (d->ResourceB = ObtainResourceB()
&& (d->ResourceC = ObtainResourceC())
{
return (IPTR)obj; /* success */
}
else CoerceMethod(cl, obj, OM_DISPOSE);
}
return NULL;
}

An important thing to observe is the fact, that ''DoSuperNew()'' '''merges''' the taglist passed to the constructor via the message ''ops_AttrList'' field and the one specified in the function arguments list. It is done with a special ''TAG_MORE'' tag, which direct a taglist iterator (like ''NextTagItem()'' function) to jump to another taglist pointed by the value of this tag. Taglist merging allows for modifying the object being constructed with tags passed to ''NewObject()'', for example adding a frame or background to the group in the above example.

The automatic handling of failed child objects works in the following way: when a subobject fails, its constructor returns ''NULL''. This ''NULL'' value is then inserted as a value of a "child" tag (''MUIA_Group_Child'') in the example. All MUI classes able to have child objects are designed in a way that:
* the constructor fails if any "child" tag has ''NULL'' value,
* the constructor disposes any succesfully constructed child objects before exiting.
Finally ''DoSuperNew()'' returns ''NULL'' as well. This design ensures that in case of any fail while building the application, all objects created are disposed and there are no orphaned ones.

An Introduction to MorphOS PPC Assembly

2011-01-06T23:10:03Z

AusPPC:

==Jump In The Deep End And Compile Something Right Now==

You could copy and paste but just entering the two lines below into a suitable text editor is probably quicker.

<pre>
.text
blr
</pre>

Save as ''shorty.s''

'''.text''' is an assembler directive - more about it later. '''blr''' is one of many branch instructions. This particular one means 'Branch to Link Register'. When a program terminates, this is the last instruction to be executed and it causes the sequence of instruction execution to pass back to the calling program or environment (shell, Ambient etc). Subroutines can also terminate with this instruction but, again, more about this later.

This is as good a time as any to ask if you've installed vbcc yet - if not, go and do it. [http://mail.pb-owl.de/~frank/vbcc/current/vbcc_bin_morphos.lha Download vbcc]

Once vbcc is installed, open a shell window and change directory to where shorty.s has been saved.

Enter:

<pre>
vasmppc_std -Felf -o ram:shorty.o shorty.s
</pre>

This tells vasm to generate an ELF formatted object file called ''shorty.o'' in ram: from the ''shorty.s'' source file.

==Hello? World's Shortest MorphOS Program - Or Is It?==

There are times when a linker is needed to further process an object file to generate an executable - this isn't one of those times.

Go ahead and enter this into the shell window:

<pre>
ram:shorty.o
</pre>

It will appear as if nothing happens - but at least it happens very quickly. However, something did happen. ''shorty.o'' was identified as an executable program and loaded into memory where the cpu instruction execution sequence passed to it. As mentioned above, the single '''blr''' instruction in this program caused the instruction execution sequence to pass directly back to where it was called from - in this case, the shell.

It may be of interest to know that all PPC instructions are four bytes long. In PPC nomenclature, this length is known as a '''word'''. But let's take a moment to have a look at the size of ''shorty.o''

Enter this into the shell window:

<pre>
list ram:shorty.o
</pre>

2664 bytes?! But this is typical for object files as they contain much additional information that is used in the process of debugging and linking. Linking, particularly with the '''-s''' 'strip all symbols' option, will generate an executable that is noticeably smaller.

Try entering this into the shell window:

<pre>
vlink -s -o ram:shorty ram:shorty.o

list ram:shorty
</pre>

The newly generated executable is 328 bytes - much smaller than its object file but what are those other 324 bytes doing there? They are the ELF 'container' that holds the single, four byte instruction of ''shorty''. ELF stands for Executable and Linkable Format and it is used by MorphOS, AmigaOS4 and AROS - not to forget, Linux, UNIX, BSD and even video game consoles. There is abundant information about this file format online but this topic will be discussed a little further when the use of the ''objdump'' program is introduced.

==The Old And The New==

Generally, in order to make a program that does something useful or to at least produce an observable result, it is necessary to use operating system library functions. Despite the markedly different cpu family that MorphOS runs on compared to the 68k family used by the classic AmigaOS, MorphOS is largely compatible with AmigaOS. This compatibility is reflected in a very similar API shared with AmigaOS and extends to using a MorphOS system structure as if it were the internal data and address registers of an actual 68k processor. This is called the EmulHandle structure and it is always available through the PPC GPR2 register. Also, as with 68k AmigaOS, the address of the Exec library base is always to be found at memory location 4. Many aspects of the AmigaOS API fit closely to the features available in the 68k cpu and the following code comparison should illustrate how it is echoed in the PPC MorphOS API.

A common task performed during the initialisation of many programs - opening the Dos library. It is a particularly simple example of library usage but most functions follow this form.

[[File:Old-and-new.png]]

'''@h''' '''@ha''' & '''@l''' attributes are needed to specify the high and low halfwords of 32 bit immediate values because the fixed 32 bit size of PPC instructions does not allow enough space for an instruction opcode and additional 32 bits of data. The difference between '''@h''' and '''@ha''' is due to the common use of the '''addi''' (add immediate) instruction, which only takes a signed immediate value, to provide the lower 16 bits of a 32 bit constant - such as an address. Sometimes these lower 16 bits will equate to a negative value and it is then that prior use of the '''@ha''' attribute will cause its immediate value to be adjusted to compensate. These details are only resolved before execution, when the program is loaded. The '''@h''' attribute just specifies the upper halfword of a 32 bit constant without regard for what follows. While I'm banging on about such intricacies, the meaning of ''zero'' in ''load word and zero'' of the '''lwz''' instruction is that on 64 bit PPC processors, this instruction will load a 32 bit value from memory into the lower word of a 64 bit GPR and then clear (or zero) its upper word. Something to consider when MorphOS is available on G5 class computers...

One could be forgiven for thinking that the PPC code snippet looks a little ungainly compared to the former. Whereas every PPC instruction is four bytes long, 68k instructions can be as little as two bytes but up to as many as ten. A single 68k instruction can load a value from a 32 bit memory address specified by one instruction operand and store it at another 32 bit memory address specified by the second instruction operand. The 68k can also perform other operations beyond simple loads and stores directly on memory. Or at least appear to... In truth, computer memory only sends and receives data - no other data processing (like adding, subtracting & etc) occurs in memory. While the 68k instruction '''add.l #$12345678,(a0)''' appears to add the immediate value of it's first operand to whatever may already be stored at the address pointed to by a0, the contents of that address are actually loaded from memory into a private work register, the addition is performed and then the result is stored back to the same memory location. So this instruction actually performs two memory accesses where it might appear that there was only one. Contrast this with PPC assembly programming where memory loads and stores are all done explicitly. Before data can be operated upon it must be loaded from memory into a GPR (General Purpose Register), zero (in the case of a simple memory copy) or more operations can then be performed and then the data may be stored back to memory.

Unless you are brand-spanking-new to the topic of PPC assembly, you will already know that the PPC has 32 GPRs - r0 through r31. But did you know that the desired use of these registers is set out in something called the System V.4 ABI which MorphOS adheres to?

<pre>
r0 - volatile
r1 - stack pointer
r2 - for system use (with MorphOS, r2 points to the EmulHandle structure)

r3 - initialised with a pointer to a Dos command buffer
r4 - initialised with the length of the Dos command buffer
r5 - initialised with a pointer to an ELF structure

r3 ... r10 volatile & can be used to pass function arguments. If more
arguments are required, the stack is used.

r11 & r12 - volatile

r13 - small data area pointer. If this register is needed by a function or
subroutine, it must be saved first and then restored before
returning to where it was called from.

r14 ... r31 - No predefined purpose. If these registers are needed by a
function or subroutine, they must be saved first and then restored
before returning to where it was called from.
</pre>

The above use of the word 'volatile' means that functions are not expected to preserve the contents of these registers. r1 & r2 are the only registers that must be restored to their initial values by a terminating program, however, while most programs will modify r1 and later restore it, it is best to have not modified r2 in the first place.

This System V.4 ABI also sets out a particular way for programs and subroutines to organise their stack frames. When a program is loaded into memory and the instruction execution sequence passes to it, the stack pointer is still pointing to the calling program's stack frame and there is also an important address stored in the Link Register at this time. Unless this program is very simple (like ''shorty'') it must save the Link Register address and, most likely, create it's own stack frame. Somewhat conveniently, there is a special position in the caller's stack frame that a callee program can save the contents of the Link Register to. This is a fairly common example of a program or subroutine's very first instructions.

[[File:Awkward-program-initialisation.png]]

'Uh?' indeed... Let's try to visualise some memory being used as stack space.

[[File:Stack-diagram16.png]]

Note that '''stwu r1,-8(r1)''' creates a two-word stack frame which is the smallest stack that a program or subroutine can have if it, in turn, calls another program, subroutine or library function. More often, a larger stack frame is created although, '''stwu r1,-4(r1)''' could be used by a program or subroutine to create a one-word stack frame but this would be redundant and such a program must not call any other program, subroutine or library function. Such a program would not need to store the value in the Link Register (LR) to prevent it from being overwritten by subsequent calls and can terminate and return to it's caller with a simple '''blr''' instruction - just like ''shorty'' does.

A further note about larger stack frames and appropriate stack sizes: For reasons relating to PPC architecture, it is a good idea to choose stack frame sizes that are multiples of 16 bytes.

This is a less common example of a program's first instructions but it may better illustrate how to use stack frames.

[[File:Program-initialisation.png]]

Let's jump ahead and look at the last few instructions involved in program termination that would 'undo' the above instructions.

[[File:Program-termination.png]]

==A Little Less Talk And A Little More Action Please==

It's time to compile another program - this one will actually do something.

But wait...

Not another 'Hello World' program... I'm afraid so. This time, copy and paste is probably quicker. Alternatively, download this fully commented [http://aminet.net/dev/src/MorphOS-PPC-HelloWorld.lha source archive].

Note that this example does not use the MorphOS SDK. Instead, some 'quick and dirty' methods are used for the sake of simplicity and readability.

<pre>
# Various library function offsets
.set _LVOOpenLibrary,-552
.set _LVOCloseLibrary,-414
.set _LVOVPrintf,-954

.set _AbsExecBase,4

# EmulHandle structure (always pointed to by r2)
.set reg_d0,0
.set reg_d1,4
.set reg_d2,8
.set reg_d3,12
.set reg_d4,16
.set reg_d5,20
.set reg_d6,24
.set reg_d7,28
.set reg_a0,32
.set reg_a1,36
.set reg_a2,40
.set reg_a3,44
.set reg_a4,48
.set reg_a5,52
.set reg_a6,56
.set reg_a7,60
.set EmulCallDirectOS,100

# Stack frame offsets
.set stack_pos0_caller_stack,0
.set stack_pos1_callerLR,4
.set stack_pos2_ExecBase,8
.set stack_pos3_DosBase,12
.set new_4_word_stack,16

.text

mflr r0
stw r0,stack_pos1_callerLR(r1)
stwu r1,-new_4_word_stack(r1)

lis r3,dosName@ha
addi r3,r3,dosName@l
stw r3,reg_a1(r2)
li r3,0
stw r3,reg_d0(r2)
li r3,_AbsExecBase
lwz r3,0(r3)
stw r3,stack_pos2_ExecBase(r1)
stw r3,reg_a6(r2)
li r3,_LVOOpenLibrary
lwz r0,EmulCallDirectOS(r2)
mtctr r0
bctrl

cmpwi r3,0
beq exit

stw r3,stack_pos3_DosBase(r1)

lis r4,string1@ha
addi r4,r4,string1@l
stw r4,reg_d1(r2)
li r4,0
stw r4,reg_d2(r2)
stw r3,reg_a6(r2)
li r3,_LVOVPrintf
lwz r0,EmulCallDirectOS(r2)
mtctr r0
bctrl

lwz r3,stack_pos3_DosBase(r1)
stw r3,reg_a1(r2)
lwz r3,stack_pos2_ExecBase(r1)
stw r3,reg_a6(r2)
li r3,_LVOCloseLibrary
lwz r0,EmulCallDirectOS(r2)
mtctr r0
bctrl

li r3,0

exit: addi r1,r1,new_4_word_stack
lwz r0,stack_pos1_callerLR(r1)
mtlr r0
blr

.rodata
#__abox__ is a special MorphOS symbol that will differentiate
__abox__: #this program from other PPC executables that can run on MorphOS...
#When linking, care should be taken to avoid stripping this symbol.
dosName:
.string "dos.library"

string1:
.string "Hello World\n"
</pre>

Save this source file as ''HelloWorld.s'' and open a shell window. Change directory to where ''HelloWorld.s'' was just saved and enter:

<pre>
vasmppc_std -Felf -o ram:hw.o HelloWorld.s
</pre>

Once again, because of the simplicity of this program, linking isn't necessary so just enter the following in the shell window:

<pre>
ram:hw.o
</pre>

Are you impressed? Feel free to modify, experiment with and improve this source code. A not-too-difficult challenge might be to change this program so that it prints the arguments given to it in the shell window - a number of small but significant changes would be needed to do this. ''Hint: Have another look at the System V.4 register usage above.''

The commented version of ''HelloWorld.s'' in the downloadable source archive gives a brief description of why the '''mtctr''' (move to Count Register) & '''bctrl''' (branch to Count Register and link) instruction pair are used in preference to '''mtlr''' (move to Link Register) & '''blrl''' (branch to Link Register and link) - being that the latter pair can degrade performance optimisations of some PPC cpus. However, the primary use of the Count Register is as a 32 bit loop counter that can be automatically decremented by certain branch instructions.

When choosing which registers to use in your own programs, be aware that use of '''r0''' in some instruction operands will not always work as you might expect. In these instructions, the actual content of '''r0''' is ignored and the result is based on the constant value zero instead. For example, imagine that '''r0''' contains the value 100 when this instruction is executed: '''addi r0,r0,50''' It looks like the result should be '''r0 = r0 + 50 = 150''' The result will actually be '''r0 = 0 + 50 = 50''' This may seem odd but, as long as the programmer is aware of it, this behaviour can be useful. A good PPC instruction reference manual will explain this, and many other things, in much greater detail. There are many of these reference documents available online - this is one of them: [http://www.freescale.com/files/product/doc/MPCFPE32B.pdf MPCFPE32B.pdf]

==MorphOS SDK, Objdump, ELFs & Sections==

In addition to installing vbcc, it is also recommended to install the [http://www.morphos-team.net/files/sdk-20100617.lha MorphOS SDK] and the [http://mail.pb-owl.de/~frank/vbcc/current/vbcc_target_ppc-morphos.lha vbcc MorphOS compiler target].

The installer script of the latter seems to expect that there is a pre-existing assign for ''include:'' and, if your system already assigns ''include:'' to somewhere, please skip over this next part.

What follows is my ''S:user-startup'' after the installation of vbcc, it's MorphOS compiler target and an additional assign that I made preceded by this comment -

''; vbcc MorphOS target needs include: to be assigned to somewhere''

<pre>
;
; MorphOS user-startup
;
; This script is executed on system boot by
; startup-sequence. You can make personal
; changes in here.
;
; $VER: user-startup 1.1
;

; Enable the following to mount the inet-handler. Note that TCP: allows
; easy access to internet, and allows scripts to listen for incoming
; connections. Some malware could abuse this.
;Mount TCP:
;BEGIN vbcc
assign >NIL: vbcc: SYS:vbcc
assign >NIL: C: vbcc:bin ADD
setenv VBCC vbcc:
;END vbcc

; vbcc MorphOS target needs include: to be assigned to somewhere
assign include: SDK:GG/os-include

;BEGIN vbcc-ppc-morphos
assign >NIL: vincludemos: vbcc:targets/ppc-morphos/include
assign >NIL: vincludemos: include: add
assign >NIL: vlibmos: vbcc:targets/ppc-morphos/lib
;END vbcc-ppc-morphos
</pre>

At this point it would be useful to have a number of freshly generated object files and executables to look at with ''objdump'' although any ELF can be used for this purpose. Note that while MorphOS 2.x system files are compiled as ELFs, they are also signed to prevent their use on MorphOS 1.x where they may not work. This signing also has the effect of causing ''objdump'' not to recognise them as ELFs.

''objdump'' can be used to reveal a lot of interesting information about an ELF including listing any symbols and sections that are present as well as disassembling. Be aware that, when disassembled, seemingly small programs can produce more output than the shell window's history buffer can hold so either redirect the output to a file or specify start and stop addresses to limit the output. Having said that, none of the files generated so far in this tutorial are at risk of overwhelming the shell's history buffer when disassembled.

''more content needed here''

As mentioned just before the previous source code example, some quick and dirty methods were used for the sake of simplicity and readability and this refers to the way library function offsets were established. The approach used will quickly become detrimental as more offsets are added. There are a number of solutions to this problem but only one will be presented here and it involves the removal of the leading underscore character from function names so that, for example, '''li r3,_LVOOpenLibrary''' becomes '''li r3,LVOOpenLibrary'''. Remove or comment out the first three '''.set''' directives that define the library function offsets and assemble with ''vasm'' as before but note that the resulting object file is no longer executable. To make this object executable, ''vlink'' is needed.

<pre>
vlink -o <desired executable name> <existing object name> -lamiga
</pre>

In the above shell command, ''-lamiga'' refers to the ''libamiga.a'' file that ''vlink'' knows to look for in ''vlibmos:'' This file contains information used to resolve many library function names to numerical values. Note that any executable generated from the above ''vlink'' command will contain a lot of symbol information that, while potentially useful, increases the size of the executable. This can be avoided with a few additions to the above command.

<pre>
vlink -s -P__abox__ -o <desired executable name> <existing object name> -lamiga
</pre>

'''-s''' strip all symbols from the output file 
'''-P<symbol>''' preserve this symbol 

For more information, please refer to the documentation for ''vlink'' and other programs installed with ''vbcc''.

An Introduction to MorphOS PPC Assembly

2011-01-06T23:08:00Z

AusPPC:

==Jump In The Deep End And Compile Something Right Now==

You could copy and paste but just entering the two lines below into a suitable text editor is probably quicker.

<pre>
.text
blr
</pre>

Save as ''shorty.s''

'''.text''' is an assembler directive - more about it later. '''blr''' is one of many branch instructions. This particular one means 'Branch to Link Register'. When a program terminates, this is the last instruction to be executed and it causes the sequence of instruction execution to pass back to the calling program or environment (shell, Ambient etc). Subroutines can also terminate with this instruction but, again, more about this later.

This is as good a time as any to ask if you've installed vbcc yet - if not, go and do it. [http://mail.pb-owl.de/~frank/vbcc/current/vbcc_bin_morphos.lha Download vbcc]

Once vbcc is installed, open a shell window and change directory to where shorty.s has been saved.

Enter:

<pre>
vasmppc_std -Felf -o ram:shorty.o shorty.s
</pre>

This tells vasm to generate an ELF formatted object file called ''shorty.o'' in ram: from the ''shorty.s'' source file.

==Hello? World's Shortest MorphOS Program - Or Is It?==

There are times when a linker is needed to further process an object file to generate an executable - this isn't one of those times.

Go ahead and enter this into the shell window:

<pre>
ram:shorty.o
</pre>

It will appear as if nothing happens - but at least it happens very quickly. However, something did happen. ''shorty.o'' was identified as an executable program and loaded into memory where the cpu instruction execution sequence passed to it. As mentioned above, the single '''blr''' instruction in this program caused the instruction execution sequence to pass directly back to where it was called from - in this case, the shell.

It may be of interest to know that all PPC instructions are four bytes long. In PPC nomenclature, this length is known as a '''word'''. But let's take a moment to have a look at the size of ''shorty.o''

Enter this into the shell window:

<pre>
list ram:shorty.o
</pre>

2664 bytes?! But this is typical for object files as they contain much additional information that is used in the process of debugging and linking. Linking, particularly with the '''-s''' 'strip all symbols' option, will generate an executable that is noticeably smaller.

Try entering this into the shell window:

<pre>
vlink -s -o ram:shorty ram:shorty.o

list ram:shorty
</pre>

The newly generated executable is 328 bytes - much smaller than its object file but what are those other 324 bytes doing there? They are the ELF 'container' that holds the single, four byte instruction of ''shorty''. ELF stands for Executable and Linkable Format and it is used by MorphOS, AmigaOS4 and AROS - not to forget, Linux, UNIX, BSD and even video game consoles. There is abundant information about this file format online but this topic will be discussed a little further when the use of the ''objdump'' program is introduced.

==The Old And The New==

Generally, in order to make a program that does something useful or to at least produce an observable result, it is necessary to use operating system library functions. Despite the markedly different cpu family that MorphOS runs on compared to the 68k family used by the classic AmigaOS, MorphOS is largely compatible with AmigaOS. This compatibility is reflected in a very similar API shared with AmigaOS and extends to using a MorphOS system structure as if it were the internal data and address registers of an actual 68k processor. This is called the EmulHandle structure and it is always available through the PPC GPR2 register. Also, as with 68k AmigaOS, the address of the Exec library base is always to be found at memory location 4. Many aspects of the AmigaOS API fit closely to the features available in the 68k cpu and the following code comparison should illustrate how it is echoed in the PPC MorphOS API.

A common task performed during the initialisation of many programs - opening the Dos library. It is a particularly simple example of library usage but most functions follow this form.

[[File:Old-and-new.png]]

'''@h''' '''@ha''' & '''@l''' attributes are needed to specify the high and low halfwords of 32 bit immediate values because the fixed 32 bit size of PPC instructions does not allow enough space for an instruction opcode and additional 32 bits of data. The difference between '''@h''' and '''@ha''' is due to the common use of the '''addi''' (add immediate) instruction, which only takes a signed immediate value, to provide the lower 16 bits of a 32 bit constant - such as an address. Sometimes these lower 16 bits will equate to a negative value and it is then that prior use of the '''@ha''' attribute will cause its immediate value to be adjusted to compensate. These details are only resolved before execution, when the program is loaded. The '''@h''' attribute just specifies the upper halfword of a 32 bit constant without regard for what follows. While I'm banging on about such intricacies, the meaning of ''zero'' in ''load word and zero'' of the '''lwz''' instruction is that on 64 bit PPC processors, this instruction will load a 32 bit value from memory into the lower word of a 64 bit GPR and then clear (or zero) its upper word. Something to consider when MorphOS is available on G5 class computers...

One could be forgiven for thinking that the PPC code snippet looks a little ungainly compared to the former. Whereas every PPC instruction is four bytes long, 68k instructions can be as little as two bytes but up to as many as ten. A single 68k instruction can load a value from a 32 bit memory address specified by one instruction operand and store it at another 32 bit memory address specified by the second instruction operand. The 68k can also perform other operations beyond simple loads and stores directly on memory. Or at least appear to... In truth, computer memory only sends and receives data - no other data processing (like adding, subtracting & etc) occurs in memory. While the 68k instruction '''add.l #$12345678,(a0)''' appears to add the immediate value of it's first operand to whatever may already be stored at the address pointed to by a0, the contents of that address are actually loaded from memory into a private work register, the addition is performed and then the result is stored back to the same memory location. So this instruction actually performs two memory accesses where it might appear that there was only one. Contrast this with PPC assembly programming where memory loads and stores are all done explicitly. Before data can be operated upon it must be loaded from memory into a GPR (General Purpose Register), zero (in the case of a simple memory copy) or more operations can then be performed and then the data may be stored back to memory.

Unless you are brand-spanking-new to the topic of PPC assembly, you will already know that the PPC has 32 GPRs - r0 through r31. But did you know that the desired use of these registers is set out in something called the System V.4 ABI which MorphOS adheres to?

<pre>
r0 - volatile
r1 - stack pointer
r2 - for system use (with MorphOS, r2 points to the EmulHandle structure)

r3 - initialised with a pointer to a Dos command buffer
r4 - initialised with the length of the Dos command buffer
r5 - initialised with a pointer to an ELF structure

r3 ... r10 volatile & can be used to pass function arguments. If more
arguments are required, the stack is used.

r11 & r12 - volatile

r13 - small data area pointer. If this register is needed by a function or
subroutine, it must be saved first and then restored before
returning to where it was called from.

r14 ... r31 - No predefined purpose. If these registers are needed by a
function or subroutine, they must be saved first and then restored
before returning to where it was called from.
</pre>

The above use of the word 'volatile' means that functions are not expected to preserve the contents of these registers. r1 & r2 are the only registers that must be restored to their initial values by a terminating program, however, while most programs will modify r1 and later restore it, it is best to have not modified r2 in the first place.

This System V.4 ABI also sets out a particular way for programs and subroutines to organise their stack frames. When a program is loaded into memory and the instruction execution sequence passes to it, the stack pointer is still pointing to the calling program's stack frame and there is also an important address stored in the Link Register at this time. Unless this program is very simple (like ''shorty'') it must save the Link Register address and, most likely, create it's own stack frame. Somewhat conveniently, there is a special position in the caller's stack frame that a callee program can save the contents of the Link Register to. This is a fairly common example of a program or subroutine's very first instructions.

[[File:Awkward-program-initialisation.png]]

'Uh?' indeed... Let's try to visualise some memory being used as stack space.

[[File:Stack-diagram16.png]]

Note that '''stwu r1,-8(r1)''' creates a two-word stack frame which is the smallest stack that a program or subroutine can have if it, in turn, calls another program, subroutine or library function. More often, a larger stack frame is created although, '''stwu r1,-4(r1)''' could be used by a program or subroutine to create a one-word stack frame but this would be redundant and such a program must not call any other program, subroutine or library function. Such a program would not need to store the value in the Link Register (LR) to prevent it from being overwritten by subsequent calls and can terminate and return to it's caller with a simple '''blr''' instruction - just like ''shorty'' does.

A further note about larger stack frames and appropriate stack sizes: For reasons relating to PPC architecture, it is a good idea to choose stack frame sizes that are multiples of 16 bytes.

This is a less common example of a program's first instructions but it may better illustrate how to use stack frames.

[[File:Program-initialisation.png]]

Let's jump ahead and look at the last few instructions involved in program termination that would 'undo' the above instructions.

[[File:Program-termination.png]]

==A Little Less Talk And A Little More Action Please==

It's time to compile another program - this one will actually do something.

But wait...

Not another 'Hello World' program... I'm afraid so. This time, copy and paste is probably quicker. Alternatively, download this fully commented [http://aminet.net/dev/src/MorphOS-PPC-HelloWorld.lha source archive].

Note that this example does not use the MorphOS SDK. Instead, some 'quick and dirty' methods are used for the sake of simplicity and readability.

<pre>
# Various library function offsets
.set _LVOOpenLibrary,-552
.set _LVOCloseLibrary,-414
.set _LVOVPrintf,-954

.set _AbsExecBase,4

# EmulHandle structure (always pointed to by r2)
.set reg_d0,0
.set reg_d1,4
.set reg_d2,8
.set reg_d3,12
.set reg_d4,16
.set reg_d5,20
.set reg_d6,24
.set reg_d7,28
.set reg_a0,32
.set reg_a1,36
.set reg_a2,40
.set reg_a3,44
.set reg_a4,48
.set reg_a5,52
.set reg_a6,56
.set reg_a7,60
.set EmulCallDirectOS,100

# Stack frame offsets
.set stack_pos0_caller_stack,0
.set stack_pos1_callerLR,4
.set stack_pos2_ExecBase,8
.set stack_pos3_DosBase,12
.set new_4_word_stack,16

.text

mflr r0
stw r0,stack_pos1_callerLR(r1)
stwu r1,-new_4_word_stack(r1)

lis r3,dosName@ha
addi r3,r3,dosName@l
stw r3,reg_a1(r2)
li r3,0
stw r3,reg_d0(r2)
li r3,_AbsExecBase
lwz r3,0(r3)
stw r3,stack_pos2_ExecBase(r1)
stw r3,reg_a6(r2)
li r3,_LVOOpenLibrary
lwz r0,EmulCallDirectOS(r2)
mtctr r0
bctrl

cmpwi r3,0
beq exit

stw r3,stack_pos3_DosBase(r1)

lis r4,string1@ha
addi r4,r4,string1@l
stw r4,reg_d1(r2)
li r4,0
stw r4,reg_d2(r2)
stw r3,reg_a6(r2)
li r3,_LVOVPrintf
lwz r0,EmulCallDirectOS(r2)
mtctr r0
bctrl

lwz r3,stack_pos3_DosBase(r1)
stw r3,reg_a1(r2)
lwz r3,stack_pos2_ExecBase(r1)
stw r3,reg_a6(r2)
li r3,_LVOCloseLibrary
lwz r0,EmulCallDirectOS(r2)
mtctr r0
bctrl

li r3,0

exit: addi r1,r1,new_4_word_stack
lwz r0,stack_pos1_callerLR(r1)
mtlr r0
blr

.rodata
#__abox__ is a special MorphOS symbol that will differentiate
__abox__: #this program from other PPC executables that can run on MorphOS...
#When linking, care should be taken to avoid stripping this symbol.
dosName:
.string "dos.library"

string1:
.string "Hello World\n"
</pre>

Save this source file as ''HelloWorld.s'' and open a shell window. Change directory to where ''HelloWorld.s'' was just saved and enter:

<pre>
vasmppc_std -Felf -o ram:hw.o HelloWorld.s
</pre>

Once again, because of the simplicity of this program, linking isn't necessary so just enter the following in the shell window:

<pre>
ram:hw.o
</pre>

Are you impressed? Feel free to modify, experiment with and improve this source code. A not-too-difficult challenge might be to change this program so that it prints the arguments given to it in the shell window - a number of small but significant changes would be needed to do this. ''Hint: Have another look at the System V.4 register usage above.''

The commented version of ''HelloWorld.s'' in the downloadable source archive gives a brief description of why the '''mtctr''' (move to Count Register) & '''bctrl''' (branch to Count Register and link) instruction pair are used in preference to '''mtlr''' (move to Link Register) & '''blrl''' (branch to Link Register and link) - being that the latter pair can degrade performance optimisations of some PPC cpus. However, the primary use of the Count Register is as a 32 bit loop counter that can be automatically decremented by certain branch instructions.

When choosing which registers to use in your own programs, be aware that use of '''r0''' in some instruction operands will not always work as you might expect. In these instructions, the actual content of '''r0''' is ignored and the result is based on the constant value zero instead. For example, imagine that '''r0''' contains the value 100 when this instruction is executed: '''addi r0,r0,50''' It looks like the result should be '''r0 = r0 + 50 = 150''' The result will actually be '''r0 = 0 + 50 = 50''' This may seem odd but, as long as the programmer is aware of it, this behaviour can be useful. A good PPC instruction reference manual will explain this, and many other things, in much greater detail. There are many of these reference documents available online - this is one of them: [http://www.freescale.com/files/product/doc/MPCFPE32B.pdf MPCFPE32B.pdf]

==MorphOS SDK, Objdump, ELFs & Sections==

In addition to installing vbcc, it is also recommended to install the [http://www.morphos-team.net/files/sdk-20100617.lha MorphOS SDK] and the [http://mail.pb-owl.de/~frank/vbcc/current/vbcc_target_ppc-morphos.lha vbcc MorphOS compiler target].

The installer script of the latter seems to expect that there is a pre-existing assign for ''include:'' and, if your system already assigns ''include:'' to somewhere, please skip over this next part.

What follows is my ''S:user-startup'' after the installation of vbcc, it's MorphOS compiler target and an additional assign that I made preceded by this comment -

''; vbcc MorphOS target needs include: to be assigned to somewhere''

<pre>
;
; MorphOS user-startup
;
; This script is executed on system boot by
; startup-sequence. You can make personal
; changes in here.
;
; $VER: user-startup 1.1
;

; Enable the following to mount the inet-handler. Note that TCP: allows
; easy access to internet, and allows scripts to listen for incoming
; connections. Some malware could abuse this.
;Mount TCP:
;BEGIN vbcc
assign >NIL: vbcc: SYS:vbcc
assign >NIL: C: vbcc:bin ADD
setenv VBCC vbcc:
;END vbcc

; vbcc MorphOS target needs include: to be assigned to somewhere
assign include: SDK:GG/os-include

;BEGIN vbcc-ppc-morphos
assign >NIL: vincludemos: vbcc:targets/ppc-morphos/include
assign >NIL: vincludemos: include: add
assign >NIL: vlibmos: vbcc:targets/ppc-morphos/lib
;END vbcc-ppc-morphos
</pre>

At this point it would be useful to have a number of freshly generated object files and executables to look at with ''objdump'' although any ELF can be used for this purpose. Note that while MorphOS 2.x system files are compiled as ELFs, they are also signed to prevent their use on MorphOS 1.x where they may not work. This signing also has the effect of causing ''objdump'' not to recognise them as ELFs.

''objdump'' can be used to reveal a lot of interesting information about an ELF including listing any symbols and sections that are present as well as disassembling. Be aware that, when disassembled, seemingly small programs can produce more output than the shell window's history buffer can hold so either redirect the output to a file or specify start and stop addresses to limit the output. Having said that, none of the files generated so far in this tutorial are at risk of overwhelming the shell's history buffer when disassembled.

''more content needed here''

As mentioned just before the previous source code example, some quick and dirty methods were used for the sake of simplicity and readability and this refers to the way library function offsets were established. The approach used will quickly become detrimental as more offsets are added. There are a number of solutions to this problem but only one will be presented here and it involves the removal of the leading underscore character from function names so that, for example, '''li r3,_LVOOpenLibrary''' becomes '''li r3,LVOOpenLibrary'''. Remove or comment out the first three '''.set''' directives that define the library function offsets and assemble with ''vasm'' as before but note that the resulting object file is no longer executable. To make this object executable, ''vlink'' is needed.

<pre>
vlink -o <desired executable name> <existing object name> -lamiga
</pre>

In the above shell command, ''-lamiga'' refers to the ''libamiga.a'' file that ''vlink'' knows to look for in ''vlibmos:'' This file contains information used to resolve many library function names to numerical values. Note that any executable generated from the above ''vlink'' command will contain a lot of symbol information that, while potentially useful, increases the size of the executable. This can be avoided with a few additions to the above command.

<pre>
vlink -s -P__abox__ -o <desired executable name> <existing object name> -lamiga
</pre>

-s strip all symbols from the output file 
-P<symbol> preserve this symbol 

For more information, please refer to the documentation for ''vlink'' and other programs installed with ''vbcc''.

An Introduction to MorphOS PPC Assembly

2011-01-06T23:00:16Z

AusPPC:

==Jump In The Deep End And Compile Something Right Now==

You could copy and paste but just entering the two lines below into a suitable text editor is probably quicker.

<pre>
.text
blr
</pre>

Save as ''shorty.s''

'''.text''' is an assembler directive - more about it later. '''blr''' is one of many branch instructions. This particular one means 'Branch to Link Register'. When a program terminates, this is the last instruction to be executed and it causes the sequence of instruction execution to pass back to the calling program or environment (shell, Ambient etc). Subroutines can also terminate with this instruction but, again, more about this later.

This is as good a time as any to ask if you've installed vbcc yet - if not, go and do it. [http://mail.pb-owl.de/~frank/vbcc/current/vbcc_bin_morphos.lha Download vbcc]

Once vbcc is installed, open a shell window and change directory to where shorty.s has been saved.

Enter:

<pre>
vasmppc_std -Felf -o ram:shorty.o shorty.s
</pre>

This tells vasm to generate an ELF formatted object file called ''shorty.o'' in ram: from the ''shorty.s'' source file.

==Hello? World's Shortest MorphOS Program - Or Is It?==

There are times when a linker is needed to further process an object file to generate an executable - this isn't one of those times.

Go ahead and enter this into the shell window:

<pre>
ram:shorty.o
</pre>

It will appear as if nothing happens - but at least it happens very quickly. However, something did happen. ''shorty.o'' was identified as an executable program and loaded into memory where the cpu instruction execution sequence passed to it. As mentioned above, the single '''blr''' instruction in this program caused the instruction execution sequence to pass directly back to where it was called from - in this case, the shell.

It may be of interest to know that all PPC instructions are four bytes long. In PPC nomenclature, this length is known as a '''word'''. But let's take a moment to have a look at the size of ''shorty.o''

Enter this into the shell window:

<pre>
list ram:shorty.o
</pre>

2664 bytes?! But this is typical for object files as they contain much additional information that is used in the process of debugging and linking. Linking, particularly with the '''-s''' 'strip all symbols' option, will generate an executable that is noticeably smaller.

Try entering this into the shell window:

<pre>
vlink -s -o ram:shorty ram:shorty.o

list ram:shorty
</pre>

The newly generated executable is 328 bytes - much smaller than its object file but what are those other 324 bytes doing there? They are the ELF 'container' that holds the single, four byte instruction of ''shorty''. ELF stands for Executable and Linkable Format and it is used by MorphOS, AmigaOS4 and AROS - not to forget, Linux, UNIX, BSD and even video game consoles. There is abundant information about this file format online but this topic will be discussed a little further when the use of the ''objdump'' program is introduced.

==The Old And The New==

Generally, in order to make a program that does something useful or to at least produce an observable result, it is necessary to use operating system library functions. Despite the markedly different cpu family that MorphOS runs on compared to the 68k family used by the classic AmigaOS, MorphOS is largely compatible with AmigaOS. This compatibility is reflected in a very similar API shared with AmigaOS and extends to using a MorphOS system structure as if it were the internal data and address registers of an actual 68k processor. This is called the EmulHandle structure and it is always available through the PPC GPR2 register. Also, as with 68k AmigaOS, the address of the Exec library base is always to be found at memory location 4. Many aspects of the AmigaOS API fit closely to the features available in the 68k cpu and the following code comparison should illustrate how it is echoed in the PPC MorphOS API.

A common task performed during the initialisation of many programs - opening the Dos library. It is a particularly simple example of library usage but most functions follow this form.

[[File:Old-and-new.png]]

'''@h''' '''@ha''' & '''@l''' attributes are needed to specify the high and low halfwords of 32 bit immediate values because the fixed 32 bit size of PPC instructions does not allow enough space for an instruction opcode and additional 32 bits of data. The difference between '''@h''' and '''@ha''' is due to the common use of the '''addi''' (add immediate) instruction, which only takes a signed immediate value, to provide the lower 16 bits of a 32 bit constant - such as an address. Sometimes these lower 16 bits will equate to a negative value and it is then that prior use of the '''@ha''' attribute will cause its immediate value to be adjusted to compensate. These details are only resolved before execution, when the program is loaded. The '''@h''' attribute just specifies the upper halfword of a 32 bit constant without regard for what follows. While I'm banging on about such intricacies, the meaning of ''zero'' in ''load word and zero'' of the '''lwz''' instruction is that on 64 bit PPC processors, this instruction will load a 32 bit value from memory into the lower word of a 64 bit GPR and then clear (or zero) its upper word. Something to consider when MorphOS is available on G5 class computers...

One could be forgiven for thinking that the PPC code snippet looks a little ungainly compared to the former. Whereas every PPC instruction is four bytes long, 68k instructions can be as little as two bytes but up to as many as ten. A single 68k instruction can load a value from a 32 bit memory address specified by one instruction operand and store it at another 32 bit memory address specified by the second instruction operand. The 68k can also perform other operations beyond simple loads and stores directly on memory. Or at least appear to... In truth, computer memory only sends and receives data - no other data processing (like adding, subtracting & etc) occurs in memory. While the 68k instruction '''add.l #$12345678,(a0)''' appears to add the immediate value of it's first operand to whatever may already be stored at the address pointed to by a0, the contents of that address are actually loaded from memory into a private work register, the addition is performed and then the result is stored back to the same memory location. So this instruction actually performs two memory accesses where it might appear that there was only one. Contrast this with PPC assembly programming where memory loads and stores are all done explicitly. Before data can be operated upon it must be loaded from memory into a GPR (General Purpose Register), zero (in the case of a simple memory copy) or more operations can then be performed and then the data may be stored back to memory.

Unless you are brand-spanking-new to the topic of PPC assembly, you will already know that the PPC has 32 GPRs - r0 through r31. But did you know that the desired use of these registers is set out in something called the System V.4 ABI which MorphOS adheres to?

<pre>
r0 - volatile
r1 - stack pointer
r2 - for system use (with MorphOS, r2 points to the EmulHandle structure)

r3 - initialised with a pointer to a Dos command buffer
r4 - initialised with the length of the Dos command buffer
r5 - initialised with a pointer to an ELF structure

r3 ... r10 volatile & can be used to pass function arguments. If more
arguments are required, the stack is used.

r11 & r12 - volatile

r13 - small data area pointer. If this register is needed by a function or
subroutine, it must be saved first and then restored before
returning to where it was called from.

r14 ... r31 - No predefined purpose. If these registers are needed by a
function or subroutine, they must be saved first and then restored
before returning to where it was called from.
</pre>

The above use of the word 'volatile' means that functions are not expected to preserve the contents of these registers. r1 & r2 are the only registers that must be restored to their initial values by a terminating program, however, while most programs will modify r1 and later restore it, it is best to have not modified r2 in the first place.

This System V.4 ABI also sets out a particular way for programs and subroutines to organise their stack frames. When a program is loaded into memory and the instruction execution sequence passes to it, the stack pointer is still pointing to the calling program's stack frame and there is also an important address stored in the Link Register at this time. Unless this program is very simple (like ''shorty'') it must save the Link Register address and, most likely, create it's own stack frame. Somewhat conveniently, there is a special position in the caller's stack frame that a callee program can save the contents of the Link Register to. This is a fairly common example of a program or subroutine's very first instructions.

[[File:Awkward-program-initialisation.png]]

'Uh?' indeed... Let's try to visualise some memory being used as stack space.

[[File:Stack-diagram16.png]]

Note that '''stwu r1,-8(r1)''' creates a two-word stack frame which is the smallest stack that a program or subroutine can have if it, in turn, calls another program, subroutine or library function. More often, a larger stack frame is created although, '''stwu r1,-4(r1)''' could be used by a program or subroutine to create a one-word stack frame but this would be redundant and such a program must not call any other program, subroutine or library function. Such a program would not need to store the value in the Link Register (LR) to prevent it from being overwritten by subsequent calls and can terminate and return to it's caller with a simple '''blr''' instruction - just like ''shorty'' does.

A further note about larger stack frames and appropriate stack sizes: For reasons relating to PPC architecture, it is a good idea to choose stack frame sizes that are multiples of 16 bytes.

This is a less common example of a program's first instructions but it may better illustrate how to use stack frames.

[[File:Program-initialisation.png]]

Let's jump ahead and look at the last few instructions involved in program termination that would 'undo' the above instructions.

[[File:Program-termination.png]]

==A Little Less Talk And A Little More Action Please==

It's time to compile another program - this one will actually do something.

But wait...

Not another 'Hello World' program... I'm afraid so. This time, copy and paste is probably quicker. Alternatively, download this fully commented [http://aminet.net/dev/src/MorphOS-PPC-HelloWorld.lha source archive].

Note that this example does not use the MorphOS SDK. Instead, some 'quick and dirty' methods are used for the sake of simplicity and readability.

<pre>
# Various library function offsets
.set _LVOOpenLibrary,-552
.set _LVOCloseLibrary,-414
.set _LVOVPrintf,-954

.set _AbsExecBase,4

# EmulHandle structure (always pointed to by r2)
.set reg_d0,0
.set reg_d1,4
.set reg_d2,8
.set reg_d3,12
.set reg_d4,16
.set reg_d5,20
.set reg_d6,24
.set reg_d7,28
.set reg_a0,32
.set reg_a1,36
.set reg_a2,40
.set reg_a3,44
.set reg_a4,48
.set reg_a5,52
.set reg_a6,56
.set reg_a7,60
.set EmulCallDirectOS,100

# Stack frame offsets
.set stack_pos0_caller_stack,0
.set stack_pos1_callerLR,4
.set stack_pos2_ExecBase,8
.set stack_pos3_DosBase,12
.set new_4_word_stack,16

.text

mflr r0
stw r0,stack_pos1_callerLR(r1)
stwu r1,-new_4_word_stack(r1)

lis r3,dosName@ha
addi r3,r3,dosName@l
stw r3,reg_a1(r2)
li r3,0
stw r3,reg_d0(r2)
li r3,_AbsExecBase
lwz r3,0(r3)
stw r3,stack_pos2_ExecBase(r1)
stw r3,reg_a6(r2)
li r3,_LVOOpenLibrary
lwz r0,EmulCallDirectOS(r2)
mtctr r0
bctrl

cmpwi r3,0
beq exit

stw r3,stack_pos3_DosBase(r1)

lis r4,string1@ha
addi r4,r4,string1@l
stw r4,reg_d1(r2)
li r4,0
stw r4,reg_d2(r2)
stw r3,reg_a6(r2)
li r3,_LVOVPrintf
lwz r0,EmulCallDirectOS(r2)
mtctr r0
bctrl

lwz r3,stack_pos3_DosBase(r1)
stw r3,reg_a1(r2)
lwz r3,stack_pos2_ExecBase(r1)
stw r3,reg_a6(r2)
li r3,_LVOCloseLibrary
lwz r0,EmulCallDirectOS(r2)
mtctr r0
bctrl

li r3,0

exit: addi r1,r1,new_4_word_stack
lwz r0,stack_pos1_callerLR(r1)
mtlr r0
blr

.rodata
#__abox__ is a special MorphOS symbol that will differentiate
__abox__: #this program from other PPC executables that can run on MorphOS...
#When linking, care should be taken to avoid stripping this symbol.
dosName:
.string "dos.library"

string1:
.string "Hello World\n"
</pre>

Save this source file as ''HelloWorld.s'' and open a shell window. Change directory to where ''HelloWorld.s'' was just saved and enter:

<pre>
vasmppc_std -Felf -o ram:hw.o HelloWorld.s
</pre>

Once again, because of the simplicity of this program, linking isn't necessary so just enter the following in the shell window:

<pre>
ram:hw.o
</pre>

Are you impressed? Feel free to modify, experiment with and improve this source code. A not-too-difficult challenge might be to change this program so that it prints the arguments given to it in the shell window - a number of small but significant changes would be needed to do this. ''Hint: Have another look at the System V.4 register usage above.''

The commented version of ''HelloWorld.s'' in the downloadable source archive gives a brief description of why the '''mtctr''' (move to Count Register) & '''bctrl''' (branch to Count Register and link) instruction pair are used in preference to '''mtlr''' (move to Link Register) & '''blrl''' (branch to Link Register and link) - being that the latter pair can degrade performance optimisations of some PPC cpus. However, the primary use of the Count Register is as a 32 bit loop counter that can be automatically decremented by certain branch instructions.

When choosing which registers to use in your own programs, be aware that use of '''r0''' in some instruction operands will not always work as you might expect. In these instructions, the actual content of '''r0''' is ignored and the result is based on the constant value zero instead. For example, imagine that '''r0''' contains the value 100 when this instruction is executed: '''addi r0,r0,50''' It looks like the result should be '''r0 = r0 + 50 = 150''' The result will actually be '''r0 = 0 + 50 = 50''' This may seem odd but, as long as the programmer is aware of it, this behaviour can be useful. A good PPC instruction reference manual will explain this, and many other things, in much greater detail. There are many of these reference documents available online - this is one of them: [http://www.freescale.com/files/product/doc/MPCFPE32B.pdf MPCFPE32B.pdf]

==MorphOS SDK, Objdump, ELFs & Sections==

In addition to installing vbcc, it is also recommended to install the [http://www.morphos-team.net/files/sdk-20100617.lha MorphOS SDK] and the [http://mail.pb-owl.de/~frank/vbcc/current/vbcc_target_ppc-morphos.lha vbcc MorphOS compiler target].

The installer script of the latter seems to expect that there is a pre-existing assign for include: and, if your system already assigns include: to somewhere, please skip over this next part.

What follows is my S:user-startup after the installation of vbcc, it's MorphOS compiler target and an additional assign that I made preceded by this comment -

''; vbcc MorphOS target needs include: to be assigned to somewhere''

<pre>
;
; MorphOS user-startup
;
; This script is executed on system boot by
; startup-sequence. You can make personal
; changes in here.
;
; $VER: user-startup 1.1
;

; Enable the following to mount the inet-handler. Note that TCP: allows
; easy access to internet, and allows scripts to listen for incoming
; connections. Some malware could abuse this.
;Mount TCP:
;BEGIN vbcc
assign >NIL: vbcc: SYS:vbcc
assign >NIL: C: vbcc:bin ADD
setenv VBCC vbcc:
;END vbcc

; vbcc MorphOS target needs include: to be assigned to somewhere
assign include: SDK:GG/os-include

;BEGIN vbcc-ppc-morphos
assign >NIL: vincludemos: vbcc:targets/ppc-morphos/include
assign >NIL: vincludemos: include: add
assign >NIL: vlibmos: vbcc:targets/ppc-morphos/lib
;END vbcc-ppc-morphos
</pre>

At this point it would be useful to have a number of freshly generated object files and executables to look at with objdump although any ELF can be used for this purpose. Note that while MorphOS 2.x system files are compiled as ELFs, they are also signed to prevent their use on MorphOS 1.x where they may not work. This signing also has the effect of causing objdump not to recognise them as ELFs.

Objdump can be used to reveal a lot of interesting information about an ELF including listing any symbols and sections that are present as well as disassembling. Be aware that, when disassembled, seemingly small programs can produce more output than the shell window's history buffer can hold so either redirect the output to a file or specify start and stop addresses to limit the output. Having said that, none of the files generated so far in this tutorial are at risk of overwhelming the shell's history buffer when disassembled.

''more content needed here''

As mentioned just before the previous source code example, some quick and dirty methods were used for the sake of simplicity and readability and this refers to the way library function offsets were established. The approach used will quickly become detrimental as more offsets are added. There are a number of solutions to this problem but only one will be presented here and it involves the removal of the leading underscore character from function names so that, for example, '''li r3,_LVOOpenLibrary''' becomes '''li r3,LVOOpenLibrary'''. Remove or comment out the first three '''.set''' directives that define the library function offsets and assemble with vasm as before but note that the resulting object file is no longer executable. To make this object executable, vlink is needed.

<pre>
vlink -o <desired executable name> <existing object name> -lamiga
</pre>

In the above shell command, -lamiga refers to the ''libamiga.a'' file that vlink knows to look for in ''vlibmos:'' This file contains information used to resolve many library function names to numerical values. Note that any executable generated from the above vlink command will contain a lot of symbol information that, while potentially useful, increases the size of the executable. This can be avoided with a few additions to the above command.

<pre>
vlink -s -P__abox__ <desired executable name> <existing object name> -lamiga
</pre>

-s strip all symbols from the output file 
-P<symbol> preserve this symbol 

For more information, please refer to the documentation for vlink and other programs installed with vbcc.

An Introduction to MorphOS PPC Assembly

2011-01-06T22:53:37Z

AusPPC:

==Jump In The Deep End And Compile Something Right Now==

You could copy and paste but just entering the two lines below into a suitable text editor is probably quicker.

<pre>
.text
blr
</pre>

Save as ''shorty.s''

'''.text''' is an assembler directive - more about it later. '''blr''' is one of many branch instructions. This particular one means 'Branch to Link Register'. When a program terminates, this is the last instruction to be executed and it causes the sequence of instruction execution to pass back to the calling program or environment (shell, Ambient etc). Subroutines can also terminate with this instruction but, again, more about this later.

This is as good a time as any to ask if you've installed vbcc yet - if not, go and do it. [http://mail.pb-owl.de/~frank/vbcc/current/vbcc_bin_morphos.lha Download vbcc]

Once vbcc is installed, open a shell window and change directory to where shorty.s has been saved.

Enter:

<pre>
vasmppc_std -Felf -o ram:shorty.o shorty.s
</pre>

This tells vasm to generate an ELF formatted object file called ''shorty.o'' in ram: from the ''shorty.s'' source file.

==Hello? World's Shortest MorphOS Program - Or Is It?==

There are times when a linker is needed to further process an object file to generate an executable - this isn't one of those times.

Go ahead and enter this into the shell window:

<pre>
ram:shorty.o
</pre>

It will appear as if nothing happens - but at least it happens very quickly. However, something did happen. ''shorty.o'' was identified as an executable program and loaded into memory where the cpu instruction execution sequence passed to it. As mentioned above, the single '''blr''' instruction in this program caused the instruction execution sequence to pass directly back to where it was called from - in this case, the shell.

It may be of interest to know that all PPC instructions are four bytes long. In PPC nomenclature, this length is known as a '''word'''. But let's take a moment to have a look at the size of ''shorty.o''

Enter this into the shell window:

<pre>
list ram:shorty.o
</pre>

2664 bytes?! But this is typical for object files as they contain much additional information that is used in the process of debugging and linking. Linking, particularly with the '''-s''' 'strip all symbols' option, will generate an executable that is noticeably smaller.

Try entering this into the shell window:

<pre>
vlink -s -o ram:shorty ram:shorty.o

list ram:shorty
</pre>

The newly generated executable is 328 bytes - much smaller than its object file but what are those other 324 bytes doing there? They are the ELF 'container' that holds the single, four byte instruction of ''shorty''. ELF stands for Executable and Linkable Format and it is used by MorphOS, AmigaOS4 and AROS - not to forget, Linux, UNIX, BSD and even video game consoles. There is abundant information about this file format online but this topic will be discussed a little further when the use of the ''objdump'' program is introduced.

==The Old And The New==

Generally, in order to make a program that does something useful or to at least produce an observable result, it is necessary to use operating system library functions. Despite the markedly different cpu family that MorphOS runs on compared to the 68k family used by the classic AmigaOS, MorphOS is largely compatible with AmigaOS. This compatibility is reflected in a very similar API shared with AmigaOS and extends to using a MorphOS system structure as if it were the internal data and address registers of an actual 68k processor. This is called the EmulHandle structure and it is always available through the PPC GPR2 register. Also, as with 68k AmigaOS, the address of the Exec library base is always to be found at memory location 4. Many aspects of the AmigaOS API fit closely to the features available in the 68k cpu and the following code comparison should illustrate how it is echoed in the PPC MorphOS API.

A common task performed during the initialisation of many programs - opening the Dos library. It is a particularly simple example of library usage but most functions follow this form.

[[File:Old-and-new.png]]

'''@h''' '''@ha''' & '''@l''' attributes are needed to specify the high and low halfwords of 32 bit immediate values because the fixed 32 bit size of PPC instructions does not allow enough space for an instruction opcode and additional 32 bits of data. The difference between '''@h''' and '''@ha''' is due to the common use of the '''addi''' (add immediate) instruction, which only takes a signed immediate value, to provide the lower 16 bits of a 32 bit constant - such as an address. Sometimes these lower 16 bits will equate to a negative value and it is then that prior use of the '''@ha''' attribute will cause its immediate value to be adjusted to compensate. These details are only resolved before execution, when the program is loaded. The '''@h''' attribute just specifies the upper halfword of a 32 bit constant without regard for what follows. While I'm banging on about such intricacies, the meaning of ''zero'' in ''load word and zero'' of the '''lwz''' instruction is that on 64 bit PPC processors, this instruction will load a 32 bit value from memory into the lower word of a 64 bit GPR and then clear (or zero) its upper word. Something to consider when MorphOS is available on G5 class computers...

One could be forgiven for thinking that the PPC code snippet looks a little ungainly compared to the former. Whereas every PPC instruction is four bytes long, 68k instructions can be as little as two bytes but up to as many as ten. A single 68k instruction can load a value from a 32 bit memory address specified by one instruction operand and store it at another 32 bit memory address specified by the second instruction operand. The 68k can also perform other operations beyond simple loads and stores directly on memory. Or at least appear to... In truth, computer memory only sends and receives data - no other data processing (like adding, subtracting & etc) occurs in memory. While the 68k instruction '''add.l #$12345678,(a0)''' appears to add the immediate value of it's first operand to whatever may already be stored at the address pointed to by a0, the contents of that address are actually loaded from memory into a private work register, the addition is performed and then the result is stored back to the same memory location. So this instruction actually performs two memory accesses where it might appear that there was only one. Contrast this with PPC assembly programming where memory loads and stores are all done explicitly. Before data can be operated upon it must be loaded from memory into a GPR (General Purpose Register), zero (in the case of a simple memory copy) or more operations can then be performed and then the data may be stored back to memory.

Unless you are brand-spanking-new to the topic of PPC assembly, you will already know that the PPC has 32 GPRs - r0 through r31. But did you know that the desired use of these registers is set out in something called the System V.4 ABI which MorphOS adheres to?

<pre>
r0 - volatile
r1 - stack pointer
r2 - for system use (with MorphOS, r2 points to the EmulHandle structure)

r3 - initialised with a pointer to a Dos command buffer
r4 - initialised with the length of the Dos command buffer
r5 - initialised with a pointer to an ELF structure

r3 ... r10 volatile & can be used to pass function arguments. If more
arguments are required, the stack is used.

r11 & r12 - volatile

r13 - small data area pointer. If this register is needed by a function or
subroutine, it must be saved first and then restored before
returning to where it was called from.

r14 ... r31 - No predefined purpose. If these registers are needed by a
function or subroutine, they must be saved first and then restored
before returning to where it was called from.
</pre>

The above use of the word 'volatile' means that functions are not expected to preserve the contents of these registers. r1 & r2 are the only registers that must be restored to their initial values by a terminating program, however, while most programs will modify r1 and later restore it, it is best to have not modified r2 in the first place.

This System V.4 ABI also sets out a particular way for programs and subroutines to organise their stack frames. When a program is loaded into memory and the instruction execution sequence passes to it, the stack pointer is still pointing to the calling program's stack frame and there is also an important address stored in the Link Register at this time. Unless this program is very simple (like ''shorty'') it must save the Link Register address and, most likely, create it's own stack frame. Somewhat conveniently, there is a special position in the caller's stack frame that a callee program can save the contents of the Link Register to. This is a fairly common example of a program or subroutine's very first instructions.

[[File:Awkward-program-initialisation.png]]

'Uh?' indeed... Let's try to visualise some memory being used as stack space.

[[File:Stack-diagram16.png]]

Note that '''stwu r1,-8(r1)''' creates a two-word stack frame which is the smallest stack that a program or subroutine can have if it, in turn, calls another program, subroutine or library function. More often, a larger stack frame is created although, '''stwu r1,-4(r1)''' could be used by a program or subroutine to create a one-word stack frame but this would be redundant and such a program must not call any other program, subroutine or library function. Such a program would not need to store the value in the Link Register (LR) to prevent it from being overwritten by subsequent calls and can terminate and return to it's caller with a simple '''blr''' instruction - just like ''shorty'' does.

A further note about larger stack frames and appropriate stack sizes: For reasons relating to PPC architecture, it is a good idea to choose stack frame sizes that are multiples of 16 bytes.

This is a less common example of a program's first instructions but it may better illustrate how to use stack frames.

[[File:Program-initialisation.png]]

Let's jump ahead and look at the last few instructions involved in program termination that would 'undo' the above instructions.

[[File:Program-termination.png]]

==A Little Less Talk And A Little More Action Please==

It's time to compile another program - this one will actually do something.

But wait...

Not another 'Hello World' program... I'm afraid so. This time, copy and paste is probably quicker. Alternatively, download this fully commented [http://aminet.net/dev/src/MorphOS-PPC-HelloWorld.lha source archive].

Note that this example does not use the MorphOS SDK. Instead, some 'quick and dirty' methods are used for the sake of simplicity and readability.

<pre>
# Various library function offsets
.set _LVOOpenLibrary,-552
.set _LVOCloseLibrary,-414
.set _LVOVPrintf,-954

.set _AbsExecBase,4

# EmulHandle structure (always pointed to by r2)
.set reg_d0,0
.set reg_d1,4
.set reg_d2,8
.set reg_d3,12
.set reg_d4,16
.set reg_d5,20
.set reg_d6,24
.set reg_d7,28
.set reg_a0,32
.set reg_a1,36
.set reg_a2,40
.set reg_a3,44
.set reg_a4,48
.set reg_a5,52
.set reg_a6,56
.set reg_a7,60
.set EmulCallDirectOS,100

# Stack frame offsets
.set stack_pos0_caller_stack,0
.set stack_pos1_callerLR,4
.set stack_pos2_ExecBase,8
.set stack_pos3_DosBase,12
.set new_4_word_stack,16

.text

mflr r0
stw r0,stack_pos1_callerLR(r1)
stwu r1,-new_4_word_stack(r1)

lis r3,dosName@ha
addi r3,r3,dosName@l
stw r3,reg_a1(r2)
li r3,0
stw r3,reg_d0(r2)
li r3,_AbsExecBase
lwz r3,0(r3)
stw r3,stack_pos2_ExecBase(r1)
stw r3,reg_a6(r2)
li r3,_LVOOpenLibrary
lwz r0,EmulCallDirectOS(r2)
mtctr r0
bctrl

cmpwi r3,0
beq exit

stw r3,stack_pos3_DosBase(r1)

lis r4,string1@ha
addi r4,r4,string1@l
stw r4,reg_d1(r2)
li r4,0
stw r4,reg_d2(r2)
stw r3,reg_a6(r2)
li r3,_LVOVPrintf
lwz r0,EmulCallDirectOS(r2)
mtctr r0
bctrl

lwz r3,stack_pos3_DosBase(r1)
stw r3,reg_a1(r2)
lwz r3,stack_pos2_ExecBase(r1)
stw r3,reg_a6(r2)
li r3,_LVOCloseLibrary
lwz r0,EmulCallDirectOS(r2)
mtctr r0
bctrl

li r3,0

exit: addi r1,r1,new_4_word_stack
lwz r0,stack_pos1_callerLR(r1)
mtlr r0
blr

.rodata
#__abox__ is a special MorphOS symbol that will differentiate
__abox__: #this program from other PPC executables that can run on MorphOS...
#When linking, care should be taken to avoid stripping this symbol.
dosName:
.string "dos.library"

string1:
.string "Hello World\n"
</pre>

Save this source file as HelloWorld.s and open a shell window. Change directory to where HelloWorld.s was just saved and enter:

<pre>
vasmppc_std -Felf -o ram:hw.o HelloWorld.s
</pre>

Once again, because of the simplicity of this program, linking isn't necessary so just enter the following in the shell window:

<pre>
ram:hw.o
</pre>

Are you impressed? Feel free to modify, experiment with and improve this source code. A not-too-difficult challenge might be to change this program so that it prints the arguments given to it in the shell window - a number of small but significant changes would be needed to do this. ''Hint: Have another look at the System V.4 register usage above.''

The commented version of HelloWorld.s in the downloadable source archive gives a brief description of why the '''mtctr''' (move to Count Register) & '''bctrl''' (branch to Count Register and link) instruction pair are used in preference to '''mtlr''' (move to Link Register) & '''blrl''' (branch to Link Register and link) - being that the latter pair can degrade performance optimisations of some PPC cpus. However, the primary use of the Count Register is as a 32 bit loop counter that can be automatically decremented by certain branch instructions.

When choosing which registers to use in your own programs, be aware that use of r0 in some instruction operands will not always work as you might expect. In these instructions, the actual content of r0 is ignored and the result is based on the constant value zero instead. For example, imagine that r0 contains the value 100 when this instruction is executed: '''addi r0,r0,50''' It looks like the result should be r0 = r0 + 50 = 150 The result will actually be r0 = 0 + 50 = 50 This may seem odd but, as long as the programmer is aware of it, this behaviour can be useful. A good PPC instruction reference manual will explain this, and many other things, in much greater detail. There are many of these reference documents available online - this is one of them: [http://www.freescale.com/files/product/doc/MPCFPE32B.pdf MPCFPE32B.pdf]

==MorphOS SDK, Objdump, ELFs & Sections==

In addition to installing vbcc, it is also recommended to install the [http://www.morphos-team.net/files/sdk-20100617.lha MorphOS SDK] and the [http://mail.pb-owl.de/~frank/vbcc/current/vbcc_target_ppc-morphos.lha vbcc MorphOS compiler target].

The installer script of the latter seems to expect that there is a pre-existing assign for include: and, if your system already assigns include: to somewhere, please skip over this next part.

What follows is my S:user-startup after the installation of vbcc, it's MorphOS compiler target and an additional assign that I made preceded by this comment -

''; vbcc MorphOS target needs include: to be assigned to somewhere''

<pre>
;
; MorphOS user-startup
;
; This script is executed on system boot by
; startup-sequence. You can make personal
; changes in here.
;
; $VER: user-startup 1.1
;

; Enable the following to mount the inet-handler. Note that TCP: allows
; easy access to internet, and allows scripts to listen for incoming
; connections. Some malware could abuse this.
;Mount TCP:
;BEGIN vbcc
assign >NIL: vbcc: SYS:vbcc
assign >NIL: C: vbcc:bin ADD
setenv VBCC vbcc:
;END vbcc

; vbcc MorphOS target needs include: to be assigned to somewhere
assign include: SDK:GG/os-include

;BEGIN vbcc-ppc-morphos
assign >NIL: vincludemos: vbcc:targets/ppc-morphos/include
assign >NIL: vincludemos: include: add
assign >NIL: vlibmos: vbcc:targets/ppc-morphos/lib
;END vbcc-ppc-morphos
</pre>

At this point it would be useful to have a number of freshly generated object files and executables to look at with objdump although any ELF can be used for this purpose. Note that while MorphOS 2.x system files are compiled as ELFs, they are also signed to prevent their use on MorphOS 1.x where they may not work. This signing also has the effect of causing objdump not to recognise them as ELFs.

Objdump can be used to reveal a lot of interesting information about an ELF including listing any symbols and sections that are present as well as disassembling. Be aware that, when disassembled, seemingly small programs can produce more output than the shell window's history buffer can hold so either redirect the output to a file or specify start and stop addresses to limit the output. Having said that, none of the files generated so far in this tutorial are at risk of overwhelming the shell's history buffer when disassembled.

''more content needed here''

As mentioned just before the previous source code example, some quick and dirty methods were used for the sake of simplicity and readability and this refers to the way library function offsets were established. The approach used will quickly become detrimental as more offsets are added. There are a number of solutions to this problem but only one will be presented here and it involves the removal of the leading underscore character from function names so that, for example, '''li r3,_LVOOpenLibrary''' becomes '''li r3,LVOOpenLibrary'''. Remove or comment out the first three '''.set''' directives that define the library function offsets and assemble with vasm as before but note that the resulting object file is no longer executable. To make this object executable, vlink is needed.

<pre>
vlink -o <desired executable name> <existing object name> -lamiga
</pre>

In the above shell command, -lamiga refers to the ''libamiga.a'' file that vlink knows to look for in ''vlibmos:'' This file contains information used to resolve many library function names to numerical values. Note that any executable generated from the above vlink command will contain a lot of symbol information that, while potentially useful, increases the size of the executable. This can be avoided with a few additions to the above command.

<pre>
vlink -s -P__abox__ <desired executable name> <existing object name> -lamiga
</pre>

-s strip all symbols from the output file 
-P<symbol> preserve this symbol 

For more information, please refer to the documentation for vlink and other programs installed with vbcc.

An Introduction to MorphOS PPC Assembly

2011-01-06T22:50:35Z

AusPPC: Small addition to @ha @l explanation

==Jump In The Deep End And Compile Something Right Now==

You could copy and paste but just entering the two lines below into a suitable text editor is probably quicker.

<pre>
.text
blr
</pre>

Save as ''shorty.s''

'''.text''' is an assembler directive - more about it later. '''blr''' is one of many branch instructions. This particular one means 'Branch to Link Register'. When a program terminates, this is the last instruction to be executed and it causes the sequence of instruction execution to pass back to the calling program or environment (shell, Ambient etc). Subroutines can also terminate with this instruction but, again, more about this later.

This is as good a time as any to ask if you've installed vbcc yet - if not, go and do it. [http://mail.pb-owl.de/~frank/vbcc/current/vbcc_bin_morphos.lha Download vbcc]

Once vbcc is installed, open a shell window and change directory to where shorty.s has been saved.

Enter:

<pre>
vasmppc_std -Felf -o ram:shorty.o shorty.s
</pre>

This tells vasm to generate an ELF formatted object file called ''shorty.o'' in ram: from the ''shorty.s'' source file.

==Hello? World's Shortest MorphOS Program - Or Is It?==

There are times when a linker is needed to further process an object file to generate an executable - this isn't one of those times.

Go ahead and enter this into the shell window:

<pre>
ram:shorty.o
</pre>

It will appear as if nothing happens - but at least it happens very quickly. However, something did happen. ''shorty.o'' was identified as an executable program and loaded into memory where the cpu instruction execution sequence passed to it. As mentioned above, the single '''blr''' instruction in this program caused the instruction execution sequence to pass directly back to where it was called from - in this case, the shell.

It may be of interest to know that all PPC instructions are four bytes long. In PPC nomenclature, this length is known as a '''word'''. But let's take a moment to have a look at the size of ''shorty.o''

Enter this into the shell window:

<pre>
list ram:shorty.o
</pre>

2664 bytes?! But this is typical for object files as they contain much additional information that is used in the process of debugging and linking. Linking, particularly with the '''-s''' 'strip all symbols' option, will generate an executable that is noticeably smaller.

Try entering this into the shell window:

<pre>
vlink -s -o ram:shorty ram:shorty.o

list ram:shorty
</pre>

The newly generated executable is 328 bytes - much smaller than its object file but what are those other 324 bytes doing there? They are the ELF 'container' that holds the single, four byte instruction of ''shorty''. ELF stands for Executable and Linkable Format and it is used by MorphOS, AmigaOS4 and AROS - not to forget, Linux, UNIX, BSD and even video game consoles. There is abundant information about this file format online but this topic will be discussed a little further when the use of the ''objdump'' program is introduced.

==The Old And The New==

Generally, in order to make a program that does something useful or to at least produce an observable result, it is necessary to use operating system library functions. Despite the markedly different cpu family that MorphOS runs on compared to the 68k family used by the classic AmigaOS, MorphOS is largely compatible with AmigaOS. This compatibility is reflected in a very similar API shared with AmigaOS and extends to using a MorphOS system structure as if it were the internal data and address registers of an actual 68k processor. This is called the EmulHandle structure and it is always available through the PPC GPR2 register. Also, as with 68k AmigaOS, the address of the Exec library base is always to be found at memory location 4. Many aspects of the AmigaOS API fit closely to the features available in the 68k cpu and the following code comparison should illustrate how it is echoed in the PPC MorphOS API.

A common task performed during the initialisation of many programs - opening the Dos library. It is a particularly simple example of library usage but most functions follow this form.

[[File:Old-and-new.png]]

'''@h''' '''@ha''' & '''@l''' attributes are needed to specify the high and low halfwords of 32 bit immediate values because the fixed 32 bit size of PPC instructions does not allow enough space for an instruction opcode and additional 32 bits of data. The difference between '''@h''' and '''@ha''' is due to the common use of the '''addi''' (add immediate) instruction, which only takes a signed immediate value, to provide the lower 16 bits of a 32 bit constant - such as an address. Sometimes these lower 16 bits will equate to a negative value and it is then that prior use of the ''@ha'' attribute will cause its immediate value to be adjusted to compensate. These details are only resolved before execution, when the program is loaded. The ''@h'' attribute just specifies the upper halfword of a 32 bit constant without regard for what follows. While I'm banging on about such intricacies, the meaning of ''zero'' in ''load word and zero'' of the '''lwz''' instruction is that on 64 bit PPC processors, this instruction will load a 32 bit value from memory into the lower word of a 64 bit GPR and then clear (or zero) its upper word. Something to consider when MorphOS is available on G5 class computers...

One could be forgiven for thinking that the PPC code snippet looks a little ungainly compared to the former. Whereas every PPC instruction is four bytes long, 68k instructions can be as little as two bytes but up to as many as ten. A single 68k instruction can load a value from a 32 bit memory address specified by one instruction operand and store it at another 32 bit memory address specified by the second instruction operand. The 68k can also perform other operations beyond simple loads and stores directly on memory. Or at least appear to... In truth, computer memory only sends and receives data - no other data processing (like adding, subtracting & etc) occurs in memory. While the 68k instruction '''add.l #$12345678,(a0)''' appears to add the immediate value of it's first operand to whatever may already be stored at the address pointed to by a0, the contents of that address are actually loaded from memory into a private work register, the addition is performed and then the result is stored back to the same memory location. So this instruction actually performs two memory accesses where it might appear that there was only one. Contrast this with PPC assembly programming where memory loads and stores are all done explicitly. Before data can be operated upon it must be loaded from memory into a GPR (General Purpose Register), zero (in the case of a simple memory copy) or more operations can then be performed and then the data may be stored back to memory.

Unless you are brand-spanking-new to the topic of PPC assembly, you will already know that the PPC has 32 GPRs - r0 through r31. But did you know that the desired use of these registers is set out in something called the System V.4 ABI which MorphOS adheres to?

<pre>
r0 - volatile
r1 - stack pointer
r2 - for system use (with MorphOS, r2 points to the EmulHandle structure)

r3 - initialised with a pointer to a Dos command buffer
r4 - initialised with the length of the Dos command buffer
r5 - initialised with a pointer to an ELF structure

r3 ... r10 volatile & can be used to pass function arguments. If more
arguments are required, the stack is used.

r11 & r12 - volatile

r13 - small data area pointer. If this register is needed by a function or
subroutine, it must be saved first and then restored before
returning to where it was called from.

r14 ... r31 - No predefined purpose. If these registers are needed by a
function or subroutine, they must be saved first and then restored
before returning to where it was called from.
</pre>

The above use of the word 'volatile' means that functions are not expected to preserve the contents of these registers. r1 & r2 are the only registers that must be restored to their initial values by a terminating program, however, while most programs will modify r1 and later restore it, it is best to have not modified r2 in the first place.

This System V.4 ABI also sets out a particular way for programs and subroutines to organise their stack frames. When a program is loaded into memory and the instruction execution sequence passes to it, the stack pointer is still pointing to the calling program's stack frame and there is also an important address stored in the Link Register at this time. Unless this program is very simple (like ''shorty'') it must save the Link Register address and, most likely, create it's own stack frame. Somewhat conveniently, there is a special position in the caller's stack frame that a callee program can save the contents of the Link Register to. This is a fairly common example of a program or subroutine's very first instructions.

[[File:Awkward-program-initialisation.png]]

'Uh?' indeed... Let's try to visualise some memory being used as stack space.

[[File:Stack-diagram16.png]]

Note that '''stwu r1,-8(r1)''' creates a two-word stack frame which is the smallest stack that a program or subroutine can have if it, in turn, calls another program, subroutine or library function. More often, a larger stack frame is created although, '''stwu r1,-4(r1)''' could be used by a program or subroutine to create a one-word stack frame but this would be redundant and such a program must not call any other program, subroutine or library function. Such a program would not need to store the value in the Link Register (LR) to prevent it from being overwritten by subsequent calls and can terminate and return to it's caller with a simple '''blr''' instruction - just like ''shorty'' does.

A further note about larger stack frames and appropriate stack sizes: For reasons relating to PPC architecture, it is a good idea to choose stack frame sizes that are multiples of 16 bytes.

This is a less common example of a program's first instructions but it may better illustrate how to use stack frames.

[[File:Program-initialisation.png]]

Let's jump ahead and look at the last few instructions involved in program termination that would 'undo' the above instructions.

[[File:Program-termination.png]]

==A Little Less Talk And A Little More Action Please==

It's time to compile another program - this one will actually do something.

But wait...

Not another 'Hello World' program... I'm afraid so. This time, copy and paste is probably quicker. Alternatively, download this fully commented [http://aminet.net/dev/src/MorphOS-PPC-HelloWorld.lha source archive].

Note that this example does not use the MorphOS SDK. Instead, some 'quick and dirty' methods are used for the sake of simplicity and readability.

<pre>
# Various library function offsets
.set _LVOOpenLibrary,-552
.set _LVOCloseLibrary,-414
.set _LVOVPrintf,-954

.set _AbsExecBase,4

# EmulHandle structure (always pointed to by r2)
.set reg_d0,0
.set reg_d1,4
.set reg_d2,8
.set reg_d3,12
.set reg_d4,16
.set reg_d5,20
.set reg_d6,24
.set reg_d7,28
.set reg_a0,32
.set reg_a1,36
.set reg_a2,40
.set reg_a3,44
.set reg_a4,48
.set reg_a5,52
.set reg_a6,56
.set reg_a7,60
.set EmulCallDirectOS,100

# Stack frame offsets
.set stack_pos0_caller_stack,0
.set stack_pos1_callerLR,4
.set stack_pos2_ExecBase,8
.set stack_pos3_DosBase,12
.set new_4_word_stack,16

.text

mflr r0
stw r0,stack_pos1_callerLR(r1)
stwu r1,-new_4_word_stack(r1)

lis r3,dosName@ha
addi r3,r3,dosName@l
stw r3,reg_a1(r2)
li r3,0
stw r3,reg_d0(r2)
li r3,_AbsExecBase
lwz r3,0(r3)
stw r3,stack_pos2_ExecBase(r1)
stw r3,reg_a6(r2)
li r3,_LVOOpenLibrary
lwz r0,EmulCallDirectOS(r2)
mtctr r0
bctrl

cmpwi r3,0
beq exit

stw r3,stack_pos3_DosBase(r1)

lis r4,string1@ha
addi r4,r4,string1@l
stw r4,reg_d1(r2)
li r4,0
stw r4,reg_d2(r2)
stw r3,reg_a6(r2)
li r3,_LVOVPrintf
lwz r0,EmulCallDirectOS(r2)
mtctr r0
bctrl

lwz r3,stack_pos3_DosBase(r1)
stw r3,reg_a1(r2)
lwz r3,stack_pos2_ExecBase(r1)
stw r3,reg_a6(r2)
li r3,_LVOCloseLibrary
lwz r0,EmulCallDirectOS(r2)
mtctr r0
bctrl

li r3,0

exit: addi r1,r1,new_4_word_stack
lwz r0,stack_pos1_callerLR(r1)
mtlr r0
blr

.rodata
#__abox__ is a special MorphOS symbol that will differentiate
__abox__: #this program from other PPC executables that can run on MorphOS...
#When linking, care should be taken to avoid stripping this symbol.
dosName:
.string "dos.library"

string1:
.string "Hello World\n"
</pre>

Save this source file as HelloWorld.s and open a shell window. Change directory to where HelloWorld.s was just saved and enter:

<pre>
vasmppc_std -Felf -o ram:hw.o HelloWorld.s
</pre>

Once again, because of the simplicity of this program, linking isn't necessary so just enter the following in the shell window:

<pre>
ram:hw.o
</pre>

Are you impressed? Feel free to modify, experiment with and improve this source code. A not-too-difficult challenge might be to change this program so that it prints the arguments given to it in the shell window - a number of small but significant changes would be needed to do this. ''Hint: Have another look at the System V.4 register usage above.''

The commented version of HelloWorld.s in the downloadable source archive gives a brief description of why the '''mtctr''' (move to Count Register) & '''bctrl''' (branch to Count Register and link) instruction pair are used in preference to '''mtlr''' (move to Link Register) & '''blrl''' (branch to Link Register and link) - being that the latter pair can degrade performance optimisations of some PPC cpus. However, the primary use of the Count Register is as a 32 bit loop counter that can be automatically decremented by certain branch instructions.

When choosing which registers to use in your own programs, be aware that use of r0 in some instruction operands will not always work as you might expect. In these instructions, the actual content of r0 is ignored and the result is based on the constant value zero instead. For example, imagine that r0 contains the value 100 when this instruction is executed: '''addi r0,r0,50''' It looks like the result should be r0 = r0 + 50 = 150 The result will actually be r0 = 0 + 50 = 50 This may seem odd but, as long as the programmer is aware of it, this behaviour can be useful. A good PPC instruction reference manual will explain this, and many other things, in much greater detail. There are many of these reference documents available online - this is one of them: [http://www.freescale.com/files/product/doc/MPCFPE32B.pdf MPCFPE32B.pdf]

==MorphOS SDK, Objdump, ELFs & Sections==

In addition to installing vbcc, it is also recommended to install the [http://www.morphos-team.net/files/sdk-20100617.lha MorphOS SDK] and the [http://mail.pb-owl.de/~frank/vbcc/current/vbcc_target_ppc-morphos.lha vbcc MorphOS compiler target].

The installer script of the latter seems to expect that there is a pre-existing assign for include: and, if your system already assigns include: to somewhere, please skip over this next part.

What follows is my S:user-startup after the installation of vbcc, it's MorphOS compiler target and an additional assign that I made preceded by this comment -

''; vbcc MorphOS target needs include: to be assigned to somewhere''

<pre>
;
; MorphOS user-startup
;
; This script is executed on system boot by
; startup-sequence. You can make personal
; changes in here.
;
; $VER: user-startup 1.1
;

; Enable the following to mount the inet-handler. Note that TCP: allows
; easy access to internet, and allows scripts to listen for incoming
; connections. Some malware could abuse this.
;Mount TCP:
;BEGIN vbcc
assign >NIL: vbcc: SYS:vbcc
assign >NIL: C: vbcc:bin ADD
setenv VBCC vbcc:
;END vbcc

; vbcc MorphOS target needs include: to be assigned to somewhere
assign include: SDK:GG/os-include

;BEGIN vbcc-ppc-morphos
assign >NIL: vincludemos: vbcc:targets/ppc-morphos/include
assign >NIL: vincludemos: include: add
assign >NIL: vlibmos: vbcc:targets/ppc-morphos/lib
;END vbcc-ppc-morphos
</pre>

At this point it would be useful to have a number of freshly generated object files and executables to look at with objdump although any ELF can be used for this purpose. Note that while MorphOS 2.x system files are compiled as ELFs, they are also signed to prevent their use on MorphOS 1.x where they may not work. This signing also has the effect of causing objdump not to recognise them as ELFs.

Objdump can be used to reveal a lot of interesting information about an ELF including listing any symbols and sections that are present as well as disassembling. Be aware that, when disassembled, seemingly small programs can produce more output than the shell window's history buffer can hold so either redirect the output to a file or specify start and stop addresses to limit the output. Having said that, none of the files generated so far in this tutorial are at risk of overwhelming the shell's history buffer when disassembled.

''more content needed here''

As mentioned just before the previous source code example, some quick and dirty methods were used for the sake of simplicity and readability and this refers to the way library function offsets were established. The approach used will quickly become detrimental as more offsets are added. There are a number of solutions to this problem but only one will be presented here and it involves the removal of the leading underscore character from function names so that, for example, '''li r3,_LVOOpenLibrary''' becomes '''li r3,LVOOpenLibrary'''. Remove or comment out the first three '''.set''' directives that define the library function offsets and assemble with vasm as before but note that the resulting object file is no longer executable. To make this object executable, vlink is needed.

<pre>
vlink -o <desired executable name> <existing object name> -lamiga
</pre>

In the above shell command, -lamiga refers to the ''libamiga.a'' file that vlink knows to look for in ''vlibmos:'' This file contains information used to resolve many library function names to numerical values. Note that any executable generated from the above vlink command will contain a lot of symbol information that, while potentially useful, increases the size of the executable. This can be avoided with a few additions to the above command.

<pre>
vlink -s -P__abox__ <desired executable name> <existing object name> -lamiga
</pre>

-s strip all symbols from the output file 
-P<symbol> preserve this symbol 

For more information, please refer to the documentation for vlink and other programs installed with vbcc.

An Introduction to MorphOS PPC Assembly

2011-01-06T22:01:57Z

AusPPC:

==Jump In The Deep End And Compile Something Right Now==

You could copy and paste but just entering the two lines below into a suitable text editor is probably quicker.

<pre>
.text
blr
</pre>

Save as ''shorty.s''

'''.text''' is an assembler directive - more about it later. '''blr''' is one of many branch instructions. This particular one means 'Branch to Link Register'. When a program terminates, this is the last instruction to be executed and it causes the sequence of instruction execution to pass back to the calling program or environment (shell, Ambient etc). Subroutines can also terminate with this instruction but, again, more about this later.

This is as good a time as any to ask if you've installed vbcc yet - if not, go and do it. [http://mail.pb-owl.de/~frank/vbcc/current/vbcc_bin_morphos.lha Download vbcc]

Once vbcc is installed, open a shell window and change directory to where shorty.s has been saved.

Enter:

<pre>
vasmppc_std -Felf -o ram:shorty.o shorty.s
</pre>

This tells vasm to generate an ELF formatted object file called ''shorty.o'' in ram: from the ''shorty.s'' source file.

==Hello? World's Shortest MorphOS Program - Or Is It?==

There are times when a linker is needed to further process an object file to generate an executable - this isn't one of those times.

Go ahead and enter this into the shell window:

<pre>
ram:shorty.o
</pre>

It will appear as if nothing happens - but at least it happens very quickly. However, something did happen. ''shorty.o'' was identified as an executable program and loaded into memory where the cpu instruction execution sequence passed to it. As mentioned above, the single '''blr''' instruction in this program caused the instruction execution sequence to pass directly back to where it was called from - in this case, the shell.

It may be of interest to know that all PPC instructions are four bytes long. In PPC nomenclature, this length is known as a '''word'''. But let's take a moment to have a look at the size of ''shorty.o''

Enter this into the shell window:

<pre>
list ram:shorty.o
</pre>

2664 bytes?! But this is typical for object files as they contain much additional information that is used in the process of debugging and linking. Linking, particularly with the '''-s''' 'strip all symbols' option, will generate an executable that is noticeably smaller.

Try entering this into the shell window:

<pre>
vlink -s -o ram:shorty ram:shorty.o

list ram:shorty
</pre>

The newly generated executable is 328 bytes - much smaller than its object file but what are those other 324 bytes doing there? They are the ELF 'container' that holds the single, four byte instruction of ''shorty''. ELF stands for Executable and Linkable Format and it is used by MorphOS, AmigaOS4 and AROS - not to forget, Linux, UNIX, BSD and even video game consoles. There is abundant information about this file format online but this topic will be discussed a little further when the use of the ''objdump'' program is introduced.

==The Old And The New==

Generally, in order to make a program that does something useful or to at least produce an observable result, it is necessary to use operating system library functions. Despite the markedly different cpu family that MorphOS runs on compared to the 68k family used by the classic AmigaOS, MorphOS is largely compatible with AmigaOS. This compatibility is reflected in a very similar API shared with AmigaOS and extends to using a MorphOS system structure as if it were the internal data and address registers of an actual 68k processor. This is called the EmulHandle structure and it is always available through the PPC GPR2 register. Also, as with 68k AmigaOS, the address of the Exec library base is always to be found at memory location 4. Many aspects of the AmigaOS API fit closely to the features available in the 68k cpu and the following code comparison should illustrate how it is echoed in the PPC MorphOS API.

A common task performed during the initialisation of many programs - opening the Dos library. It is a particularly simple example of library usage but most functions follow this form.

[[File:Old-and-new.png]]

@ha & @l are needed to specify the high and low halfwords of 32 bit immediate values because the fixed 32 bit size of PPC instructions does not allow enough space for an instruction opcode and additional 32 bits of data.

One could be forgiven for thinking that the PPC code snippet looks a little ungainly compared to the former. Whereas every PPC instruction is four bytes long, 68k instructions can be as little as two bytes but up to as many as ten. A single 68k instruction can load a value from a 32 bit memory address specified by one instruction operand and store it at another 32 bit memory address specified by the second instruction operand. The 68k can also perform other operations beyond simple loads and stores directly on memory. Or at least appear to... In truth, computer memory only sends and receives data - no other data processing (like adding, subtracting & etc) occurs in memory. While the 68k instruction '''add.l #$12345678,(a0)''' appears to add the immediate value of it's first operand to whatever may already be stored at the address pointed to by a0, the contents of that address are actually loaded from memory into a private work register, the addition is performed and then the result is stored back to the same memory location. So this instruction actually performs two memory accesses where it might appear that there was only one. Contrast this with PPC assembly programming where memory loads and stores are all done explicitly. Before data can be operated upon it must be loaded from memory into a GPR (General Purpose Register), zero (in the case of a simple memory copy) or more operations can then be performed and then the data may be stored back to memory.

Unless you are brand-spanking-new to the topic of PPC assembly, you will already know that the PPC has 32 GPRs - r0 through r31. But did you know that the desired use of these registers is set out in something called the System V.4 ABI which MorphOS adheres to?

<pre>
r0 - volatile
r1 - stack pointer
r2 - for system use (with MorphOS, r2 points to the EmulHandle structure)

r3 - initialised with a pointer to a Dos command buffer
r4 - initialised with the length of the Dos command buffer
r5 - initialised with a pointer to an ELF structure

r3 ... r10 volatile & can be used to pass function arguments. If more
arguments are required, the stack is used.

r11 & r12 - volatile

r13 - small data area pointer. If this register is needed by a function or
subroutine, it must be saved first and then restored before
returning to where it was called from.

r14 ... r31 - No predefined purpose. If these registers are needed by a
function or subroutine, they must be saved first and then restored
before returning to where it was called from.
</pre>

The above use of the word 'volatile' means that functions are not expected to preserve the contents of these registers. r1 & r2 are the only registers that must be restored to their initial values by a terminating program, however, while most programs will modify r1 and later restore it, it is best to have not modified r2 in the first place.

This System V.4 ABI also sets out a particular way for programs and subroutines to organise their stack frames. When a program is loaded into memory and the instruction execution sequence passes to it, the stack pointer is still pointing to the calling program's stack frame and there is also an important address stored in the Link Register at this time. Unless this program is very simple (like shorty) it must save the Link Register address and, most likely, create it's own stack frame. Somewhat conveniently, there is a special position in the caller's stack frame that a callee program can save the contents of the Link Register to. This is a fairly common example of a program or subroutine's very first instructions.

[[File:Awkward-program-initialisation.png]]

Uh indeed... Let's try to visualise some memory being used as stack space.

[[File:Stack-diagram16.png]]

Note that '''stwu r1,-8(r1)''' creates a two-word stack frame which is the smallest stack that a program or subroutine can have if it, in turn, calls another program, subroutine or library function. More often, a larger stack frame is created although, '''stwu r1,-4(r1)''' could be used by a program or subroutine to create a one-word stack frame but this would be redundant and such a program must not call any other program, subroutine or library function. Such a program would not need to store the value in the Link Register (LR) to prevent it from being overwritten by subsequent calls and can terminate and return to it's caller with a simple '''blr''' instruction - just like shorty does.

A further note about larger stack frames and appropriate stack sizes: For reasons relating to PPC architecture, it is a good idea to choose stack frame sizes that are multiples of 16 bytes.

This is a less common example of a program's first instructions but it may better illustrate how to use stack frames.

[[File:Program-initialisation.png]]

Let's jump ahead and look at the last few instructions involved in program termination that would 'undo' the above instructions.

[[File:Program-termination.png]]

==A Little Less Talk And A Little More Action Please==

It's time to compile another program - this one will actually do something.

But wait...

Not another 'Hello World' program... I'm afraid so. This time, copy and paste is probably quicker. Alternatively, download this fully commented [http://aminet.net/dev/src/MorphOS-PPC-HelloWorld.lha source archive].

Note that this example does not use the MorphOS SDK. Instead, some 'quick and dirty' methods are used for the sake of simplicity and readability.

<pre>
# Various library function offsets
.set _LVOOpenLibrary,-552
.set _LVOCloseLibrary,-414
.set _LVOVPrintf,-954

.set _AbsExecBase,4

# EmulHandle structure (always pointed to by r2)
.set reg_d0,0
.set reg_d1,4
.set reg_d2,8
.set reg_d3,12
.set reg_d4,16
.set reg_d5,20
.set reg_d6,24
.set reg_d7,28
.set reg_a0,32
.set reg_a1,36
.set reg_a2,40
.set reg_a3,44
.set reg_a4,48
.set reg_a5,52
.set reg_a6,56
.set reg_a7,60
.set EmulCallDirectOS,100

# Stack frame offsets
.set stack_pos0_caller_stack,0
.set stack_pos1_callerLR,4
.set stack_pos2_ExecBase,8
.set stack_pos3_DosBase,12
.set new_4_word_stack,16

.text

mflr r0
stw r0,stack_pos1_callerLR(r1)
stwu r1,-new_4_word_stack(r1)

lis r3,dosName@ha
addi r3,r3,dosName@l
stw r3,reg_a1(r2)
li r3,0
stw r3,reg_d0(r2)
li r3,_AbsExecBase
lwz r3,0(r3)
stw r3,stack_pos2_ExecBase(r1)
stw r3,reg_a6(r2)
li r3,_LVOOpenLibrary
lwz r0,EmulCallDirectOS(r2)
mtctr r0
bctrl

cmpwi r3,0
beq exit

stw r3,stack_pos3_DosBase(r1)

lis r4,string1@ha
addi r4,r4,string1@l
stw r4,reg_d1(r2)
li r4,0
stw r4,reg_d2(r2)
stw r3,reg_a6(r2)
li r3,_LVOVPrintf
lwz r0,EmulCallDirectOS(r2)
mtctr r0
bctrl

lwz r3,stack_pos3_DosBase(r1)
stw r3,reg_a1(r2)
lwz r3,stack_pos2_ExecBase(r1)
stw r3,reg_a6(r2)
li r3,_LVOCloseLibrary
lwz r0,EmulCallDirectOS(r2)
mtctr r0
bctrl

li r3,0

exit: addi r1,r1,new_4_word_stack
lwz r0,stack_pos1_callerLR(r1)
mtlr r0
blr

.rodata
#__abox__ is a special MorphOS symbol that will differentiate
__abox__: #this program from other PPC executables that can run on MorphOS...
#When linking, care should be taken to avoid stripping this symbol.
dosName:
.string "dos.library"

string1:
.string "Hello World\n"
</pre>

Save this source file as HelloWorld.s and open a shell window. Change directory to where HelloWorld.s was just saved and enter:

<pre>
vasmppc_std -Felf -o ram:hw.o HelloWorld.s
</pre>

Once again, because of the simplicity of this program, linking isn't necessary so just enter the following in the shell window:

<pre>
ram:hw.o
</pre>

Are you impressed? Feel free to modify, experiment with and improve this source code. A not-too-difficult challenge might be to change this program so that it prints the arguments given to it in the shell window - a number of small but significant changes would be needed to do this. ''Hint: Have another look at the System V.4 register usage above.''

The commented version of HelloWorld.s in the downloadable source archive gives a brief description of why the '''mtctr''' (move to Count Register) & '''bctrl''' (branch to Count Register and link) instruction pair are used in preference to '''mtlr''' (move to Link Register) & '''blrl''' (branch to Link Register and link) - being that the latter pair can degrade performance optimisations of some PPC cpus. However, the primary use of the Count Register is as a 32 bit loop counter that can be automatically decremented by certain branch instructions.

When choosing which registers to use in your own programs, be aware that use of r0 in some instruction operands will not always work as you might expect. In these instructions, the actual content of r0 is ignored and the result is based on the constant value zero instead. For example, imagine that r0 contains the value 100 when this instruction is executed: '''addi r0,r0,50''' It looks like the result should be r0 = r0 + 50 = 150 The result will actually be r0 = 0 + 50 = 50 This may seem odd but, as long as the programmer is aware of it, this behaviour can be useful. A good PPC instruction reference manual will explain this, and many other things, in much greater detail. There are many of these reference documents available online - this is one of them: [http://www.freescale.com/files/product/doc/MPCFPE32B.pdf MPCFPE32B.pdf]

==MorphOS SDK, Objdump, ELFs & Sections==

In addition to installing vbcc, it is also recommended to install the [http://www.morphos-team.net/files/sdk-20100617.lha MorphOS SDK] and the [http://mail.pb-owl.de/~frank/vbcc/current/vbcc_target_ppc-morphos.lha vbcc MorphOS compiler target].

The installer script of the latter seems to expect that there is a pre-existing assign for include: and, if your system already assigns include: to somewhere, please skip over this next part.

What follows is my S:user-startup after the installation of vbcc, it's MorphOS compiler target and an additional assign that I made preceded by this comment -

''; vbcc MorphOS target needs include: to be assigned to somewhere''

<pre>
;
; MorphOS user-startup
;
; This script is executed on system boot by
; startup-sequence. You can make personal
; changes in here.
;
; $VER: user-startup 1.1
;

; Enable the following to mount the inet-handler. Note that TCP: allows
; easy access to internet, and allows scripts to listen for incoming
; connections. Some malware could abuse this.
;Mount TCP:
;BEGIN vbcc
assign >NIL: vbcc: SYS:vbcc
assign >NIL: C: vbcc:bin ADD
setenv VBCC vbcc:
;END vbcc

; vbcc MorphOS target needs include: to be assigned to somewhere
assign include: SDK:GG/os-include

;BEGIN vbcc-ppc-morphos
assign >NIL: vincludemos: vbcc:targets/ppc-morphos/include
assign >NIL: vincludemos: include: add
assign >NIL: vlibmos: vbcc:targets/ppc-morphos/lib
;END vbcc-ppc-morphos
</pre>

At this point it would be useful to have a number of freshly generated object files and executables to look at with objdump although any ELF can be used for this purpose. Note that while MorphOS 2.x system files are compiled as ELFs, they are also signed to prevent their use on MorphOS 1.x where they may not work. This signing also has the effect of causing objdump not to recognise them as ELFs.

Objdump can be used to reveal a lot of interesting information about an ELF including listing any symbols and sections that are present as well as disassembling. Be aware that, when disassembled, seemingly small programs can produce more output than the shell window's history buffer can hold so either redirect the output to a file or specify start and stop addresses to limit the output. Having said that, none of the files generated so far in this tutorial are at risk of overwhelming the shell's history buffer when disassembled.

''more content needed here''

As mentioned just before the previous source code example, some quick and dirty methods were used for the sake of simplicity and readability and this refers to the way library function offsets were established. The approach used will quickly become detrimental as more offsets are added. There are a number of solutions to this problem but only one will be presented here and it involves the removal of the leading underscore character from function names so that, for example, '''li r3,_LVOOpenLibrary''' becomes '''li r3,LVOOpenLibrary'''. Remove or comment out the first three '''.set''' directives that define the library function offsets and assemble with vasm as before but note that the resulting object file is no longer executable. To make this object executable, vlink is needed.

<pre>
vlink -o <desired executable name> <existing object name> -lamiga
</pre>

In the above shell command, -lamiga refers to the ''libamiga.a'' file that vlink knows to look for in ''vlibmos:'' This file contains information used to resolve many library function names to numerical values. Note that any executable generated from the above vlink command will contain a lot of symbol information that, while potentially useful, increases the size of the executable. This can be avoided with a few additions to the above command.

<pre>
vlink -s -P__abox__ <desired executable name> <existing object name> -lamiga
</pre>

-s strip all symbols from the output file 
-P<symbol> preserve this symbol 

For more information, please refer to the documentation for vlink and other programs installed with vbcc.

An Introduction to MorphOS PPC Assembly

2011-01-06T21:58:01Z

AusPPC:

==Jump In The Deep End And Compile Something Right Now==

You could copy and paste but just entering the two lines below into a suitable text editor is probably quicker.

<pre>
.text
blr
</pre>

Save as ''shorty.s''

'''.text''' is an assembler directive - more about it later. '''blr''' is one of many branch instructions. This particular one means 'Branch to Link Register'. When a program terminates, this is the last instruction to be executed and it causes the sequence of instruction execution to pass back to the calling program or environment (shell, Ambient etc). Subroutines can also terminate with this instruction but, again, more about this later.

This is as good a time as any to ask if you've installed vbcc yet - if not, go and do it. [http://mail.pb-owl.de/~frank/vbcc/current/vbcc_bin_morphos.lha Download vbcc]

Once vbcc is installed, open a shell window and change directory to where shorty.s has been saved.

Enter:

<pre>
vasmppc_std -Felf -o ram:shorty.o shorty.s
</pre>

This tells vasm to generate an ELF formatted object file called ''shorty.o'' in ram: from the ''shorty.s'' source file.

==Hello? World's Shortest MorphOS Program - Or Is It?==

There are times when a linker is needed to further process an object file to generate an executable - this isn't one of those times.

Go ahead and enter this into the shell window:

<pre>
ram:shorty.o
</pre>

It will appear as if nothing happens - but at least it happens very quickly. However, something did happen. shorty.o was identified as an executable program and loaded into memory where the cpu instruction execution sequence passed to it. As mentioned above, the single '''blr''' instruction in this program caused the instruction execution sequence to pass directly back to where it was called from - in this case, the shell.

It may be of interest to know that all PPC instructions are four bytes long. In PPC nomenclature, this length is known as a word. But let's take a moment to have a look at the size of shorty.o

Enter this into the shell window:

<pre>
list ram:shorty.o
</pre>

2664 bytes?! But this is typical for object files as they contain much additional information that is used in the process of debugging and linking. Linking, particularly with the -s 'strip all symbols' option, will generate an executable that is noticeably smaller.

Try entering this into the shell window:

<pre>
vlink -s -o ram:shorty ram:shorty.o

list ram:shorty
</pre>

The newly generated executable is 328 bytes - much smaller than it's object file but what are those other 324 bytes doing there? They are the ELF 'container' that holds the single, four byte instruction of shorty. ELF stands for Executable and Linkable Format and it is used by MorphOS, AmigaOS4 and AROS - not to forget, Linux, UNIX, BSD and even video game consoles. There is abundant information about this file format online but this topic will be discussed a little further when the use of the objdump program is introduced.

==The Old And The New==

Generally, in order to make a program that does something useful or to at least produce an observable result, it is necessary to use operating system library functions. Despite the markedly different cpu family that MorphOS runs on compared to the 68k family used by the classic AmigaOS, MorphOS is largely compatible with AmigaOS. This compatibility is reflected in a very similar API shared with AmigaOS and extends to using a MorphOS system structure as if it were the internal data and address registers of an actual 68k processor. This is called the EmulHandle structure and it is always available through the PPC GPR2 register. Also, as with 68k AmigaOS, the address of the Exec library base is always to be found at memory location 4. Many aspects of the AmigaOS API fit closely to the features available in the 68k cpu and the following code comparison should illustrate how it is echoed in the PPC MorphOS API.

A common task performed during the initialisation of many programs - opening the Dos library. It is a particularly simple example of library usage but most functions follow this form.

[[File:Old-and-new.png]]

@ha & @l are needed to specify the high and low halfwords of 32 bit immediate values because the fixed 32 bit size of PPC instructions does not allow enough space for an instruction opcode and additional 32 bits of data.

One could be forgiven for thinking that the PPC code snippet looks a little ungainly compared to the former. Whereas every PPC instruction is four bytes long, 68k instructions can be as little as two bytes but up to as many as ten. A single 68k instruction can load a value from a 32 bit memory address specified by one instruction operand and store it at another 32 bit memory address specified by the second instruction operand. The 68k can also perform other operations beyond simple loads and stores directly on memory. Or at least appear to... In truth, computer memory only sends and receives data - no other data processing (like adding, subtracting & etc) occurs in memory. While the 68k instruction '''add.l #$12345678,(a0)''' appears to add the immediate value of it's first operand to whatever may already be stored at the address pointed to by a0, the contents of that address are actually loaded from memory into a private work register, the addition is performed and then the result is stored back to the same memory location. So this instruction actually performs two memory accesses where it might appear that there was only one. Contrast this with PPC assembly programming where memory loads and stores are all done explicitly. Before data can be operated upon it must be loaded from memory into a GPR (General Purpose Register), zero (in the case of a simple memory copy) or more operations can then be performed and then the data may be stored back to memory.

Unless you are brand-spanking-new to the topic of PPC assembly, you will already know that the PPC has 32 GPRs - r0 through r31. But did you know that the desired use of these registers is set out in something called the System V.4 ABI which MorphOS adheres to?

<pre>
r0 - volatile
r1 - stack pointer
r2 - for system use (with MorphOS, r2 points to the EmulHandle structure)

r3 - initialised with a pointer to a Dos command buffer
r4 - initialised with the length of the Dos command buffer
r5 - initialised with a pointer to an ELF structure

r3 ... r10 volatile & can be used to pass function arguments. If more
arguments are required, the stack is used.

r11 & r12 - volatile

r13 - small data area pointer. If this register is needed by a function or
subroutine, it must be saved first and then restored before
returning to where it was called from.

r14 ... r31 - No predefined purpose. If these registers are needed by a
function or subroutine, they must be saved first and then restored
before returning to where it was called from.
</pre>

The above use of the word 'volatile' means that functions are not expected to preserve the contents of these registers. r1 & r2 are the only registers that must be restored to their initial values by a terminating program, however, while most programs will modify r1 and later restore it, it is best to have not modified r2 in the first place.

This System V.4 ABI also sets out a particular way for programs and subroutines to organise their stack frames. When a program is loaded into memory and the instruction execution sequence passes to it, the stack pointer is still pointing to the calling program's stack frame and there is also an important address stored in the Link Register at this time. Unless this program is very simple (like shorty) it must save the Link Register address and, most likely, create it's own stack frame. Somewhat conveniently, there is a special position in the caller's stack frame that a callee program can save the contents of the Link Register to. This is a fairly common example of a program or subroutine's very first instructions.

[[File:Awkward-program-initialisation.png]]

Uh indeed... Let's try to visualise some memory being used as stack space.

[[File:Stack-diagram16.png]]

Note that '''stwu r1,-8(r1)''' creates a two-word stack frame which is the smallest stack that a program or subroutine can have if it, in turn, calls another program, subroutine or library function. More often, a larger stack frame is created although, '''stwu r1,-4(r1)''' could be used by a program or subroutine to create a one-word stack frame but this would be redundant and such a program must not call any other program, subroutine or library function. Such a program would not need to store the value in the Link Register (LR) to prevent it from being overwritten by subsequent calls and can terminate and return to it's caller with a simple '''blr''' instruction - just like shorty does.

A further note about larger stack frames and appropriate stack sizes: For reasons relating to PPC architecture, it is a good idea to choose stack frame sizes that are multiples of 16 bytes.

This is a less common example of a program's first instructions but it may better illustrate how to use stack frames.

[[File:Program-initialisation.png]]

Let's jump ahead and look at the last few instructions involved in program termination that would 'undo' the above instructions.

[[File:Program-termination.png]]

==A Little Less Talk And A Little More Action Please==

It's time to compile another program - this one will actually do something.

But wait...

Not another 'Hello World' program... I'm afraid so. This time, copy and paste is probably quicker. Alternatively, download this fully commented [http://aminet.net/dev/src/MorphOS-PPC-HelloWorld.lha source archive].

Note that this example does not use the MorphOS SDK. Instead, some 'quick and dirty' methods are used for the sake of simplicity and readability.

<pre>
# Various library function offsets
.set _LVOOpenLibrary,-552
.set _LVOCloseLibrary,-414
.set _LVOVPrintf,-954

.set _AbsExecBase,4

# EmulHandle structure (always pointed to by r2)
.set reg_d0,0
.set reg_d1,4
.set reg_d2,8
.set reg_d3,12
.set reg_d4,16
.set reg_d5,20
.set reg_d6,24
.set reg_d7,28
.set reg_a0,32
.set reg_a1,36
.set reg_a2,40
.set reg_a3,44
.set reg_a4,48
.set reg_a5,52
.set reg_a6,56
.set reg_a7,60
.set EmulCallDirectOS,100

# Stack frame offsets
.set stack_pos0_caller_stack,0
.set stack_pos1_callerLR,4
.set stack_pos2_ExecBase,8
.set stack_pos3_DosBase,12
.set new_4_word_stack,16

.text

mflr r0
stw r0,stack_pos1_callerLR(r1)
stwu r1,-new_4_word_stack(r1)

lis r3,dosName@ha
addi r3,r3,dosName@l
stw r3,reg_a1(r2)
li r3,0
stw r3,reg_d0(r2)
li r3,_AbsExecBase
lwz r3,0(r3)
stw r3,stack_pos2_ExecBase(r1)
stw r3,reg_a6(r2)
li r3,_LVOOpenLibrary
lwz r0,EmulCallDirectOS(r2)
mtctr r0
bctrl

cmpwi r3,0
beq exit

stw r3,stack_pos3_DosBase(r1)

lis r4,string1@ha
addi r4,r4,string1@l
stw r4,reg_d1(r2)
li r4,0
stw r4,reg_d2(r2)
stw r3,reg_a6(r2)
li r3,_LVOVPrintf
lwz r0,EmulCallDirectOS(r2)
mtctr r0
bctrl

lwz r3,stack_pos3_DosBase(r1)
stw r3,reg_a1(r2)
lwz r3,stack_pos2_ExecBase(r1)
stw r3,reg_a6(r2)
li r3,_LVOCloseLibrary
lwz r0,EmulCallDirectOS(r2)
mtctr r0
bctrl

li r3,0

exit: addi r1,r1,new_4_word_stack
lwz r0,stack_pos1_callerLR(r1)
mtlr r0
blr

.rodata
#__abox__ is a special MorphOS symbol that will differentiate
__abox__: #this program from other PPC executables that can run on MorphOS...
#When linking, care should be taken to avoid stripping this symbol.
dosName:
.string "dos.library"

string1:
.string "Hello World\n"
</pre>

Save this source file as HelloWorld.s and open a shell window. Change directory to where HelloWorld.s was just saved and enter:

<pre>
vasmppc_std -Felf -o ram:hw.o HelloWorld.s
</pre>

Once again, because of the simplicity of this program, linking isn't necessary so just enter the following in the shell window:

<pre>
ram:hw.o
</pre>

Are you impressed? Feel free to modify, experiment with and improve this source code. A not-too-difficult challenge might be to change this program so that it prints the arguments given to it in the shell window - a number of small but significant changes would be needed to do this. ''Hint: Have another look at the System V.4 register usage above.''

The commented version of HelloWorld.s in the downloadable source archive gives a brief description of why the '''mtctr''' (move to Count Register) & '''bctrl''' (branch to Count Register and link) instruction pair are used in preference to '''mtlr''' (move to Link Register) & '''blrl''' (branch to Link Register and link) - being that the latter pair can degrade performance optimisations of some PPC cpus. However, the primary use of the Count Register is as a 32 bit loop counter that can be automatically decremented by certain branch instructions.

When choosing which registers to use in your own programs, be aware that use of r0 in some instruction operands will not always work as you might expect. In these instructions, the actual content of r0 is ignored and the result is based on the constant value zero instead. For example, imagine that r0 contains the value 100 when this instruction is executed: '''addi r0,r0,50''' It looks like the result should be r0 = r0 + 50 = 150 The result will actually be r0 = 0 + 50 = 50 This may seem odd but, as long as the programmer is aware of it, this behaviour can be useful. A good PPC instruction reference manual will explain this, and many other things, in much greater detail. There are many of these reference documents available online - this is one of them: [http://www.freescale.com/files/product/doc/MPCFPE32B.pdf MPCFPE32B.pdf]

==MorphOS SDK, Objdump, ELFs & Sections==

In addition to installing vbcc, it is also recommended to install the [http://www.morphos-team.net/files/sdk-20100617.lha MorphOS SDK] and the [http://mail.pb-owl.de/~frank/vbcc/current/vbcc_target_ppc-morphos.lha vbcc MorphOS compiler target].

The installer script of the latter seems to expect that there is a pre-existing assign for include: and, if your system already assigns include: to somewhere, please skip over this next part.

What follows is my S:user-startup after the installation of vbcc, it's MorphOS compiler target and an additional assign that I made preceded by this comment -

''; vbcc MorphOS target needs include: to be assigned to somewhere''

<pre>
;
; MorphOS user-startup
;
; This script is executed on system boot by
; startup-sequence. You can make personal
; changes in here.
;
; $VER: user-startup 1.1
;

; Enable the following to mount the inet-handler. Note that TCP: allows
; easy access to internet, and allows scripts to listen for incoming
; connections. Some malware could abuse this.
;Mount TCP:
;BEGIN vbcc
assign >NIL: vbcc: SYS:vbcc
assign >NIL: C: vbcc:bin ADD
setenv VBCC vbcc:
;END vbcc

; vbcc MorphOS target needs include: to be assigned to somewhere
assign include: SDK:GG/os-include

;BEGIN vbcc-ppc-morphos
assign >NIL: vincludemos: vbcc:targets/ppc-morphos/include
assign >NIL: vincludemos: include: add
assign >NIL: vlibmos: vbcc:targets/ppc-morphos/lib
;END vbcc-ppc-morphos
</pre>

At this point it would be useful to have a number of freshly generated object files and executables to look at with objdump although any ELF can be used for this purpose. Note that while MorphOS 2.x system files are compiled as ELFs, they are also signed to prevent their use on MorphOS 1.x where they may not work. This signing also has the effect of causing objdump not to recognise them as ELFs.

Objdump can be used to reveal a lot of interesting information about an ELF including listing any symbols and sections that are present as well as disassembling. Be aware that, when disassembled, seemingly small programs can produce more output than the shell window's history buffer can hold so either redirect the output to a file or specify start and stop addresses to limit the output. Having said that, none of the files generated so far in this tutorial are at risk of overwhelming the shell's history buffer when disassembled.

''more content needed here''

As mentioned just before the previous source code example, some quick and dirty methods were used for the sake of simplicity and readability and this refers to the way library function offsets were established. The approach used will quickly become detrimental as more offsets are added. There are a number of solutions to this problem but only one will be presented here and it involves the removal of the leading underscore character from function names so that, for example, '''li r3,_LVOOpenLibrary''' becomes '''li r3,LVOOpenLibrary'''. Remove or comment out the first three '''.set''' directives that define the library function offsets and assemble with vasm as before but note that the resulting object file is no longer executable. To make this object executable, vlink is needed.

<pre>
vlink -o <desired executable name> <existing object name> -lamiga
</pre>

In the above shell command, -lamiga refers to the ''libamiga.a'' file that vlink knows to look for in ''vlibmos:'' This file contains information used to resolve many library function names to numerical values. Note that any executable generated from the above vlink command will contain a lot of symbol information that, while potentially useful, increases the size of the executable. This can be avoided with a few additions to the above command.

<pre>
vlink -s -P__abox__ <desired executable name> <existing object name> -lamiga
</pre>

-s strip all symbols from the output file 
-P<symbol> preserve this symbol 

For more information, please refer to the documentation for vlink and other programs installed with vbcc.

General Rules and Purpose of Subclassing

2011-01-06T21:52:59Z

AusPPC: Fixing minor typos and other small changes for readability.

''Grzegorz Kraszewski''

==Introduction==

Subclassing is one of the essential object oriented programming techniques. In MUI subclassing is used for the following purposes:
* Implementing program functionality as a set of methods. The ''Application'' class is usually used for this purpose.
* Customizing classes by writing methods intentionally left unimplemented (or having some default implementations) in standard MUI classes. The most common example is the ''List'' class, but also the ''Numeric'' one and others.
* Writing custom drawn gadgets or areas. The ''Area'' class is subclassed in this case.
Regardless of the reason for subclassing, it is always done in the same way. A programmer must write new methods or override existing methods, create a dispatcher function, define an instance data structure (an empty one in some cases), then create the class. It is worth noting, subclassing MUI classes is done the same as subclassing [[Short_BOOPSI_Overview|BOOPSI ones]]. The only difference is that MUI provides its [[Short_BOOPSI_Overview#MUI_Extensions_to_BOOPSI|own functions]] for class creation and disposition.

==Object Data==

Object data are stored in a memory area automatically allocated for every object created. The object data area is used for storing attribute values and for internal variables and buffers. This area is usually defined as a structure. Size of the area is passed to the ''MUI_CreateCustomClass()'' function. In a class hierarchy, every class may add its own contribution to the object data area. Unlike in C++, a class has no direct access to anything except its own data area. It can't access data defined in the superclass (In C++ it is possible that a field is declared as ''protected'' or ''public''). Object data defined in any of the superclasses may only be accessed using methods or attributes provided by these superclasses.

Because of internal [[Short BOOPSI Overview|BOOPSI]] design, the size of the data instance area is limited to 64 kB. Large buffers should be allocated dynamically in OM_NEW() and freed in OM_DISPOSE(). The area data is always cleared to all zeros at object creation. If a class does not need any object instance data it can pass 0 as the area size to ''MUI_CreateCustomClass()''.

==Writing Methods==
A MUI method is just a plain C function, but with a partially fixed prototype.

IPTR ''MethodName''(Class *cl, Object *obj, ''MessageType'' *msg);

The method return value may be either integer or pointer to anything. That is why it uses the ''IPTR'' type which means "integer big enough to hold a pointer". In the current MorphOS it is just a 32-bit integer (the same as ''LONG''). If a method has no meaningful value to return, it can just return 0. Two first, fixed arguments are: pointer to the class and pointer to the object. The last one is a method message. When a method is being overridden, the type of message is determined by the superclass. For a new method, message type is defined by the programmer. Some methods may have empty messages (containing only a method identifier), in this case the third argument may be omitted.

Most methods need access to the object instance data. To get a pointer to the data area, one uses the ''INST_DATA'' macro, defined in ''<intuition/classes.h>''. An example below shows the macro usage:

struct ObjData
{
LONG SomeVal;
/* ... */
};

IPTR SomeMethod(Class *cl, Object *obj)
{
struct ObjData *d = (struct ObjData*)'''INST_DATA(cl, obj)''';

d->SomeVal = 14;
/* ... */
return 0;
}

If a method is an overridden method from a superclass, it may want to perform the superclass method. There are no implicit super method calls in MUI. The superclass method must always be called explicitly with the ''DoSuperMethodA()'' call:

result = DoSuperMethodA(cl, obj, msg);
result = DoSuperMethod(cl, obj, ''MethodID'', ...);

The second form rebuilds the method message from variable arguments, and is used when the message is modified before calling the superclass method. The super method may be called in any place of the method, or may not be called at all. For MUI standard classes and methods, rules of calling super methods are described in the documentation and will be discussed later in this tutorial. For custom methods the question of calling a super method is up to the application programmer.

==The Dispatcher==
A dispatcher function is a kind of jump table for methods. When any method is called on an object (with ''DoMethod()''), BOOPSI finds the dispatcher of the object's class and calls it. The dispatcher checks a method identifier, which is always the first field of any method message. Based on the identifier, a method is called. If a method is unknown to the class, the dispatcher should pass it to the superclass with the ''DoSuperMethod()'' call.

The dispatcher is a kind of [[Hooks|hook]] function. It makes its calling convention independent of programming language. A disadvantage of this is that the dispatcher's arguments are passed in virtual M68k processor registers. This inconvenience allows support for legacy M68k software and also allows for native PowerPC classes to be used by M68k applications and old M68k classes to be used by native applications. Being a hook, a dispatcher needs an ''EmulLibEntry'' structure to be created and filled first. The structure is defined in ''<emul/emulinterface.h>'' and acts as a data gate between PowerPC native code and the M68k emulator.

const struct EmulLibEntry ClassGate = {TRAP_LIB, 0, (void(*)(void))ClassDispatcher};

Then the dispatcher is defined as follows:

IPTR ClassDispatcher(void)
{
Class *cl = (Class*)REG_A0;
Object *obj = (Object*)REG_A2;
Msg msg = (Msg)REG_A1;

/* ... */

Arguments of the dispatcher are the same as arguments of a method. They are passed in virtual M680x0 processor address registers A0, A1 and A2 instead of being just arguments. The dispatcher's data gate is passed as an argument to ''MUI_CreateCustomClass()''. The data gate is used even when a native application calls a native dispatcher. It introduces some overhead, but it's negligible. Many programmers prefer to hide these details behind a set of preprocessor macros, such macros have not been used here however, for better understanding.

The ''Msg'' type is a root type for all method messages. It defines a structure containing only the method identifier field (defined as ULONG). All following parameters have to keep the CPU stack aligned, as ''DoMethod()'' builds the message on the stack. It requires that every parameter is defined either as an ''IPTR'' or as a pointer.

After receiving arguments the dispatcher checks the method identifier from the message and jumps to the respective method. It is usually implemented as a ''switch'' statement. If only a few methods are implemented, it may also be an ''if/if else'' cascade. Here is a typical example:

switch (msg->MethodID)
{
case OM_NEW: return MyClassNew(cl, obj, (struct opSet*)msg);
case OM_DISPOSE: return MyClassDispose(cl, obj, msg);
case OM_SET: return MyClassSet(cl, obj, (struct opSet*)msg);
case OM_GET: return MyClassGet(cl, obj, (struct opGet*)msg);
case MUIM_Draw: return MyClassDraw(cl, obj, (struct MUIP_Draw*)msg);
case MUIM_AskMinMax: return MyClassAskMinMax(cl, obj, (struct MUIP_AskMinMax*)msg);
/* ... */
default: return DoSuperMethodA(cl, obj, msg);
}

For every method a message pointer is typecast to a message structure of this particular method. Some programmers place the method's code inside the ''switch'' statement directly, especially if methods are short and only a few. In the example above, some methods of ''Area'' class are overridden. The naming scheme used for the method functions is just an example, there are no constraints on this. Although prefixing method function names with a class name has an advantage of avoiding name conflicts between custom classes if method functions are not declared as ''static''.

==Class Creation==

Having all components done (methods, dispatcher, gate, object data structure) one can create a MUI class.

struct MUI_CustomClass *MyClass;

MyClass = MUI_CreateCustomClass(NULL, MUIC_Area, NULL, sizeof(struct MyClassData),
(APTR)&MyClassGate);

The first argument is a library base if the created class is public. Writing MUI public classes will be covered later. Let's say for now, that public classes are implemented as shared libraries, so such a public class has a library base. For private classes this argument should always be ''NULL''.

The next two arguments are used alternatively and specify the superclass. The superclass may be either private (referenced by pointer) or public (referenced by name). Public classes are usually subclassed, so the pointer is set to ''NULL'' as in the example. More complex projects may use multilevel subclassing and subclass their own private classes. In this case, a pointer to a private class is passed as the first argument and the second one is ''NULL''.

The fourth argument defines the size of the object data area in bytes. In most cases object data area is defined as a structure, so using the ''sizeof()'' operator is the obvious way of determining the size. If the class does not need any per-object data, zero may be passed here.

The last argument is an address of the data gate (''EmulLibEntry'' structure). Programmers experienced on M68k programming may notice that there is a difference – in M68k code only the dispatcher function address is used here. As mentioned above, seamless M68k code support requires that program execution passes through the data gate when going from system code to the dispatcher. That is why the data gate address is placed as this argument, then the data gate contains a real dispatcher address.

==Class Disposition==

A MUI class is disposed with a call to ''MUI_DeleteCustomClass()''.

if (MyClass) MUI_DeleteCustomClass(MyClass);

Some conditions must be fulfilled before calling this function.
* Call it only if the class was successfully created. Calling it with a ''NULL'' class pointer is deadly (hence the checking for ''NULL'' in the example).
* Do not delete a class if it has any remaining subclasses or objects. The best practice is to create all classes before creating the application GUI and to dispose them after the final ''MUI_DisposeObject()'' of the main ''Application'' object. Classes should be deleted in the reversed order of creation. ''MUI_DeleteCustomClass()'' returns a boolean value. It is FALSE when a class cannot be deleted because of potentially orphaned subclasses or objects.

An Introduction to MorphOS PPC Assembly

2010-12-11T05:22:08Z

AusPPC: overlooked a bad path name in user-startup

==Jump In The Deep End And Compile Something Right Now==

You could copy and paste but just entering the two lines below into a suitable text editor is probably quicker.

<pre>
.text
blr
</pre>

Save as ''shorty.s''

'''.text''' is an assembler directive - more about it later. '''blr''' is one of many branch instructions. This particular one means 'Branch to Link Register'. When a program terminates, this is the last instruction to be executed and it causes the sequence of instruction execution to pass back to the calling program or environment (shell, Ambient etc). Subroutines can also terminate with this instruction but, again, more about this later.

This is as good a time as any to ask if you've installed vbcc yet - if not, go and do it. [http://mail.pb-owl.de/~frank/vbcc/current/vbcc_bin_morphos.lha Download vbcc]

Once vbcc is installed, open a shell window and change directory to where shorty.s has been saved.

Enter:

<pre>
vasmppc_std -Felf -o ram:shorty.o shorty.s
</pre>

This tells vasm to generate an ELF formatted object file called shorty.o in ram: from the shorty.s source file.

==Hello? World's Shortest MorphOS Program - Or Is It?==

There are times when a linker is needed to further process an object file to generate an executable - this isn't one of those times.

Go ahead and enter this into the shell window:

<pre>
ram:shorty.o
</pre>

It will appear as if nothing happens - but at least it happens very quickly. However, something did happen. shorty.o was identified as an executable program and loaded into memory where the cpu instruction execution sequence passed to it. As mentioned above, the single '''blr''' instruction in this program caused the instruction execution sequence to pass directly back to where it was called from - in this case, the shell.

It may be of interest to know that all PPC instructions are four bytes long. In PPC nomenclature, this length is known as a word. But let's take a moment to have a look at the size of shorty.o

Enter this into the shell window:

<pre>
list ram:shorty.o
</pre>

2664 bytes?! But this is typical for object files as they contain much additional information that is used in the process of debugging and linking. Linking, particularly with the -s 'strip all symbols' option, will generate an executable that is noticeably smaller.

Try entering this into the shell window:

<pre>
vlink -s -o ram:shorty ram:shorty.o

list ram:shorty
</pre>

The newly generated executable is 328 bytes - much smaller than it's object file but what are those other 324 bytes doing there? They are the ELF 'container' that holds the single, four byte instruction of shorty. ELF stands for Executable and Linkable Format and it is used by MorphOS, AmigaOS4 and AROS - not to forget, Linux, UNIX, BSD and even video game consoles. There is abundant information about this file format online but this topic will be discussed a little further when the use of the objdump program is introduced.

==The Old And The New==

Generally, in order to make a program that does something useful or to at least produce an observable result, it is necessary to use operating system library functions. Despite the markedly different cpu family that MorphOS runs on compared to the 68k family used by the classic AmigaOS, MorphOS is largely compatible with AmigaOS. This compatibility is reflected in a very similar API shared with AmigaOS and extends to using a MorphOS system structure as if it were the internal data and address registers of an actual 68k processor. This is called the EmulHandle structure and it is always available through the PPC GPR2 register. Also, as with 68k AmigaOS, the address of the Exec library base is always to be found at memory location 4. Many aspects of the AmigaOS API fit closely to the features available in the 68k cpu and the following code comparison should illustrate how it is echoed in the PPC MorphOS API.

A common task performed during the initialisation of many programs - opening the Dos library. It is a particularly simple example of library usage but most functions follow this form.

[[File:Old-and-new.png]]

@ha & @l are needed to specify the high and low halfwords of 32 bit immediate values because the fixed 32 bit size of PPC instructions does not allow enough space for an instruction opcode and additional 32 bits of data.

One could be forgiven for thinking that the PPC code snippet looks a little ungainly compared to the former. Whereas every PPC instruction is four bytes long, 68k instructions can be as little as two bytes but up to as many as ten. A single 68k instruction can load a value from a 32 bit memory address specified by one instruction operand and store it at another 32 bit memory address specified by the second instruction operand. The 68k can also perform other operations beyond simple loads and stores directly on memory. Or at least appear to... In truth, computer memory only sends and receives data - no other data processing (like adding, subtracting & etc) occurs in memory. While the 68k instruction '''add.l #$12345678,(a0)''' appears to add the immediate value of it's first operand to whatever may already be stored at the address pointed to by a0, the contents of that address are actually loaded from memory into a private work register, the addition is performed and then the result is stored back to the same memory location. So this instruction actually performs two memory accesses where it might appear that there was only one. Contrast this with PPC assembly programming where memory loads and stores are all done explicitly. Before data can be operated upon it must be loaded from memory into a GPR (General Purpose Register), zero (in the case of a simple memory copy) or more operations can then be performed and then the data may be stored back to memory.

Unless you are brand-spanking-new to the topic of PPC assembly, you will already know that the PPC has 32 GPRs - r0 through r31. But did you know that the desired use of these registers is set out in something called the System V.4 ABI which MorphOS adheres to?

<pre>
r0 - volatile
r1 - stack pointer
r2 - for system use (with MorphOS, r2 points to the EmulHandle structure)

r3 - initialised with a pointer to a Dos command buffer
r4 - initialised with the length of the Dos command buffer
r5 - initialised with a pointer to an ELF structure

r3 ... r10 volatile & can be used to pass function arguments. If more
arguments are required, the stack is used.

r11 & r12 - volatile

r13 - small data area pointer. If this register is needed by a function or
subroutine, it must be saved first and then restored before
returning to where it was called from.

r14 ... r31 - No predefined purpose. If these registers are needed by a
function or subroutine, they must be saved first and then restored
before returning to where it was called from.
</pre>

The above use of the word 'volatile' means that functions are not expected to preserve the contents of these registers. r1 & r2 are the only registers that must be restored to their initial values by a terminating program, however, while most programs will modify r1 and later restore it, it is best to have not modified r2 in the first place.

This System V.4 ABI also sets out a particular way for programs and subroutines to organise their stack frames. When a program is loaded into memory and the instruction execution sequence passes to it, the stack pointer is still pointing to the calling program's stack frame and there is also an important address stored in the Link Register at this time. Unless this program is very simple (like shorty) it must save the Link Register address and, most likely, create it's own stack frame. Somewhat conveniently, there is a special position in the caller's stack frame that a callee program can save the contents of the Link Register to. This is a fairly common example of a program or subroutine's very first instructions.

[[File:Awkward-program-initialisation.png]]

Uh indeed... Let's try to visualise some memory being used as stack space.

[[File:Stack-diagram16.png]]

Note that '''stwu r1,-8(r1)''' creates a two-word stack frame which is the smallest stack that a program or subroutine can have if it, in turn, calls another program, subroutine or library function. More often, a larger stack frame is created although, '''stwu r1,-4(r1)''' could be used by a program or subroutine to create a one-word stack frame but this would be redundant and such a program must not call any other program, subroutine or library function. Such a program would not need to store the value in the Link Register (LR) to prevent it from being overwritten by subsequent calls and can terminate and return to it's caller with a simple '''blr''' instruction - just like shorty does.

A further note about larger stack frames and appropriate stack sizes: For reasons relating to PPC architecture, it is a good idea to choose stack frame sizes that are multiples of 16 bytes.

This is a less common example of a program's first instructions but it may better illustrate how to use stack frames.

[[File:Program-initialisation.png]]

Let's jump ahead and look at the last few instructions involved in program termination that would 'undo' the above instructions.

[[File:Program-termination.png]]

==A Little Less Talk And A Little More Action Please==

It's time to compile another program - this one will actually do something.

But wait...

Not another 'Hello World' program... I'm afraid so. This time, copy and paste is probably quicker. Alternatively, download this fully commented [http://aminet.net/dev/src/MorphOS-PPC-HelloWorld.lha source archive].

Note that this example does not use the MorphOS SDK. Instead, some 'quick and dirty' methods are used for the sake of simplicity and readability.

<pre>
# Various library function offsets
.set _LVOOpenLibrary,-552
.set _LVOCloseLibrary,-414
.set _LVOVPrintf,-954

.set _AbsExecBase,4

# EmulHandle structure (always pointed to by r2)
.set reg_d0,0
.set reg_d1,4
.set reg_d2,8
.set reg_d3,12
.set reg_d4,16
.set reg_d5,20
.set reg_d6,24
.set reg_d7,28
.set reg_a0,32
.set reg_a1,36
.set reg_a2,40
.set reg_a3,44
.set reg_a4,48
.set reg_a5,52
.set reg_a6,56
.set reg_a7,60
.set EmulCallDirectOS,100

# Stack frame offsets
.set stack_pos0_caller_stack,0
.set stack_pos1_callerLR,4
.set stack_pos2_ExecBase,8
.set stack_pos3_DosBase,12
.set new_4_word_stack,16

.text

mflr r0
stw r0,stack_pos1_callerLR(r1)
stwu r1,-new_4_word_stack(r1)

lis r3,dosName@ha
addi r3,r3,dosName@l
stw r3,reg_a1(r2)
li r3,0
stw r3,reg_d0(r2)
li r3,_AbsExecBase
lwz r3,0(r3)
stw r3,stack_pos2_ExecBase(r1)
stw r3,reg_a6(r2)
li r3,_LVOOpenLibrary
lwz r0,EmulCallDirectOS(r2)
mtctr r0
bctrl

cmpwi r3,0
beq exit

stw r3,stack_pos3_DosBase(r1)

lis r4,string1@ha
addi r4,r4,string1@l
stw r4,reg_d1(r2)
li r4,0
stw r4,reg_d2(r2)
stw r3,reg_a6(r2)
li r3,_LVOVPrintf
lwz r0,EmulCallDirectOS(r2)
mtctr r0
bctrl

lwz r3,stack_pos3_DosBase(r1)
stw r3,reg_a1(r2)
lwz r3,stack_pos2_ExecBase(r1)
stw r3,reg_a6(r2)
li r3,_LVOCloseLibrary
lwz r0,EmulCallDirectOS(r2)
mtctr r0
bctrl

li r3,0

exit: addi r1,r1,new_4_word_stack
lwz r0,stack_pos1_callerLR(r1)
mtlr r0
blr

.rodata
#__abox__ is a special MorphOS symbol that will differentiate
__abox__: #this program from other PPC executables that can run on MorphOS...
#When linking, care should be taken to avoid stripping this symbol.
dosName:
.string "dos.library"

string1:
.string "Hello World\n"
</pre>

Save this source file as HelloWorld.s and open a shell window. Change directory to where HelloWorld.s was just saved and enter:

<pre>
vasmppc_std -Felf -o ram:hw.o HelloWorld.s
</pre>

Once again, because of the simplicity of this program, linking isn't necessary so just enter the following in the shell window:

<pre>
ram:hw.o
</pre>

Are you impressed? Feel free to modify, experiment with and improve this source code. A not-too-difficult challenge might be to change this program so that it prints the arguments given to it in the shell window - a number of small but significant changes would be needed to do this. ''Hint: Have another look at the System V.4 register usage above.''

The commented version of HelloWorld.s in the downloadable source archive gives a brief description of why the '''mtctr''' (move to Count Register) & '''bctrl''' (branch to Count Register and link) instruction pair are used in preference to '''mtlr''' (move to Link Register) & '''blrl''' (branch to Link Register and link) - being that the latter pair can degrade performance optimisations of some PPC cpus. However, the primary use of the Count Register is as a 32 bit loop counter that can be automatically decremented by certain branch instructions.

When choosing which registers to use in your own programs, be aware that use of r0 in some instruction operands will not always work as you might expect. In these instructions, the actual content of r0 is ignored and the result is based on the constant value zero instead. For example, imagine that r0 contains the value 100 when this instruction is executed: '''addi r0,r0,50''' It looks like the result should be r0 = r0 + 50 = 150 The result will actually be r0 = 0 + 50 = 50 This may seem odd but, as long as the programmer is aware of it, this behaviour can be useful. A good PPC instruction reference manual will explain this, and many other things, in much greater detail. There are many of these reference documents available online - this is one of them: [http://www.freescale.com/files/product/doc/MPCFPE32B.pdf MPCFPE32B.pdf]

==MorphOS SDK, Objdump, ELFs & Sections==

In addition to installing vbcc, it is also recommended to install the [http://www.morphos-team.net/files/sdk-20100617.lha MorphOS SDK] and the [http://mail.pb-owl.de/~frank/vbcc/current/vbcc_target_ppc-morphos.lha vbcc MorphOS compiler target].

The installer script of the latter seems to expect that there is a pre-existing assign for include: and, if your system already assigns include: to somewhere, please skip over this next part.

What follows is my S:user-startup after the installation of vbcc, it's MorphOS compiler target and an additional assign that I made preceded by this comment -

''; vbcc MorphOS target needs include: to be assigned to somewhere''

<pre>
;
; MorphOS user-startup
;
; This script is executed on system boot by
; startup-sequence. You can make personal
; changes in here.
;
; $VER: user-startup 1.1
;

; Enable the following to mount the inet-handler. Note that TCP: allows
; easy access to internet, and allows scripts to listen for incoming
; connections. Some malware could abuse this.
;Mount TCP:
;BEGIN vbcc
assign >NIL: vbcc: SYS:vbcc
assign >NIL: C: vbcc:bin ADD
setenv VBCC vbcc:
;END vbcc

; vbcc MorphOS target needs include: to be assigned to somewhere
assign include: SDK:GG/os-include

;BEGIN vbcc-ppc-morphos
assign >NIL: vincludemos: vbcc:targets/ppc-morphos/include
assign >NIL: vincludemos: include: add
assign >NIL: vlibmos: vbcc:targets/ppc-morphos/lib
;END vbcc-ppc-morphos
</pre>

At this point it would be useful to have a number of freshly generated object files and executables to look at with objdump although any ELF can be used for this purpose. Note that while MorphOS 2.x system files are compiled as ELFs, they are also signed to prevent their use on MorphOS 1.x where they may not work. This signing also has the effect of causing objdump not to recognise them as ELFs.

Objdump can be used to reveal a lot of interesting information about an ELF including listing any symbols and sections that are present as well as disassembling. Be aware that, when disassembled, seemingly small programs can produce more output than the shell window's history buffer can hold so either redirect the output to a file or specify start and stop addresses to limit the output. Having said that, none of the files generated so far in this tutorial are at risk of overwhelming the shell's history buffer when disassembled.

''more content needed here''

As mentioned just before the previous source code example, some quick and dirty methods were used for the sake of simplicity and readability and this refers to the way library function offsets were established. The approach used will quickly become detrimental as more offsets are added. There are a number of solutions to this problem but only one will be presented here and it involves the removal of the leading underscore character from function names so that, for example, '''li r3,_LVOOpenLibrary''' becomes '''li r3,LVOOpenLibrary'''. Remove or comment out the first three '''.set''' directives that define the library function offsets and assemble with vasm as before but note that the resulting object file is no longer executable. To make this object executable, vlink is needed.

<pre>
vlink -o <desired executable name> <existing object name> -lamiga
</pre>

In the above shell command, -lamiga refers to the ''libamiga.a'' file that vlink knows to look for in ''vlibmos:'' This file contains information used to resolve many library function names to numerical values. Note that any executable generated from the above vlink command will contain a lot of symbol information that, while potentially useful, increases the size of the executable. This can be avoided with a few additions to the above command.

<pre>
vlink -s -P__abox__ <desired executable name> <existing object name> -lamiga
</pre>

-s strip all symbols from the output file 
-P<symbol> preserve this symbol 

For more information, please refer to the documentation for vlink and other programs installed with vbcc.

An Introduction to MorphOS PPC Assembly

2010-12-11T05:20:10Z

AusPPC: fixed bad suggestion re: assign include: in user-startup

==Jump In The Deep End And Compile Something Right Now==

You could copy and paste but just entering the two lines below into a suitable text editor is probably quicker.

<pre>
.text
blr
</pre>

Save as ''shorty.s''

'''.text''' is an assembler directive - more about it later. '''blr''' is one of many branch instructions. This particular one means 'Branch to Link Register'. When a program terminates, this is the last instruction to be executed and it causes the sequence of instruction execution to pass back to the calling program or environment (shell, Ambient etc). Subroutines can also terminate with this instruction but, again, more about this later.

This is as good a time as any to ask if you've installed vbcc yet - if not, go and do it. [http://mail.pb-owl.de/~frank/vbcc/current/vbcc_bin_morphos.lha Download vbcc]

Once vbcc is installed, open a shell window and change directory to where shorty.s has been saved.

Enter:

<pre>
vasmppc_std -Felf -o ram:shorty.o shorty.s
</pre>

This tells vasm to generate an ELF formatted object file called shorty.o in ram: from the shorty.s source file.

==Hello? World's Shortest MorphOS Program - Or Is It?==

There are times when a linker is needed to further process an object file to generate an executable - this isn't one of those times.

Go ahead and enter this into the shell window:

<pre>
ram:shorty.o
</pre>

It will appear as if nothing happens - but at least it happens very quickly. However, something did happen. shorty.o was identified as an executable program and loaded into memory where the cpu instruction execution sequence passed to it. As mentioned above, the single '''blr''' instruction in this program caused the instruction execution sequence to pass directly back to where it was called from - in this case, the shell.

It may be of interest to know that all PPC instructions are four bytes long. In PPC nomenclature, this length is known as a word. But let's take a moment to have a look at the size of shorty.o

Enter this into the shell window:

<pre>
list ram:shorty.o
</pre>

2664 bytes?! But this is typical for object files as they contain much additional information that is used in the process of debugging and linking. Linking, particularly with the -s 'strip all symbols' option, will generate an executable that is noticeably smaller.

Try entering this into the shell window:

<pre>
vlink -s -o ram:shorty ram:shorty.o

list ram:shorty
</pre>

The newly generated executable is 328 bytes - much smaller than it's object file but what are those other 324 bytes doing there? They are the ELF 'container' that holds the single, four byte instruction of shorty. ELF stands for Executable and Linkable Format and it is used by MorphOS, AmigaOS4 and AROS - not to forget, Linux, UNIX, BSD and even video game consoles. There is abundant information about this file format online but this topic will be discussed a little further when the use of the objdump program is introduced.

==The Old And The New==

Generally, in order to make a program that does something useful or to at least produce an observable result, it is necessary to use operating system library functions. Despite the markedly different cpu family that MorphOS runs on compared to the 68k family used by the classic AmigaOS, MorphOS is largely compatible with AmigaOS. This compatibility is reflected in a very similar API shared with AmigaOS and extends to using a MorphOS system structure as if it were the internal data and address registers of an actual 68k processor. This is called the EmulHandle structure and it is always available through the PPC GPR2 register. Also, as with 68k AmigaOS, the address of the Exec library base is always to be found at memory location 4. Many aspects of the AmigaOS API fit closely to the features available in the 68k cpu and the following code comparison should illustrate how it is echoed in the PPC MorphOS API.

A common task performed during the initialisation of many programs - opening the Dos library. It is a particularly simple example of library usage but most functions follow this form.

[[File:Old-and-new.png]]

@ha & @l are needed to specify the high and low halfwords of 32 bit immediate values because the fixed 32 bit size of PPC instructions does not allow enough space for an instruction opcode and additional 32 bits of data.

One could be forgiven for thinking that the PPC code snippet looks a little ungainly compared to the former. Whereas every PPC instruction is four bytes long, 68k instructions can be as little as two bytes but up to as many as ten. A single 68k instruction can load a value from a 32 bit memory address specified by one instruction operand and store it at another 32 bit memory address specified by the second instruction operand. The 68k can also perform other operations beyond simple loads and stores directly on memory. Or at least appear to... In truth, computer memory only sends and receives data - no other data processing (like adding, subtracting & etc) occurs in memory. While the 68k instruction '''add.l #$12345678,(a0)''' appears to add the immediate value of it's first operand to whatever may already be stored at the address pointed to by a0, the contents of that address are actually loaded from memory into a private work register, the addition is performed and then the result is stored back to the same memory location. So this instruction actually performs two memory accesses where it might appear that there was only one. Contrast this with PPC assembly programming where memory loads and stores are all done explicitly. Before data can be operated upon it must be loaded from memory into a GPR (General Purpose Register), zero (in the case of a simple memory copy) or more operations can then be performed and then the data may be stored back to memory.

Unless you are brand-spanking-new to the topic of PPC assembly, you will already know that the PPC has 32 GPRs - r0 through r31. But did you know that the desired use of these registers is set out in something called the System V.4 ABI which MorphOS adheres to?

<pre>
r0 - volatile
r1 - stack pointer
r2 - for system use (with MorphOS, r2 points to the EmulHandle structure)

r3 - initialised with a pointer to a Dos command buffer
r4 - initialised with the length of the Dos command buffer
r5 - initialised with a pointer to an ELF structure

r3 ... r10 volatile & can be used to pass function arguments. If more
arguments are required, the stack is used.

r11 & r12 - volatile

r13 - small data area pointer. If this register is needed by a function or
subroutine, it must be saved first and then restored before
returning to where it was called from.

r14 ... r31 - No predefined purpose. If these registers are needed by a
function or subroutine, they must be saved first and then restored
before returning to where it was called from.
</pre>

The above use of the word 'volatile' means that functions are not expected to preserve the contents of these registers. r1 & r2 are the only registers that must be restored to their initial values by a terminating program, however, while most programs will modify r1 and later restore it, it is best to have not modified r2 in the first place.

This System V.4 ABI also sets out a particular way for programs and subroutines to organise their stack frames. When a program is loaded into memory and the instruction execution sequence passes to it, the stack pointer is still pointing to the calling program's stack frame and there is also an important address stored in the Link Register at this time. Unless this program is very simple (like shorty) it must save the Link Register address and, most likely, create it's own stack frame. Somewhat conveniently, there is a special position in the caller's stack frame that a callee program can save the contents of the Link Register to. This is a fairly common example of a program or subroutine's very first instructions.

[[File:Awkward-program-initialisation.png]]

Uh indeed... Let's try to visualise some memory being used as stack space.

[[File:Stack-diagram16.png]]

Note that '''stwu r1,-8(r1)''' creates a two-word stack frame which is the smallest stack that a program or subroutine can have if it, in turn, calls another program, subroutine or library function. More often, a larger stack frame is created although, '''stwu r1,-4(r1)''' could be used by a program or subroutine to create a one-word stack frame but this would be redundant and such a program must not call any other program, subroutine or library function. Such a program would not need to store the value in the Link Register (LR) to prevent it from being overwritten by subsequent calls and can terminate and return to it's caller with a simple '''blr''' instruction - just like shorty does.

A further note about larger stack frames and appropriate stack sizes: For reasons relating to PPC architecture, it is a good idea to choose stack frame sizes that are multiples of 16 bytes.

This is a less common example of a program's first instructions but it may better illustrate how to use stack frames.

[[File:Program-initialisation.png]]

Let's jump ahead and look at the last few instructions involved in program termination that would 'undo' the above instructions.

[[File:Program-termination.png]]

==A Little Less Talk And A Little More Action Please==

It's time to compile another program - this one will actually do something.

But wait...

Not another 'Hello World' program... I'm afraid so. This time, copy and paste is probably quicker. Alternatively, download this fully commented [http://aminet.net/dev/src/MorphOS-PPC-HelloWorld.lha source archive].

Note that this example does not use the MorphOS SDK. Instead, some 'quick and dirty' methods are used for the sake of simplicity and readability.

<pre>
# Various library function offsets
.set _LVOOpenLibrary,-552
.set _LVOCloseLibrary,-414
.set _LVOVPrintf,-954

.set _AbsExecBase,4

# EmulHandle structure (always pointed to by r2)
.set reg_d0,0
.set reg_d1,4
.set reg_d2,8
.set reg_d3,12
.set reg_d4,16
.set reg_d5,20
.set reg_d6,24
.set reg_d7,28
.set reg_a0,32
.set reg_a1,36
.set reg_a2,40
.set reg_a3,44
.set reg_a4,48
.set reg_a5,52
.set reg_a6,56
.set reg_a7,60
.set EmulCallDirectOS,100

# Stack frame offsets
.set stack_pos0_caller_stack,0
.set stack_pos1_callerLR,4
.set stack_pos2_ExecBase,8
.set stack_pos3_DosBase,12
.set new_4_word_stack,16

.text

mflr r0
stw r0,stack_pos1_callerLR(r1)
stwu r1,-new_4_word_stack(r1)

lis r3,dosName@ha
addi r3,r3,dosName@l
stw r3,reg_a1(r2)
li r3,0
stw r3,reg_d0(r2)
li r3,_AbsExecBase
lwz r3,0(r3)
stw r3,stack_pos2_ExecBase(r1)
stw r3,reg_a6(r2)
li r3,_LVOOpenLibrary
lwz r0,EmulCallDirectOS(r2)
mtctr r0
bctrl

cmpwi r3,0
beq exit

stw r3,stack_pos3_DosBase(r1)

lis r4,string1@ha
addi r4,r4,string1@l
stw r4,reg_d1(r2)
li r4,0
stw r4,reg_d2(r2)
stw r3,reg_a6(r2)
li r3,_LVOVPrintf
lwz r0,EmulCallDirectOS(r2)
mtctr r0
bctrl

lwz r3,stack_pos3_DosBase(r1)
stw r3,reg_a1(r2)
lwz r3,stack_pos2_ExecBase(r1)
stw r3,reg_a6(r2)
li r3,_LVOCloseLibrary
lwz r0,EmulCallDirectOS(r2)
mtctr r0
bctrl

li r3,0

exit: addi r1,r1,new_4_word_stack
lwz r0,stack_pos1_callerLR(r1)
mtlr r0
blr

.rodata
#__abox__ is a special MorphOS symbol that will differentiate
__abox__: #this program from other PPC executables that can run on MorphOS...
#When linking, care should be taken to avoid stripping this symbol.
dosName:
.string "dos.library"

string1:
.string "Hello World\n"
</pre>

Save this source file as HelloWorld.s and open a shell window. Change directory to where HelloWorld.s was just saved and enter:

<pre>
vasmppc_std -Felf -o ram:hw.o HelloWorld.s
</pre>

Once again, because of the simplicity of this program, linking isn't necessary so just enter the following in the shell window:

<pre>
ram:hw.o
</pre>

Are you impressed? Feel free to modify, experiment with and improve this source code. A not-too-difficult challenge might be to change this program so that it prints the arguments given to it in the shell window - a number of small but significant changes would be needed to do this. ''Hint: Have another look at the System V.4 register usage above.''

The commented version of HelloWorld.s in the downloadable source archive gives a brief description of why the '''mtctr''' (move to Count Register) & '''bctrl''' (branch to Count Register and link) instruction pair are used in preference to '''mtlr''' (move to Link Register) & '''blrl''' (branch to Link Register and link) - being that the latter pair can degrade performance optimisations of some PPC cpus. However, the primary use of the Count Register is as a 32 bit loop counter that can be automatically decremented by certain branch instructions.

When choosing which registers to use in your own programs, be aware that use of r0 in some instruction operands will not always work as you might expect. In these instructions, the actual content of r0 is ignored and the result is based on the constant value zero instead. For example, imagine that r0 contains the value 100 when this instruction is executed: '''addi r0,r0,50''' It looks like the result should be r0 = r0 + 50 = 150 The result will actually be r0 = 0 + 50 = 50 This may seem odd but, as long as the programmer is aware of it, this behaviour can be useful. A good PPC instruction reference manual will explain this, and many other things, in much greater detail. There are many of these reference documents available online - this is one of them: [http://www.freescale.com/files/product/doc/MPCFPE32B.pdf MPCFPE32B.pdf]

==MorphOS SDK, Objdump, ELFs & Sections==

In addition to installing vbcc, it is also recommended to install the [http://www.morphos-team.net/files/sdk-20100617.lha MorphOS SDK] and the [http://mail.pb-owl.de/~frank/vbcc/current/vbcc_target_ppc-morphos.lha vbcc MorphOS compiler target].

The installer script of the latter seems to expect that there is a pre-existing assign for include: and, if your system already assigns include: to somewhere, please skip over this next part.

What follows is my S:user-startup after the installation of vbcc, it's MorphOS compiler target and an additional assign that I made preceded by this comment -

''; vbcc MorphOS target needs include: to be assigned to somewhere''

<pre>
;
; MorphOS user-startup
;
; This script is executed on system boot by
; startup-sequence. You can make personal
; changes in here.
;
; $VER: user-startup 1.1
;

; Enable the following to mount the inet-handler. Note that TCP: allows
; easy access to internet, and allows scripts to listen for incoming
; connections. Some malware could abuse this.
;Mount TCP:
;BEGIN vbcc
assign >NIL: vbcc: mos26:vbcc
assign >NIL: C: vbcc:bin ADD
setenv VBCC vbcc:
;END vbcc

; vbcc MorphOS target needs include: to be assigned to somewhere
assign include: SDK:GG/os-include

;BEGIN vbcc-ppc-morphos
assign >NIL: vincludemos: vbcc:targets/ppc-morphos/include
assign >NIL: vincludemos: include: add
assign >NIL: vlibmos: vbcc:targets/ppc-morphos/lib
;END vbcc-ppc-morphos
</pre>

At this point it would be useful to have a number of freshly generated object files and executables to look at with objdump although any ELF can be used for this purpose. Note that while MorphOS 2.x system files are compiled as ELFs, they are also signed to prevent their use on MorphOS 1.x where they may not work. This signing also has the effect of causing objdump not to recognise them as ELFs.

Objdump can be used to reveal a lot of interesting information about an ELF including listing any symbols and sections that are present as well as disassembling. Be aware that, when disassembled, seemingly small programs can produce more output than the shell window's history buffer can hold so either redirect the output to a file or specify start and stop addresses to limit the output. Having said that, none of the files generated so far in this tutorial are at risk of overwhelming the shell's history buffer when disassembled.

''more content needed here''

As mentioned just before the previous source code example, some quick and dirty methods were used for the sake of simplicity and readability and this refers to the way library function offsets were established. The approach used will quickly become detrimental as more offsets are added. There are a number of solutions to this problem but only one will be presented here and it involves the removal of the leading underscore character from function names so that, for example, '''li r3,_LVOOpenLibrary''' becomes '''li r3,LVOOpenLibrary'''. Remove or comment out the first three '''.set''' directives that define the library function offsets and assemble with vasm as before but note that the resulting object file is no longer executable. To make this object executable, vlink is needed.

<pre>
vlink -o <desired executable name> <existing object name> -lamiga
</pre>

In the above shell command, -lamiga refers to the ''libamiga.a'' file that vlink knows to look for in ''vlibmos:'' This file contains information used to resolve many library function names to numerical values. Note that any executable generated from the above vlink command will contain a lot of symbol information that, while potentially useful, increases the size of the executable. This can be avoided with a few additions to the above command.

<pre>
vlink -s -P__abox__ <desired executable name> <existing object name> -lamiga
</pre>

-s strip all symbols from the output file 
-P<symbol> preserve this symbol 

For more information, please refer to the documentation for vlink and other programs installed with vbcc.

An Introduction to MorphOS PPC Assembly

2010-11-29T02:10:59Z

AusPPC: /* A Little Less Talk And A Little More Action Please */

==Jump In The Deep End And Compile Something Right Now==

You could copy and paste but just entering the two lines below into a suitable text editor is probably quicker.

<pre>
.text
blr
</pre>

Save as ''shorty.s''

'''.text''' is an assembler directive - more about it later. '''blr''' is one of many branch instructions. This particular one means 'Branch to Link Register'. When a program terminates, this is the last instruction to be executed and it causes the sequence of instruction execution to pass back to the calling program or environment (shell, Ambient etc). Subroutines can also terminate with this instruction but, again, more about this later.

This is as good a time as any to ask if you've installed vbcc yet - if not, go and do it. [http://mail.pb-owl.de/~frank/vbcc/current/vbcc_bin_morphos.lha Download vbcc]

Once vbcc is installed, open a shell window and change directory to where shorty.s has been saved.

Enter:

<pre>
vasmppc_std -Felf -o ram:shorty.o shorty.s
</pre>

This tells vasm to generate an ELF formatted object file called shorty.o in ram: from the shorty.s source file.

==Hello? World's Shortest MorphOS Program - Or Is It?==

There are times when a linker is needed to further process an object file to generate an executable - this isn't one of those times.

Go ahead and enter this into the shell window:

<pre>
ram:shorty.o
</pre>

It will appear as if nothing happens - but at least it happens very quickly. However, something did happen. shorty.o was identified as an executable program and loaded into memory where the cpu instruction execution sequence passed to it. As mentioned above, the single '''blr''' instruction in this program caused the instruction execution sequence to pass directly back to where it was called from - in this case, the shell.

It may be of interest to know that all PPC instructions are four bytes long. In PPC nomenclature, this length is known as a word. But let's take a moment to have a look at the size of shorty.o

Enter this into the shell window:

<pre>
list ram:shorty.o
</pre>

2664 bytes?! But this is typical for object files as they contain much additional information that is used in the process of debugging and linking. Linking, particularly with the -s 'strip all symbols' option, will generate an executable that is noticeably smaller.

Try entering this into the shell window:

<pre>
vlink -s -o ram:shorty ram:shorty.o

list ram:shorty
</pre>

The newly generated executable is 328 bytes - much smaller than it's object file but what are those other 324 bytes doing there? They are the ELF 'container' that holds the single, four byte instruction of shorty. ELF stands for Executable and Linkable Format and it is used by MorphOS, AmigaOS4 and AROS - not to forget, Linux, UNIX, BSD and even video game consoles. There is abundant information about this file format online but this topic will be discussed a little further when the use of the objdump program is introduced.

==The Old And The New==

Generally, in order to make a program that does something useful or to at least produce an observable result, it is necessary to use operating system library functions. Despite the markedly different cpu family that MorphOS runs on compared to the 68k family used by the classic AmigaOS, MorphOS is largely compatible with AmigaOS. This compatibility is reflected in a very similar API shared with AmigaOS and extends to using a MorphOS system structure as if it were the internal data and address registers of an actual 68k processor. This is called the EmulHandle structure and it is always available through the PPC GPR2 register. Also, as with 68k AmigaOS, the address of the Exec library base is always to be found at memory location 4. Many aspects of the AmigaOS API fit closely to the features available in the 68k cpu and the following code comparison should illustrate how it is echoed in the PPC MorphOS API.

A common task performed during the initialisation of many programs - opening the Dos library. It is a particularly simple example of library usage but most functions follow this form.

[[File:Old-and-new.png]]

@ha & @l are needed to specify the high and low halfwords of 32 bit immediate values because the fixed 32 bit size of PPC instructions does not allow enough space for an instruction opcode and additional 32 bits of data.

One could be forgiven for thinking that the PPC code snippet looks a little ungainly compared to the former. Whereas every PPC instruction is four bytes long, 68k instructions can be as little as two bytes but up to as many as ten. A single 68k instruction can load a value from a 32 bit memory address specified by one instruction operand and store it at another 32 bit memory address specified by the second instruction operand. The 68k can also perform other operations beyond simple loads and stores directly on memory. Or at least appear to... In truth, computer memory only sends and receives data - no other data processing (like adding, subtracting & etc) occurs in memory. While the 68k instruction '''add.l #$12345678,(a0)''' appears to add the immediate value of it's first operand to whatever may already be stored at the address pointed to by a0, the contents of that address are actually loaded from memory into a private work register, the addition is performed and then the result is stored back to the same memory location. So this instruction actually performs two memory accesses where it might appear that there was only one. Contrast this with PPC assembly programming where memory loads and stores are all done explicitly. Before data can be operated upon it must be loaded from memory into a GPR (General Purpose Register), zero (in the case of a simple memory copy) or more operations can then be performed and then the data may be stored back to memory.

Unless you are brand-spanking-new to the topic of PPC assembly, you will already know that the PPC has 32 GPRs - r0 through r31. But did you know that the desired use of these registers is set out in something called the System V.4 ABI which MorphOS adheres to?

<pre>
r0 - volatile
r1 - stack pointer
r2 - for system use (with MorphOS, r2 points to the EmulHandle structure)

r3 - initialised with a pointer to a Dos command buffer
r4 - initialised with the length of the Dos command buffer
r5 - initialised with a pointer to an ELF structure

r3 ... r10 volatile & can be used to pass function arguments. If more
arguments are required, the stack is used.

r11 & r12 - volatile

r13 - small data area pointer. If this register is needed by a function or
subroutine, it must be saved first and then restored before
returning to where it was called from.

r14 ... r31 - No predefined purpose. If these registers are needed by a
function or subroutine, they must be saved first and then restored
before returning to where it was called from.
</pre>

The above use of the word 'volatile' means that functions are not expected to preserve the contents of these registers. r1 & r2 are the only registers that must be restored to their initial values by a terminating program, however, while most programs will modify r1 and later restore it, it is best to have not modified r2 in the first place.

This System V.4 ABI also sets out a particular way for programs and subroutines to organise their stack frames. When a program is loaded into memory and the instruction execution sequence passes to it, the stack pointer is still pointing to the calling program's stack frame and there is also an important address stored in the Link Register at this time. Unless this program is very simple (like shorty) it must save the Link Register address and, most likely, create it's own stack frame. Somewhat conveniently, there is a special position in the caller's stack frame that a callee program can save the contents of the Link Register to. This is a fairly common example of a program or subroutine's very first instructions.

[[File:Awkward-program-initialisation.png]]

Uh indeed... Let's try to visualise some memory being used as stack space.

[[File:Stack-diagram16.png]]

Note that '''stwu r1,-8(r1)''' creates a two-word stack frame which is the smallest stack that a program or subroutine can have if it, in turn, calls another program, subroutine or library function. More often, a larger stack frame is created although, '''stwu r1,-4(r1)''' could be used by a program or subroutine to create a one-word stack frame but this would be redundant and such a program must not call any other program, subroutine or library function. Such a program would not need to store the value in the Link Register (LR) to prevent it from being overwritten by subsequent calls and can terminate and return to it's caller with a simple '''blr''' instruction - just like shorty does.

A further note about larger stack frames and appropriate stack sizes: For reasons relating to PPC architecture, it is a good idea to choose stack frame sizes that are multiples of 16 bytes.

This is a less common example of a program's first instructions but it may better illustrate how to use stack frames.

[[File:Program-initialisation.png]]

Let's jump ahead and look at the last few instructions involved in program termination that would 'undo' the above instructions.

[[File:Program-termination.png]]

==A Little Less Talk And A Little More Action Please==

It's time to compile another program - this one will actually do something.

But wait...

Not another 'Hello World' program... I'm afraid so. This time, copy and paste is probably quicker. Alternatively, download this fully commented [http://aminet.net/dev/src/MorphOS-PPC-HelloWorld.lha source archive].

Note that this example does not use the MorphOS SDK. Instead, some 'quick and dirty' methods are used for the sake of simplicity and readability.

<pre>
# Various library function offsets
.set _LVOOpenLibrary,-552
.set _LVOCloseLibrary,-414
.set _LVOVPrintf,-954

.set _AbsExecBase,4

# EmulHandle structure (always pointed to by r2)
.set reg_d0,0
.set reg_d1,4
.set reg_d2,8
.set reg_d3,12
.set reg_d4,16
.set reg_d5,20
.set reg_d6,24
.set reg_d7,28
.set reg_a0,32
.set reg_a1,36
.set reg_a2,40
.set reg_a3,44
.set reg_a4,48
.set reg_a5,52
.set reg_a6,56
.set reg_a7,60
.set EmulCallDirectOS,100

# Stack frame offsets
.set stack_pos0_caller_stack,0
.set stack_pos1_callerLR,4
.set stack_pos2_ExecBase,8
.set stack_pos3_DosBase,12
.set new_4_word_stack,16

.text

mflr r0
stw r0,stack_pos1_callerLR(r1)
stwu r1,-new_4_word_stack(r1)

lis r3,dosName@ha
addi r3,r3,dosName@l
stw r3,reg_a1(r2)
li r3,0
stw r3,reg_d0(r2)
li r3,_AbsExecBase
lwz r3,0(r3)
stw r3,stack_pos2_ExecBase(r1)
stw r3,reg_a6(r2)
li r3,_LVOOpenLibrary
lwz r0,EmulCallDirectOS(r2)
mtctr r0
bctrl

cmpwi r3,0
beq exit

stw r3,stack_pos3_DosBase(r1)

lis r4,string1@ha
addi r4,r4,string1@l
stw r4,reg_d1(r2)
li r4,0
stw r4,reg_d2(r2)
stw r3,reg_a6(r2)
li r3,_LVOVPrintf
lwz r0,EmulCallDirectOS(r2)
mtctr r0
bctrl

lwz r3,stack_pos3_DosBase(r1)
stw r3,reg_a1(r2)
lwz r3,stack_pos2_ExecBase(r1)
stw r3,reg_a6(r2)
li r3,_LVOCloseLibrary
lwz r0,EmulCallDirectOS(r2)
mtctr r0
bctrl

li r3,0

exit: addi r1,r1,new_4_word_stack
lwz r0,stack_pos1_callerLR(r1)
mtlr r0
blr

.rodata
#__abox__ is a special MorphOS symbol that will differentiate
__abox__: #this program from other PPC executables that can run on MorphOS...
#When linking, care should be taken to avoid stripping this symbol.
dosName:
.string "dos.library"

string1:
.string "Hello World\n"
</pre>

Save this source file as HelloWorld.s and open a shell window. Change directory to where HelloWorld.s was just saved and enter:

<pre>
vasmppc_std -Felf -o ram:hw.o HelloWorld.s
</pre>

Once again, because of the simplicity of this program, linking isn't necessary so just enter the following in the shell window:

<pre>
ram:hw.o
</pre>

Are you impressed? Feel free to modify, experiment with and improve this source code. A not-too-difficult challenge might be to change this program so that it prints the arguments given to it in the shell window - a number of small but significant changes would be needed to do this. ''Hint: Have another look at the System V.4 register usage above.''

The commented version of HelloWorld.s in the downloadable source archive gives a brief description of why the '''mtctr''' (move to Count Register) & '''bctrl''' (branch to Count Register and link) instruction pair are used in preference to '''mtlr''' (move to Link Register) & '''blrl''' (branch to Link Register and link) - being that the latter pair can degrade performance optimisations of some PPC cpus. However, the primary use of the Count Register is as a 32 bit loop counter that can be automatically decremented by certain branch instructions.

When choosing which registers to use in your own programs, be aware that use of r0 in some instruction operands will not always work as you might expect. In these instructions, the actual content of r0 is ignored and the result is based on the constant value zero instead. For example, imagine that r0 contains the value 100 when this instruction is executed: '''addi r0,r0,50''' It looks like the result should be r0 = r0 + 50 = 150 The result will actually be r0 = 0 + 50 = 50 This may seem odd but, as long as the programmer is aware of it, this behaviour can be useful. A good PPC instruction reference manual will explain this, and many other things, in much greater detail. There are many of these reference documents available online - this is one of them: [http://www.freescale.com/files/product/doc/MPCFPE32B.pdf MPCFPE32B.pdf]

==MorphOS SDK, Objdump, ELFs & Sections==

In addition to installing vbcc, it is also recommended to install the [http://www.morphos-team.net/files/sdk-20100617.lha MorphOS SDK] and the [http://mail.pb-owl.de/~frank/vbcc/current/vbcc_target_ppc-morphos.lha vbcc MorphOS compiler target].

The installer script of the latter seems to expect that there is a pre-existing assign for include: and, if your system already assigns include: to somewhere, please skip over this next part.

What follows is my S:user-startup after the installation of vbcc, it's MorphOS compiler target and an additional assign that I made preceded by this comment -

''; vbcc MorphOS target needs include: to be assigned to somewhere''

<pre>
;
; MorphOS user-startup
;
; This script is executed on system boot by
; startup-sequence. You can make personal
; changes in here.
;
; $VER: user-startup 1.1
;

; Enable the following to mount the inet-handler. Note that TCP: allows
; easy access to internet, and allows scripts to listen for incoming
; connections. Some malware could abuse this.
;Mount TCP:
;BEGIN vbcc
assign >NIL: vbcc: mos26:vbcc
assign >NIL: C: vbcc:bin ADD
setenv VBCC vbcc:
;END vbcc

; vbcc MorphOS target needs include: to be assigned to somewhere
assign include: vbcc:targets/ppc-morphos/include

;BEGIN vbcc-ppc-morphos
assign >NIL: vincludemos: vbcc:targets/ppc-morphos/include
assign >NIL: vincludemos: include: add
assign >NIL: vlibmos: vbcc:targets/ppc-morphos/lib
;END vbcc-ppc-morphos
</pre>

At this point it would be useful to have a number of freshly generated object files and executables to look at with objdump although any ELF can be used for this purpose. Note that while MorphOS 2.x system files are compiled as ELFs, they are also signed to prevent their use on MorphOS 1.x where they may not work. This signing also has the effect of causing objdump not to recognise them as ELFs.

Objdump can be used to reveal a lot of interesting information about an ELF including listing any symbols and sections that are present as well as disassembling. Be aware that, when disassembled, seemingly small programs can produce more output than the shell window's history buffer can hold so either redirect the output to a file or specify start and stop addresses to limit the output. Having said that, none of the files generated so far in this tutorial are at risk of overwhelming the shell's history buffer when disassembled.

''more content needed here''

As mentioned just before the previous source code example, some quick and dirty methods were used for the sake of simplicity and readability and this refers to the way library function offsets were established. The approach used will quickly become detrimental as more offsets are added. There are a number of solutions to this problem but only one will be presented here and it involves the removal of the leading underscore character from function names so that, for example, '''li r3,_LVOOpenLibrary''' becomes '''li r3,LVOOpenLibrary'''. Remove or comment out the first three '''.set''' directives that define the library function offsets and assemble with vasm as before but note that the resulting object file is no longer executable. To make this object executable, vlink is needed.

<pre>
vlink -o <desired executable name> <existing object name> -lamiga
</pre>

In the above shell command, -lamiga refers to the ''libamiga.a'' file that vlink knows to look for in ''vlibmos:'' This file contains information used to resolve many library function names to numerical values. Note that any executable generated from the above vlink command will contain a lot of symbol information that, while potentially useful, increases the size of the executable. This can be avoided with a few additions to the above command.

<pre>
vlink -s -P__abox__ <desired executable name> <existing object name> -lamiga
</pre>

-s strip all symbols from the output file 
-P<symbol> preserve this symbol 

For more information, please refer to the documentation for vlink and other programs installed with vbcc.

File:Old-and-new.png

2010-11-26T21:20:10Z

AusPPC: uploaded a new version of "File:Old-and-new.png": Fixing omitted description in diagram showing commented 68k and PPC instructions

diagram showing commented 68k and PPC instructions

An Introduction to MorphOS PPC Assembly

2010-11-26T20:27:36Z

AusPPC: Fixed a mistake in the source listing & added a paragraph.

==Jump In The Deep End And Compile Something Right Now==

You could copy and paste but just entering the two lines below into a suitable text editor is probably quicker.

<pre>
.text
blr
</pre>

Save as ''shorty.s''

'''.text''' is an assembler directive - more about it later. '''blr''' is one of many branch instructions. This particular one means 'Branch to Link Register'. When a program terminates, this is the last instruction to be executed and it causes the sequence of instruction execution to pass back to the calling program or environment (shell, Ambient etc). Subroutines can also terminate with this instruction but, again, more about this later.

This is as good a time as any to ask if you've installed vbcc yet - if not, go and do it. [http://mail.pb-owl.de/~frank/vbcc/current/vbcc_bin_morphos.lha Download vbcc]

Once vbcc is installed, open a shell window and change directory to where shorty.s has been saved.

Enter:

<pre>
vasmppc_std -Felf -o ram:shorty.o shorty.s
</pre>

This tells vasm to generate an ELF formatted object file called shorty.o in ram: from the shorty.s source file.

==Hello? World's Shortest MorphOS Program - Or Is It?==

There are times when a linker is needed to further process an object file to generate an executable - this isn't one of those times.

Go ahead and enter this into the shell window:

<pre>
ram:shorty.o
</pre>

It will appear as if nothing happens - but at least it happens very quickly. However, something did happen. shorty.o was identified as an executable program and loaded into memory where the cpu instruction execution sequence passed to it. As mentioned above, the single '''blr''' instruction in this program caused the instruction execution sequence to pass directly back to where it was called from - in this case, the shell.

It may be of interest to know that all PPC instructions are four bytes long. In PPC nomenclature, this length is known as a word. But let's take a moment to have a look at the size of shorty.o

Enter this into the shell window:

<pre>
list ram:shorty.o
</pre>

2664 bytes?! But this is typical for object files as they contain much additional information that is used in the process of debugging and linking. Linking, particularly with the -s 'strip all symbols' option, will generate an executable that is noticeably smaller.

Try entering this into the shell window:

<pre>
vlink -s -o ram:shorty ram:shorty.o

list ram:shorty
</pre>

The newly generated executable is 328 bytes - much smaller than it's object file but what are those other 324 bytes doing there? They are the ELF 'container' that holds the single, four byte instruction of shorty. ELF stands for Executable and Linkable Format and it is used by MorphOS, AmigaOS4 and AROS - not to forget, Linux, UNIX, BSD and even video game consoles. There is abundant information about this file format online but this topic will be discussed a little further when the use of the objdump program is introduced.

==The Old And The New==

Generally, in order to make a program that does something useful or to at least produce an observable result, it is necessary to use operating system library functions. Despite the markedly different cpu family that MorphOS runs on compared to the 68k family used by the classic AmigaOS, MorphOS is largely compatible with AmigaOS. This compatibility is reflected in a very similar API shared with AmigaOS and extends to using a MorphOS system structure as if it were the internal data and address registers of an actual 68k processor. This is called the EmulHandle structure and it is always available through the PPC GPR2 register. Also, as with 68k AmigaOS, the address of the Exec library base is always to be found at memory location 4. Many aspects of the AmigaOS API fit closely to the features available in the 68k cpu and the following code comparison should illustrate how it is echoed in the PPC MorphOS API.

A common task performed during the initialisation of many programs - opening the Dos library. It is a particularly simple example of library usage but most functions follow this form.

[[File:Old-and-new.png]]

@ha & @l are needed to specify the high and low halfwords of 32 bit immediate values because the fixed 32 bit size of PPC instructions does not allow enough space for an instruction opcode and additional 32 bits of data.

One could be forgiven for thinking that the PPC code snippet looks a little ungainly compared to the former. Whereas every PPC instruction is four bytes long, 68k instructions can be as little as two bytes but up to as many as ten. A single 68k instruction can load a value from a 32 bit memory address specified by one instruction operand and store it at another 32 bit memory address specified by the second instruction operand. The 68k can also perform other operations beyond simple loads and stores directly on memory. Or at least appear to... In truth, computer memory only sends and receives data - no other data processing (like adding, subtracting & etc) occurs in memory. While the 68k instruction '''add.l #$12345678,(a0)''' appears to add the immediate value of it's first operand to whatever may already be stored at the address pointed to by a0, the contents of that address are actually loaded from memory into a private work register, the addition is performed and then the result is stored back to the same memory location. So this instruction actually performs two memory accesses where it might appear that there was only one. Contrast this with PPC assembly programming where memory loads and stores are all done explicitly. Before data can be operated upon it must be loaded from memory into a GPR (General Purpose Register), zero (in the case of a simple memory copy) or more operations can then be performed and then the data may be stored back to memory.

Unless you are brand-spanking-new to the topic of PPC assembly, you will already know that the PPC has 32 GPRs - r0 through r31. But did you know that the desired use of these registers is set out in something called the System V.4 ABI which MorphOS adheres to?

<pre>
r0 - volatile
r1 - stack pointer
r2 - for system use (with MorphOS, r2 points to the EmulHandle structure)

r3 - initialised with a pointer to a Dos command buffer
r4 - initialised with the length of the Dos command buffer
r5 - initialised with a pointer to an ELF structure

r3 ... r10 volatile & can be used to pass function arguments. If more
arguments are required, the stack is used.

r11 & r12 - volatile

r13 - small data area pointer. If this register is needed by a function or
subroutine, it must be saved first and then restored before
returning to where it was called from.

r14 ... r31 - No predefined purpose. If these registers are needed by a
function or subroutine, they must be saved first and then restored
before returning to where it was called from.
</pre>

The above use of the word 'volatile' means that functions are not expected to preserve the contents of these registers. r1 & r2 are the only registers that must be restored to their initial values by a terminating program, however, while most programs will modify r1 and later restore it, it is best to have not modified r2 in the first place.

This System V.4 ABI also sets out a particular way for programs and subroutines to organise their stack frames. When a program is loaded into memory and the instruction execution sequence passes to it, the stack pointer is still pointing to the calling program's stack frame and there is also an important address stored in the Link Register at this time. Unless this program is very simple (like shorty) it must save the Link Register address and, most likely, create it's own stack frame. Somewhat conveniently, there is a special position in the caller's stack frame that a callee program can save the contents of the Link Register to. This is a fairly common example of a program or subroutine's very first instructions.

[[File:Awkward-program-initialisation.png]]

Uh indeed... Let's try to visualise some memory being used as stack space.

[[File:Stack-diagram16.png]]

Note that '''stwu r1,-8(r1)''' creates a two-word stack frame which is the smallest stack that a program or subroutine can have if it, in turn, calls another program, subroutine or library function. More often, a larger stack frame is created although, '''stwu r1,-4(r1)''' could be used by a program or subroutine to create a one-word stack frame but this would be redundant and such a program must not call any other program, subroutine or library function. Such a program would not need to store the value in the Link Register (LR) to prevent it from being overwritten by subsequent calls and can terminate and return to it's caller with a simple '''blr''' instruction - just like shorty does.

A further note about larger stack frames and appropriate stack sizes: For reasons relating to PPC architecture, it is a good idea to choose stack frame sizes that are multiples of 16 bytes.

This is a less common example of a program's first instructions but it may better illustrate how to use stack frames.

[[File:Program-initialisation.png]]

Let's jump ahead and look at the last few instructions involved in program termination that would 'undo' the above instructions.

[[File:Program-termination.png]]

==A Little Less Talk And A Little More Action Please==

It's time to compile another program - this one will actually do something.

But wait...

Not another 'Hello World' program... I'm afraid so. This time, copy and paste is probably quicker. Alternatively, download this fully commented [http://aminet.net/dev/src/morphos-ppc-HelloWorld.lha source archive].

Note that this example does not use the MorphOS SDK. Instead, some 'quick and dirty' methods are used for the sake of simplicity and readability.

<pre>
# Various library function offsets
.set _LVOOpenLibrary,-552
.set _LVOCloseLibrary,-414
.set _LVOVPrintf,-954

.set _AbsExecBase,4

# EmulHandle structure (always pointed to by r2)
.set reg_d0,0
.set reg_d1,4
.set reg_d2,8
.set reg_d3,12
.set reg_d4,16
.set reg_d5,20
.set reg_d6,24
.set reg_d7,28
.set reg_a0,32
.set reg_a1,36
.set reg_a2,40
.set reg_a3,44
.set reg_a4,48
.set reg_a5,52
.set reg_a6,56
.set reg_a7,60
.set EmulCallDirectOS,100

# Stack frame offsets
.set stack_pos0_caller_stack,0
.set stack_pos1_callerLR,4
.set stack_pos2_ExecBase,8
.set stack_pos3_DosBase,12
.set new_4_word_stack,16

.text

mflr r0
stw r0,stack_pos1_callerLR(r1)
stwu r1,-new_4_word_stack(r1)

lis r3,dosName@ha
addi r3,r3,dosName@l
stw r3,reg_a1(r2)
li r3,0
stw r3,reg_d0(r2)
li r3,_AbsExecBase
lwz r3,0(r3)
stw r3,stack_pos2_ExecBase(r1)
stw r3,reg_a6(r2)
li r3,_LVOOpenLibrary
lwz r0,EmulCallDirectOS(r2)
mtctr r0
bctrl

cmpwi r3,0
beq exit

stw r3,stack_pos3_DosBase(r1)

lis r4,string1@ha
addi r4,r4,string1@l
stw r4,reg_d1(r2)
li r4,0
stw r4,reg_d2(r2)
stw r3,reg_a6(r2)
li r3,_LVOVPrintf
lwz r0,EmulCallDirectOS(r2)
mtctr r0
bctrl

lwz r3,stack_pos3_DosBase(r1)
stw r3,reg_a1(r2)
lwz r3,stack_pos2_ExecBase(r1)
stw r3,reg_a6(r2)
li r3,_LVOCloseLibrary
lwz r0,EmulCallDirectOS(r2)
mtctr r0
bctrl

li r3,0

exit: addi r1,r1,new_4_word_stack
lwz r0,stack_pos1_callerLR(r1)
mtlr r0
blr

.rodata
#__abox__ is a special MorphOS symbol that will differentiate
__abox__: #this program from other PPC executables that can run on MorphOS...
#When linking, care should be taken to avoid stripping this symbol.
dosName:
.string "dos.library"

string1:
.string "Hello World\n"
</pre>

Save this source file as HelloWorld.s and open a shell window. Change directory to where HelloWorld.s was just saved and enter:

<pre>
vasmppc_std -Felf -o ram:hw.o HelloWorld.s
</pre>

Once again, because of the simplicity of this program, linking isn't necessary so just enter the following in the shell window:

<pre>
ram:hw.o
</pre>

Are you impressed? Feel free to modify, experiment with and improve this source code. A not-too-difficult challenge might be to change this program so that it prints the arguments given to it in the shell window - a number of small but significant changes would be needed to do this. ''Hint: Have another look at the System V.4 register usage above.''

The commented version of HelloWorld.s in the downloadable source archive gives a brief description of why the '''mtctr''' (move to Count Register) & '''bctrl''' (branch to Count Register and link) instruction pair are used in preference to '''mtlr''' (move to Link Register) & '''blrl''' (branch to Link Register and link) - being that the latter pair can degrade performance optimisations of some PPC cpus. However, the primary use of the Count Register is as a 32 bit loop counter that can be automatically decremented by certain branch instructions.

When choosing which registers to use in your own programs, be aware that use of r0 in some instruction operands will not always work as you might expect. In these instructions, the actual content of r0 is ignored and the result is based on the constant value zero instead. For example, imagine that r0 contains the value 100 when this instruction is executed: '''addi r0,r0,50''' It looks like the result should be r0 = r0 + 50 = 150 The result will actually be r0 = 0 + 50 = 50 This may seem odd but, as long as the programmer is aware of it, this behaviour can be useful. A good PPC instruction reference manual will explain this, and many other things, in much greater detail. There are many of these reference documents available online - this is one of them: [http://www.freescale.com/files/product/doc/MPCFPE32B.pdf MPCFPE32B.pdf]

==MorphOS SDK, Objdump, ELFs & Sections==

In addition to installing vbcc, it is also recommended to install the [http://www.morphos-team.net/files/sdk-20100617.lha MorphOS SDK] and the [http://mail.pb-owl.de/~frank/vbcc/current/vbcc_target_ppc-morphos.lha vbcc MorphOS compiler target].

The installer script of the latter seems to expect that there is a pre-existing assign for include: and, if your system already assigns include: to somewhere, please skip over this next part.

What follows is my S:user-startup after the installation of vbcc, it's MorphOS compiler target and an additional assign that I made preceded by this comment -

''; vbcc MorphOS target needs include: to be assigned to somewhere''

<pre>
;
; MorphOS user-startup
;
; This script is executed on system boot by
; startup-sequence. You can make personal
; changes in here.
;
; $VER: user-startup 1.1
;

; Enable the following to mount the inet-handler. Note that TCP: allows
; easy access to internet, and allows scripts to listen for incoming
; connections. Some malware could abuse this.
;Mount TCP:
;BEGIN vbcc
assign >NIL: vbcc: mos26:vbcc
assign >NIL: C: vbcc:bin ADD
setenv VBCC vbcc:
;END vbcc

; vbcc MorphOS target needs include: to be assigned to somewhere
assign include: vbcc:targets/ppc-morphos/include

;BEGIN vbcc-ppc-morphos
assign >NIL: vincludemos: vbcc:targets/ppc-morphos/include
assign >NIL: vincludemos: include: add
assign >NIL: vlibmos: vbcc:targets/ppc-morphos/lib
;END vbcc-ppc-morphos
</pre>

At this point it would be useful to have a number of freshly generated object files and executables to look at with objdump although any ELF can be used for this purpose. Note that while MorphOS 2.x system files are compiled as ELFs, they are also signed to prevent their use on MorphOS 1.x where they may not work. This signing also has the effect of causing objdump not to recognise them as ELFs.

Objdump can be used to reveal a lot of interesting information about an ELF including listing any symbols and sections that are present as well as disassembling. Be aware that, when disassembled, seemingly small programs can produce more output than the shell window's history buffer can hold so either redirect the output to a file or specify start and stop addresses to limit the output. Having said that, none of the files generated so far in this tutorial are at risk of overwhelming the shell's history buffer when disassembled.

''more content needed here''

As mentioned just before the previous source code example, some quick and dirty methods were used for the sake of simplicity and readability and this refers to the way library function offsets were established. The approach used will quickly become detrimental as more offsets are added. There are a number of solutions to this problem but only one will be presented here and it involves the removal of the leading underscore character from function names so that, for example, '''li r3,_LVOOpenLibrary''' becomes '''li r3,LVOOpenLibrary'''. Remove or comment out the first three '''.set''' directives that define the library function offsets and assemble with vasm as before but note that the resulting object file is no longer executable. To make this object executable, vlink is needed.

<pre>
vlink -o <desired executable name> <existing object name> -lamiga
</pre>

In the above shell command, -lamiga refers to the ''libamiga.a'' file that vlink knows to look for in ''vlibmos:'' This file contains information used to resolve many library function names to numerical values. Note that any executable generated from the above vlink command will contain a lot of symbol information that, while potentially useful, increases the size of the executable. This can be avoided with a few additions to the above command.

<pre>
vlink -s -P__abox__ <desired executable name> <existing object name> -lamiga
</pre>

-s strip all symbols from the output file 
-P<symbol> preserve this symbol 

For more information, please refer to the documentation for vlink and other programs installed with vbcc.

An Introduction to MorphOS PPC Assembly

2010-11-26T05:05:41Z

AusPPC: Reorganising and adding content.

==Jump In The Deep End And Compile Something Right Now==

You could copy and paste but just entering the two lines below into a suitable text editor is probably quicker.

<pre>
.text
blr
</pre>

Save as ''shorty.s''

'''.text''' is an assembler directive - more about it later. '''blr''' is one of many branch instructions. This particular one means 'Branch to Link Register'. When a program terminates, this is the last instruction to be executed and it causes the sequence of instruction execution to pass back to the calling program or environment (shell, Ambient etc). Subroutines can also terminate with this instruction but, again, more about this later.

This is as good a time as any to ask if you've installed vbcc yet - if not, go and do it. [http://mail.pb-owl.de/~frank/vbcc/current/vbcc_bin_morphos.lha Download vbcc]

Once vbcc is installed, open a shell window and change directory to where shorty.s has been saved.

Enter:

<pre>
vasmppc_std -Felf -o ram:shorty.o shorty.s
</pre>

This tells vasm to generate an ELF formatted object file called shorty.o in ram: from the shorty.s source file.

==Hello? World's Shortest MorphOS Program - Or Is It?==

There are times when a linker is needed to further process an object file to generate an executable - this isn't one of those times.

Go ahead and enter this into the shell window:

<pre>
ram:shorty.o
</pre>

It will appear as if nothing happens - but at least it happens very quickly. However, something did happen. shorty.o was identified as an executable program and loaded into memory where the cpu instruction execution sequence passed to it. As mentioned above, the single '''blr''' instruction in this program caused the instruction execution sequence to pass directly back to where it was called from - in this case, the shell.

It may be of interest to know that all PPC instructions are four bytes long. In PPC nomenclature, this length is known as a word. But let's take a moment to have a look at the size of shorty.o

Enter this into the shell window:

<pre>
list ram:shorty.o
</pre>

2664 bytes?! But this is typical for object files as they contain much additional information that is used in the process of debugging and linking. Linking, particularly with the -s 'strip all symbols' option, will generate an executable that is noticeably smaller.

Try entering this into the shell window:

<pre>
vlink -s -o ram:shorty ram:shorty.o

list ram:shorty
</pre>

The newly generated executable is 328 bytes - much smaller than it's object file but what are those other 324 bytes doing there? They are the ELF 'container' that holds the single, four byte instruction of shorty. ELF stands for Executable and Linkable Format and it is used by MorphOS, AmigaOS4 and AROS - not to forget, Linux, UNIX, BSD and even video game consoles. There is abundant information about this file format online but this topic will be discussed a little further when the use of the objdump program is introduced.

==The Old And The New==

Generally, in order to make a program that does something useful or to at least produce an observable result, it is necessary to use operating system library functions. Despite the markedly different cpu family that MorphOS runs on compared to the 68k family used by the classic AmigaOS, MorphOS is largely compatible with AmigaOS. This compatibility is reflected in a very similar API shared with AmigaOS and extends to using a MorphOS system structure as if it were the internal data and address registers of an actual 68k processor. This is called the EmulHandle structure and it is always available through the PPC GPR2 register. Also, as with 68k AmigaOS, the address of the Exec library base is always to be found at memory location 4. Many aspects of the AmigaOS API fit closely to the features available in the 68k cpu and the following code comparison should illustrate how it is echoed in the PPC MorphOS API.

A common task performed during the initialisation of many programs - opening the Dos library. It is a particularly simple example of library usage but most functions follow this form.

[[File:Old-and-new.png]]

@ha & @l are needed to specify the high and low halfwords of 32 bit immediate values because the fixed 32 bit size of PPC instructions does not allow enough space for an instruction opcode and additional 32 bits of data.

One could be forgiven for thinking that the PPC code snippet looks a little ungainly compared to the former. Whereas every PPC instruction is four bytes long, 68k instructions can be as little as two bytes but up to as many as ten. A single 68k instruction can load a value from a 32 bit memory address specified by one instruction operand and store it at another 32 bit memory address specified by the second instruction operand. The 68k can also perform other operations beyond simple loads and stores directly on memory. Or at least appear to... In truth, computer memory only sends and receives data - no other data processing (like adding, subtracting & etc) occurs in memory. While the 68k instruction '''add.l #$12345678,(a0)''' appears to add the immediate value of it's first operand to whatever may already be stored at the address pointed to by a0, the contents of that address are actually loaded from memory into a private work register, the addition is performed and then the result is stored back to the same memory location. So this instruction actually performs two memory accesses where it might appear that there was only one. Contrast this with PPC assembly programming where memory loads and stores are all done explicitly. Before data can be operated upon it must be loaded from memory into a GPR (General Purpose Register), zero (in the case of a simple memory copy) or more operations can then be performed and then the data may be stored back to memory.

Unless you are brand-spanking-new to the topic of PPC assembly, you will already know that the PPC has 32 GPRs - r0 through r31. But did you know that the desired use of these registers is set out in something called the System V.4 ABI which MorphOS adheres to?

<pre>
r0 - volatile
r1 - stack pointer
r2 - for system use (with MorphOS, r2 points to the EmulHandle structure)

r3 - initialised with a pointer to a Dos command buffer
r4 - initialised with the length of the Dos command buffer
r5 - initialised with a pointer to an ELF structure

r3 ... r10 volatile & can be used to pass function arguments. If more
arguments are required, the stack is used.

r11 & r12 - volatile

r13 - small data area pointer. If this register is needed by a function or
subroutine, it must be saved first and then restored before
returning to where it was called from.

r14 ... r31 - No predefined purpose. If these registers are needed by a
function or subroutine, they must be saved first and then restored
before returning to where it was called from.
</pre>

The above use of the word 'volatile' means that functions are not expected to preserve the contents of these registers. r1 & r2 are the only registers that must be restored to their initial values by a terminating program, however, while most programs will modify r1 and later restore it, it is best to have not modified r2 in the first place.

This System V.4 ABI also sets out a particular way for programs and subroutines to organise their stack frames. When a program is loaded into memory and the instruction execution sequence passes to it, the stack pointer is still pointing to the calling program's stack frame and there is also an important address stored in the Link Register at this time. Unless this program is very simple (like shorty) it must save the Link Register address and, most likely, create it's own stack frame. Somewhat conveniently, there is a special position in the caller's stack frame that a callee program can save the contents of the Link Register to. This is a fairly common example of a program or subroutine's very first instructions.

[[File:Awkward-program-initialisation.png]]

Uh indeed... Let's try to visualise some memory being used as stack space.

[[File:Stack-diagram16.png]]

Note that '''stwu r1,-8(r1)''' creates a two-word stack frame which is the smallest stack that a program or subroutine can have if it, in turn, calls another program, subroutine or library function. More often, a larger stack frame is created although, '''stwu r1,-4(r1)''' could be used by a program or subroutine to create a one-word stack frame but this would be redundant and such a program must not call any other program, subroutine or library function. Such a program would not need to store the value in the Link Register (LR) to prevent it from being overwritten by subsequent calls and can terminate and return to it's caller with a simple '''blr''' instruction - just like shorty does.

A further note about larger stack frames and appropriate stack sizes: For reasons relating to PPC architecture, it is a good idea to choose stack frame sizes that are multiples of 16 bytes.

This is a less common example of a program's first instructions but it may better illustrate how to use stack frames.

[[File:Program-initialisation.png]]

Let's jump ahead and look at the last few instructions involved in program termination that would 'undo' the above instructions.

[[File:Program-termination.png]]

==A Little Less Talk And A Little More Action Please==

It's time to compile another program - this one will actually do something.

But wait...

Not another 'Hello World' program... I'm afraid so. This time, copy and paste is probably quicker. Alternatively, download this fully commented [http://aminet.net/dev/src/morphos-ppc-HelloWorld.lha source archive].

Note that this example does not use the MorphOS SDK. Instead, some 'quick and dirty' methods are used for the sake of simplicity and readability.

<pre>
# Various library function offsets
.set _LVOOpenLibrary,-552
.set _LVOCloseLibrary,-414
.set _LVOVPrintf,-954

.set _AbsExecBase,4

# EmulHandle structure (always pointed to by r2)
.set reg_d0,0
.set reg_d1,4
.set reg_d2,8
.set reg_d3,12
.set reg_d4,16
.set reg_d5,20
.set reg_d6,24
.set reg_d7,28
.set reg_a0,32
.set reg_a1,36
.set reg_a2,40
.set reg_a3,44
.set reg_a4,48
.set reg_a5,52
.set reg_a6,56
.set reg_a7,60
.set EmulCallDirectOS,100

# Stack frame offsets
.set stack_pos0_caller_stack,0
.set stack_pos1_callerLR,4
.set stack_pos2_ExecBase,8
.set stack_pos3_DosBase,12
.set new_4_word_stack,16

.text

mflr r0
stw r0,stack_pos1_callerLR(r1)
stwu r1,-new_4_word_stack(r1)

lis r3,dosName@ha
addi r3,r3,dosName@l
stw r3,reg_a1(r2)
li r3,0
stw r3,reg_d0(r2)
li r3,_AbsExecBase
lwz r3,0(r3)
stw r3,stack_pos2_ExecBase(r1)
stw r3,reg_a6(r2)
li r3,_LVOOpenLibrary
lwz r0,EmulCallDirectOS(r2)
mtctr r0
bctrl

cmpwi r3,0
beq exit

stw r3,stack_pos3_DosBase(r1)

lis r4,string1@ha
addi r4,r4,string1@l
stw r4,reg_d1(r2)
li r4,0
stw r4,reg_d2(r2)
stw r3,reg_a6(r2)
li r3,_LVOVPrintf
lwz r0,EmulCallDirectOS(r2)
mtctr r0
bctrl

lwz r3,stack_pos3_DosBase(r1)
stw r3,reg_a1(r2)
lwz r3,stack_pos2_ExecBase(r1)
stw r3,reg_a6(r2)
li r3,_LVOCloseLibrary
lwz r0,EmulCallDirectOS(r2)
mtctr r0
bctrl

li r3,0

exit: addi r1,r1,new_4_word_stack
lwz r0,stack_pos1_callerLR(r1)
mtlr r0
blr

.rodata

__abox__:

dosName:
.string dos.library

string1:
.string "Hello World\n"
</pre>

Save this source file as HelloWorld.s and open a shell window. Change directory to where HelloWorld.s was just saved and enter:

<pre>
vasmppc_std -Felf -o ram:hw.o HelloWorld.s
</pre>

Once again, because of the simplicity of this program, linking isn't necessary so just enter the following in the shell window:

<pre>
ram:hw.o
</pre>

Are you impressed? Feel free to modify, experiment with and improve this source code. A not-too-difficult challenge might be to change this program so that it prints the arguments given to it in the shell window - a number of small but significant changes would be needed to do this. ''Hint: Have another look at the System V.4 register usage above.''

When choosing which registers to use in your own programs, be aware that use of r0 in some instruction operands will not always work as you might expect. In these instructions, the actual content of r0 is ignored and the result is based on the constant value zero instead. For example, imagine that r0 contains the value 100 when this instruction is executed: '''addi r0,r0,50''' It looks like the result should be r0 = r0 + 50 = 150 The result will actually be r0 = 0 + 50 = 50 This may seem odd but, as long as the programmer is aware of it, this behaviour can be useful. A good PPC instruction reference manual will explain this, and many other things, in much greater detail. There are many of these reference documents available online - this is one of them [http://www.freescale.com/files/product/doc/MPCFPE32B.pdf MPCFPE32B.pdf]

==MorphOS SDK, Objdump, ELFs & Sections==

In addition to installing vbcc, it is also recommended to install the [http://www.morphos-team.net/files/sdk-20100617.lha MorphOS SDK] and the [http://mail.pb-owl.de/~frank/vbcc/current/vbcc_target_ppc-morphos.lha vbcc MorphOS compiler target].

The installer script of the latter seems to expect that there is a pre-existing assign for include: and, if your system already assigns include: to somewhere, please skip over this next part.

What follows is my S:user-startup after the installation of vbcc, it's MorphOS compiler target and an additional assign that I made preceded by this comment -

''; vbcc MorphOS target needs include: to be assigned to somewhere''

<pre>
;
; MorphOS user-startup
;
; This script is executed on system boot by
; startup-sequence. You can make personal
; changes in here.
;
; $VER: user-startup 1.1
;

; Enable the following to mount the inet-handler. Note that TCP: allows
; easy access to internet, and allows scripts to listen for incoming
; connections. Some malware could abuse this.
;Mount TCP:
;BEGIN vbcc
assign >NIL: vbcc: mos26:vbcc
assign >NIL: C: vbcc:bin ADD
setenv VBCC vbcc:
;END vbcc

; vbcc MorphOS target needs include: to be assigned to somewhere
assign include: vbcc:targets/ppc-morphos/include

;BEGIN vbcc-ppc-morphos
assign >NIL: vincludemos: vbcc:targets/ppc-morphos/include
assign >NIL: vincludemos: include: add
assign >NIL: vlibmos: vbcc:targets/ppc-morphos/lib
;END vbcc-ppc-morphos
</pre>

At this point it would be useful to have a number of freshly generated object files and executables to look at with objdump although any ELF can be used for this purpose. Note that while MorphOS 2.x system files are compiled as ELFs, they are also signed to prevent their use on MorphOS 1.x where they may not work. This signing also has the effect of causing objdump not to recognise them as ELFs.

Objdump can be used to reveal a lot of interesting information about an ELF including listing any symbols and sections that are present as well as disassembling. Be aware that, when disassembled, seemingly small programs can produce more output than the shell window's history buffer can hold so either redirect the output to a file or specify start and stop addresses to limit the output. Having said that, none of the files generated so far in this tutorial are at risk of overwhelming the shell's history buffer when disassembled.

''more content needed here''

As mentioned just before the previous source code example, some quick and dirty methods were used for the sake of simplicity and readability and this refers to the way library function offsets were established. The approach used will quickly become detrimental as more offsets are added. There are a number of solutions to this problem but only one will be presented here and it involves the removal of the leading underscore character from function names so that, for example, '''li r3,_LVOOpenLibrary''' becomes '''li r3,LVOOpenLibrary'''. Remove or comment out the first three '''.set''' directives that define the library function offsets and assemble with vasm as before but note that the resulting object file is no longer executable. To make this object executable, vlink is needed.

<pre>
vlink -o <desired executable name> <existing object name> -lamiga
</pre>

In the above shell command, -lamiga refers to the ''libamiga.a'' file that vlink knows to look for in ''vlibmos:'' This file contains information used to resolve many library function names to numerical values. Note that any executable generated from the above vlink command will contain a lot of symbol information that, while potentially useful, increases the size of the executable. This can be avoided with a few additions to the above command.

<pre>
vlink -s -P__abox__ <desired executable name> <existing object name> -lamiga
</pre>

-s strip all symbols from the output file 
-P<symbol> preserve this symbol 

For more information, please refer to the documentation for vlink and other programs installed with vbcc.

An Introduction to MorphOS PPC Assembly

2010-11-26T04:48:58Z

AusPPC: Minor additions and other small edits.

==Jump In The Deep End And Compile Something Right Now==

You could copy and paste but just entering the two lines below into a suitable text editor is probably quicker.

<pre>
.text
blr
</pre>

Save as ''shorty.s''

'''.text''' is an assembler directive - more about it later. '''blr''' is one of many branch instructions. This particular one means 'Branch to Link Register'. When a program terminates, this is the last instruction to be executed and it causes the sequence of instruction execution to pass back to the calling program or environment (shell, Ambient etc). Subroutines can also terminate with this instruction but, again, more about this later.

This is as good a time as any to ask if you've installed vbcc yet - if not, go and do it. [http://mail.pb-owl.de/~frank/vbcc/current/vbcc_bin_morphos.lha Download vbcc]

Once vbcc is installed, open a shell window and change directory to where shorty.s has been saved.

Enter:

<pre>
vasmppc_std -Felf -o ram:shorty.o shorty.s
</pre>

This tells vasm to generate an ELF formatted object file called shorty.o in ram: from the shorty.s source file.

==Hello? World's Shortest MorphOS Program - Or Is It?==

There are times when a linker is needed to further process an object file to generate an executable - this isn't one of those times.

Go ahead and enter this into the shell window:

<pre>
ram:shorty.o
</pre>

It will appear as if nothing happens - but at least it happens very quickly. However, something did happen. shorty.o was identified as an executable program and loaded into memory where the cpu instruction execution sequence passed to it. As mentioned above, the single '''blr''' instruction in this program caused the instruction execution sequence to pass directly back to where it was called from - in this case, the shell.

It may be of interest to know that all PPC instructions are four bytes long. In PPC nomenclature, this length is known as a word. But let's take a moment to have a look at the size of shorty.o

Enter this into the shell window:

<pre>
list ram:shorty.o
</pre>

2664 bytes?! But this is typical for object files as they contain much additional information that is used in the process of debugging and linking. Linking, particularly with the -s 'strip all symbols' option, will generate an executable that is noticeably smaller.

Try entering this into the shell window:

<pre>
vlink -s -o ram:shorty ram:shorty.o

list ram:shorty
</pre>

The newly generated executable is 328 bytes - much smaller than it's object file but what are those other 324 bytes doing there? They are the ELF 'container' that holds the single, four byte instruction of shorty. ELF stands for Executable and Linkable Format and it is used by MorphOS, AmigaOS4 and AROS - not to forget, Linux, UNIX, BSD and even video game consoles. There is abundant information about this file format online but this topic will be discussed a little further when the use of the objdump program is introduced.

==The Old And The New==

Generally, in order to make a program that does something useful or to at least produce an observable result, it is necessary to use operating system library functions. Despite the markedly different cpu family that MorphOS runs on compared to the 68k family used by the classic AmigaOS, MorphOS is largely compatible with AmigaOS. This compatibility is reflected in a very similar API shared with AmigaOS and extends to using a MorphOS system structure as if it were the internal data and address registers of an actual 68k processor. This is called the EmulHandle structure and it is always available through the PPC GPR2 register. Also, as with 68k AmigaOS, the address of the Exec library base is always to be found at memory location 4. Many aspects of the AmigaOS API fit closely to the features available in the 68k cpu and the following code comparison should illustrate how it is echoed in the PPC MorphOS API.

A common task performed during the initialisation of many programs - opening the Dos library. It is a particularly simple example of library usage but most functions follow this form.

[[File:Old-and-new.png]]

@ha & @l are needed to specify the high and low halfwords of 32 bit immediate values because the fixed 32 bit size of PPC instructions does not allow enough space for an instruction opcode and additional 32 bits of data.

One could be forgiven for thinking that the PPC code snippet looks a little ungainly compared to the former. Whereas every PPC instruction is four bytes long, 68k instructions can be as little as two bytes but up to as many as ten. A single 68k instruction can load a value from a 32 bit memory address specified by one instruction operand and store it at another 32 bit memory address specified by the second instruction operand. The 68k can also perform other operations beyond simple loads and stores directly on memory. Or at least appear to... In truth, computer memory only sends and receives data - no other data processing (like adding, subtracting & etc) occurs in memory. While the 68k instruction '''add.l #$12345678,(a0)''' appears to add the immediate value of it's first operand to whatever may already be stored at the address pointed to by a0, the contents of that address are actually loaded from memory into a private work register, the addition is performed and then the result is stored back to the same memory location. So this instruction actually performs two memory accesses where it might appear that there was only one. Contrast this with PPC assembly programming where memory loads and stores are all done explicitly. Before data can be operated upon it must be loaded from memory into a GPR (General Purpose Register), zero (in the case of a simple memory copy) or more operations can then be performed and then the data may be stored back to memory.

Unless you are brand-spanking-new to the topic of PPC assembly, you will already know that the PPC has 32 GPRs - r0 through r31. But did you know that the desired use of these registers is set out in something called the System V.4 ABI which MorphOS adheres to?

<pre>
r0 - volatile
r1 - stack pointer
r2 - for system use (with MorphOS, r2 points to the EmulHandle structure)

r3 - initialised with a pointer to a Dos command buffer
r4 - initialised with the length of the Dos command buffer
r5 - initialised with a pointer to an ELF structure

r3 ... r10 volatile & can be used to pass function arguments. If more
arguments are required, the stack is used.

r11 & r12 - volatile

r13 - small data area pointer. If this register is needed by a function or
subroutine, it must be saved first and then restored before
returning to where it was called from.

r14 ... r31 - No predefined purpose. If these registers are needed by a
function or subroutine, they must be saved first and then restored
before returning to where it was called from.
</pre>

The above use of the word 'volatile' means that functions are not expected to preserve the contents of these registers. r1 & r2 are the only registers that must be restored to their initial values by a terminating program, however, while most programs will modify r1 and later restore it, it is best to have not modified r2 in the first place.

This System V.4 ABI also sets out a particular way for programs and subroutines to organise their stack frames. When a program is loaded into memory and the instruction execution sequence passes to it, the stack pointer is still pointing to the calling program's stack frame and there is also an important address stored in the Link Register at this time. Unless this program is very simple (like shorty) it must save the Link Register address and, most likely, create it's own stack frame. Somewhat conveniently, there is a special position in the caller's stack frame that a callee program can save the contents of the Link Register to. This is a fairly common example of a program or subroutine's very first instructions.

[[File:Awkward-program-initialisation.png]]

Uh indeed... Let's try to visualise some memory being used as stack space.

[[File:Stack-diagram16.png]]

Note that '''stwu r1,-8(r1)''' creates a two-word stack frame which is the smallest stack that a program or subroutine can have if it, in turn, calls another program, subroutine or library function. More often, a larger stack frame is created although, '''stwu r1,-4(r1)''' could be used by a program or subroutine to create a one-word stack frame but this would be redundant and such a program must not call any other program, subroutine or library function. Such a program would not need to store the value in the Link Register (LR) to prevent it from being overwritten by subsequent calls and can terminate and return to it's caller with a simple '''blr''' instruction - just like shorty does.

A further note about larger stack frames and appropriate stack sizes: For reasons relating to PPC architecture, it is a good idea to choose stack frame sizes that are multiples of 16 bytes.

This is a less common example of a program's first instructions but it may better illustrate how to use stack frames.

[[File:Program-initialisation.png]]

Let's jump ahead and look at the last few instructions involved in program termination that would 'undo' the above instructions.

[[File:Program-termination.png]]

==A Little Less Talk And A Little More Action Please==

It's time to compile another program - this one will actually do something.

But wait...

Not another 'Hello World' program... I'm afraid so. This time, copy and paste is probably quicker. Alternatively, download this fully commented [http://aminet.net/dev/src/morphos-ppc-HelloWorld.lha source archive].

Note that this example does not use the MorphOS SDK. Instead, some 'quick and dirty' methods are used for the sake of simplicity and readability.

<pre>
# Various library function offsets
.set _LVOOpenLibrary,-552
.set _LVOCloseLibrary,-414
.set _LVOVPrintf,-954

.set _AbsExecBase,4

# EmulHandle structure (always pointed to by r2)
.set reg_d0,0
.set reg_d1,4
.set reg_d2,8
.set reg_d3,12
.set reg_d4,16
.set reg_d5,20
.set reg_d6,24
.set reg_d7,28
.set reg_a0,32
.set reg_a1,36
.set reg_a2,40
.set reg_a3,44
.set reg_a4,48
.set reg_a5,52
.set reg_a6,56
.set reg_a7,60
.set EmulCallDirectOS,100

# Stack frame offsets
.set stack_pos0_caller_stack,0
.set stack_pos1_callerLR,4
.set stack_pos2_ExecBase,8
.set stack_pos3_DosBase,12
.set new_4_word_stack,16

.text

mflr r0
stw r0,stack_pos1_callerLR(r1)
stwu r1,-new_4_word_stack(r1)

lis r3,dosName@ha
addi r3,r3,dosName@l
stw r3,reg_a1(r2)
li r3,0
stw r3,reg_d0(r2)
li r3,_AbsExecBase
lwz r3,0(r3)
stw r3,stack_pos2_ExecBase(r1)
stw r3,reg_a6(r2)
li r3,_LVOOpenLibrary
lwz r0,EmulCallDirectOS(r2)
mtctr r0
bctrl

cmpwi r3,0
beq exit

stw r3,stack_pos3_DosBase(r1)

lis r4,string1@ha
addi r4,r4,string1@l
stw r4,reg_d1(r2)
li r4,0
stw r4,reg_d2(r2)
stw r3,reg_a6(r2)
li r3,_LVOVPrintf
lwz r0,EmulCallDirectOS(r2)
mtctr r0
bctrl

lwz r3,stack_pos3_DosBase(r1)
stw r3,reg_a1(r2)
lwz r3,stack_pos2_ExecBase(r1)
stw r3,reg_a6(r2)
li r3,_LVOCloseLibrary
lwz r0,EmulCallDirectOS(r2)
mtctr r0
bctrl

li r3,0

exit: addi r1,r1,new_4_word_stack
lwz r0,stack_pos1_callerLR(r1)
mtlr r0
blr

.rodata

__abox__:

dosName:
.string dos.library

string1:
.string "Hello World\n"
</pre>

Save this source file as HelloWorld.s and open a shell window. Change directory to where HelloWorld.s was just saved and enter:

<pre>
vasmppc_std -Felf -o ram:hw.o HelloWorld.s
</pre>

Once again, because of the simplicity of this program, linking isn't necessary so just enter the following in the shell window:

<pre>
ram:hw.o
</pre>

Are you impressed? Feel free to modify, experiment with and improve this source code. A not-too-difficult challenge might be to change this program so that it prints the arguments given to it in the shell window - a number of small but significant changes would be needed to do this. ''Hint: Have another look at the System V.4 register usage above.''

When choosing which registers to use in your own programs, be aware that use of r0 in some instruction operands will not always work as you might expect. In these instructions, the actual content of r0 is ignored and the result is based on the constant value zero instead. For example, imagine that r0 contains the value 100 when this instruction is executed: '''addi r0,r0,50''' It looks like the result should be r0 = r0 + 50 = 150 The result will actually be r0 = 0 + 50 = 50 This may seem odd but, as long as the programmer is aware of it, this behaviour can be useful. A good PPC instruction reference manual will explain this, and many other things, in much greater detail. There are many of these reference documents available online - this is one of them [http://www.freescale.com/files/product/doc/MPCFPE32B.pdf MPCFPE32B.pdf]

==MorphOS SDK, Objdump, ELFs & Sections==

In addition to installing vbcc, it is also recommended to install the [http://www.morphos-team.net/files/sdk-20100617.lha MorphOS SDK] and the [http://mail.pb-owl.de/~frank/vbcc/current/vbcc_target_ppc-morphos.lha vbcc MorphOS compiler target].

The installer script of the latter seems to expect that there is a pre-existing assign for include: and, if your system already assigns include: to somewhere, please skip over this next part.

What follows is my S:user-startup after the installation of vbcc, it's MorphOS compiler target and an additional assign that I made preceded by this comment -

;vbcc MorphOS target needs include: to be assigned to somewhere

<pre>
;
; MorphOS user-startup
;
; This script is executed on system boot by
; startup-sequence. You can make personal
; changes in here.
;
; $VER: user-startup 1.1
;

; Enable the following to mount the inet-handler. Note that TCP: allows
; easy access to internet, and allows scripts to listen for incoming
; connections. Some malware could abuse this.
;Mount TCP:
;BEGIN vbcc
assign >NIL: vbcc: mos26:vbcc
assign >NIL: C: vbcc:bin ADD
setenv VBCC vbcc:
;END vbcc

;vbcc MorphOS target needs include: to be assigned to somewhere
assign include: vbcc:targets/ppc-morphos/include

;BEGIN vbcc-ppc-morphos
assign >NIL: vincludemos: vbcc:targets/ppc-morphos/include
assign >NIL: vincludemos: include: add
assign >NIL: vlibmos: vbcc:targets/ppc-morphos/lib
;END vbcc-ppc-morphos
</pre>

As mentioned just before the previous source code example, some quick and dirty methods were used for the sake of simplicity and readability and this refers to the way library function offsets were established. This approach will quickly become detrimental as more offsets are added. There are a number of solutions to this problem but only one will be presented here and it involves the removal of the leading underscore character from function names and appending '@l' to the end so that, for example, '''li r3,_LVOOpenLibrary''' becomes '''li r3,LVOOpenLibrary@l'''. Assemble with vasm as before but note that the resulting object file is no longer executable. To make this object executable, vlink is needed.

<pre>
vlink -b elf32morphos -o <desired executable name> <existing object name> -lamiga
</pre>

In the above shell command, -lamiga refers to the libamiga.a file that vlink knows to look for in vlibmos: This file contains information used to resolve many library function names to numerical values. Note that any executable generated from the above vlink command will contain a lot of symbol information that, while potentially useful, increases the size of the executable. This can be avoided with a few additions to the above command.

<pre>
vlink -b elf32morphos -s -x -P__abox__ <desired executable name> <existing object name> -lamiga
</pre>

-s strip symbols from the output file 
-x discard local symbols from input file(s) 
-P<symbol> preserve this symbol 

For more information, please refer to the documentation for vlink and other programs installed with vbcc.

At this point it would be useful to have a number of freshly generated object files and executables to look at with objdump although any ELF can be used for this purpose.

''final part yet to come''

An Introduction to MorphOS PPC Assembly

2010-11-26T04:35:58Z

AusPPC: Very minor edit.

==Jump In The Deep End And Compile Something Right Now==

You could copy and paste but just entering the two lines below into a suitable text editor is probably quicker.

<pre>
.text
blr
</pre>

Save as ''shorty.s''

'''.text''' is an assembler directive - more about it later. '''blr''' is one of many branch instructions. This particular one means 'Branch to Link Register'. When a program terminates, this is the last instruction to be executed and it causes the sequence of instruction execution to pass back to the calling program or environment (shell, Ambient etc). Subroutines can also terminate with this instruction but, again, more about this later.

This is as good a time as any to ask if you've installed vbcc yet - if not, go and do it. [http://mail.pb-owl.de/~frank/vbcc/current/vbcc_bin_morphos.lha Download vbcc]

Once vbcc is installed, open a shell window and change directory to where shorty.s has been saved.

Enter:

<pre>
vasmppc_std -Felf -o ram:shorty.o shorty.s
</pre>

This tells vasm to generate an ELF formatted object file called shorty.o in ram: from the shorty.s source file.

==Hello? World's Shortest MorphOS Program - Or Is It?==

There are times when a linker is needed to further process an object file to generate an executable - this isn't one of those times.

Go ahead and enter this into the shell window:

<pre>
ram:shorty.o
</pre>

It will appear as if nothing happens - but at least it happens very quickly. However, something did happen. shorty.o was identified as an executable program and loaded into memory where the cpu instruction execution sequence passed to it. As mentioned above, the single '''blr''' instruction in this program caused the instruction execution sequence to pass directly back to where it was called from - in this case, the shell.

It may be of interest to know that all PPC instructions are four bytes long. In PPC nomenclature, this length is known as a word. But let's take a moment to have a look at the size of shorty.o

Enter this into the shell window:

<pre>
list ram:shorty.o
</pre>

2664 bytes?! But this is typical for object files as they contain much additional information that is used in the process of debugging and linking. Linking, particularly with the -s 'strip all symbols' option, will generate an executable that is noticeably smaller.

Try entering this into the shell window:

<pre>
vlink -s -o ram:shorty ram:shorty.o

list ram:shorty
</pre>

The newly generated executable is 328 bytes - much smaller than it's object file but what are those other 324 bytes doing there? They are the ELF 'container' that holds the single, four byte instruction of shorty. ELF stands for Executable and Linkable Format and it is used by MorphOS, AmigaOS4 and AROS - not to forget, Linux, UNIX, BSD and even video game consoles. There is abundant information about this file format online but this topic will be discussed a little further when the use of the objdump program is introduced.

==The Old And The New==

Generally, in order to make a program that does something useful or to at least produce an observable result, it is necessary to use operating system library functions. Despite the markedly different cpu family that MorphOS runs on compared to the 68k family used by the classic AmigaOS, MorphOS is largely compatible with AmigaOS. This compatibility is reflected in a very similar API shared with AmigaOS and extends to using a MorphOS system structure as if it were the internal data and address registers of an actual 68k processor. This is called the EmulHandle structure and it is always available through the PPC GPR2 register. Also, as with 68k AmigaOS, the address of the Exec library base is always to be found at memory location 4. Many aspects of the AmigaOS API fit closely to the features available in the 68k cpu and the following code comparison should illustrate how it is echoed in the PPC MorphOS API.

A common task performed during the initialisation of many programs - opening the Dos library. It is a particularly simple example of library usage but most functions follow this form.

[[File:Old-and-new.png]]

@ha & @l are needed to specify the high and low halfwords of 32 bit immediate values because the fixed 32 bit size of PPC instructions does not allow enough space for an instruction opcode and additional 32 bits of data.

One could be forgiven for thinking that the PPC code snippet looks a little ungainly compared to the former. Whereas every PPC instruction is four bytes long, 68k instructions can be as little as two bytes but up to as many as ten. A single 68k instruction can load a value from a 32 bit memory address specified by one instruction operand and store it at another 32 bit memory address specified by the second instruction operand. The 68k can also perform other operations beyond simple loads and stores directly on memory. Or at least appear to... In truth, computer memory only sends and receives data - no other data processing (like adding, subtracting & etc) occurs in memory. While the 68k instruction '''add.l #$12345678,(a0)''' appears to add the immediate value of it's first operand to whatever may already be stored at the address pointed to by a0, the contents of that address are actually loaded from memory into a private work register, the addition is performed and then the result is stored back to the same memory location. So this instruction actually performs two memory accesses where it might appear that there was only one. Contrast this with PPC assembly programming where memory loads and stores are all done explicitly. Before data can be operated upon it must be loaded from memory into a GPR (General Purpose Register), zero (in the case of a simple memory copy) or more operations can then be performed and then the data may be stored back to memory.

Unless you are brand-spanking-new to the topic of PPC assembly, you will already know that the PPC has 32 GPRs - r0 through r31. But did you know that the desired use of these registers is set out in something called the System V.4 ABI which MorphOS adheres to?

<pre>
r0 - volatile
r1 - stack pointer
r2 - for system use (with MorphOS, r2 points to the EmulHandle structure)

r3 - initialised with a pointer to a Dos command buffer
r4 - initialised with the length of the Dos command buffer
r5 - initialised with a pointer to an ELF structure

r3 ... r10 volatile & can be used to pass function arguments. If more
arguments are required, the stack is used.

r11 & r12 - volatile

r13 - small data area pointer. If this register is needed by a function or
subroutine, it must be saved first and then restored before
returning to where it was called from.

r14 ... r31 - No predefined purpose. If these registers are needed by a
function or subroutine, they must be saved first and then restored
before returning to where it was called from.
</pre>

The above use of the word 'volatile' means that functions are not expected to preserve the contents of these registers. r1 & r2 are the only registers that must be restored to their initial values by a terminating program, however, while most programs will modify r1 and later restore it, it is best to have not modified r2 in the first place.

This System V.4 ABI also sets out a particular way for programs and subroutines to organise their stack frames. When a program is loaded into memory and the instruction execution sequence passes to it, the stack pointer is still pointing to the calling program's stack frame and there is also an important address stored in the Link Register at this time. Unless this program is very simple (like shorty) it must save the Link Register address and, most likely, create it's own stack frame. Somewhat conveniently, there is a special position in the caller's stack frame that a callee program can save the contents of the Link Register to. This is a fairly common example of a program or subroutine's very first instructions.

[[File:Awkward-program-initialisation.png]]

Uh indeed... Let's try to visualise some memory being used as stack space.

[[File:Stack-diagram16.png]]

Note that '''stwu r1,-8(r1)''' creates a two-word stack frame which is the smallest stack that a program or subroutine can have if it, in turn, calls another program, subroutine or library function. More often, a larger stack frame is created although, '''stwu r1,-4(r1)''' could be used by a program or subroutine to create a one-word stack frame but this would be redundant and such a program must not call any other program, subroutine or library function. Such a program would not need to store the value in the Link Register (LR) to prevent it from being overwritten by subsequent calls and can terminate and return to it's caller with a simple '''blr''' instruction - just like shorty does.

A further note about larger stack frames and appropriate stack sizes: For reasons relating to PPC architecture, it is a good idea to choose stack frame sizes that are multiples of 16 bytes.

This is a less common example of a program's first instructions but it may better illustrate how to use stack frames.

[[File:Program-initialisation.png]]

Let's jump ahead and look at the last few instructions involved in program termination that would 'undo' the above instructions.

[[File:Program-termination.png]]

==A Little Less Talk And A Little More Action Please==

It's time to compile another program - this one will actually do something.

But wait...

Not another 'Hello World' program... I'm afraid so. This time, copy and paste is probably quicker. ''A fully commented version will be made available for download soon.''

Note that this example does not use the MorphOS SDK. Instead, some 'quick and dirty' methods are used for the sake of simplicity and readability.

<pre>
# Various library function offsets
.set _LVOOpenLibrary,-552
.set _LVOCloseLibrary,-414
.set _LVOVPrintf,-954
.set _AbsExecBase,4

# EmulHandle structure (always pointed to by r2)
.set reg_d0,0
.set reg_d1,4
.set reg_d2,8
.set reg_d3,12
.set reg_d4,16
.set reg_d5,20
.set reg_d6,24
.set reg_d7,28
.set reg_a0,32
.set reg_a1,36
.set reg_a2,40
.set reg_a3,44
.set reg_a4,48
.set reg_a5,52
.set reg_a6,56
.set reg_a7,60
.set EmulCallDirectOS,100

# Stack frame offsets
.set stack_pos0_caller_stack,0
.set stack_pos1_callerLR,4
.set stack_pos2_ExecBase,8
.set stack_pos3_DosBase,12
.set new_4_word_stack,16

.text

mflr r0
stw r0,stack_pos1_callerLR(r1)
stwu r1,-new_4_word_stack(r1)

lis r3,dosName@ha
addi r3,r3,dosName@l
stw r3,reg_a1(r2)
li r3,0
stw r3,reg_d0(r2)
li r3,_AbsExecBase
lwz r3,0(r3)
stw r3,stack_pos2_ExecBase(r1)
stw r3,reg_a6(r2)
li r3,_LVOOpenLibrary
lwz r0,EmulCallDirectOS(r2)
mtctr r0
bctrl

cmpwi r3,0
beq exit

stw r3,stack_pos3_DosBase(r1)

lis r4,string1@ha
addi r4,r4,string1@l
stw r4,reg_d1(r2)
li r4,0
stw r4,reg_d2(r2)
stw r3,reg_a6(r2)
li r3,_LVOVPrintf
lwz r0,EmulCallDirectOS(r2)
mtctr r0
bctrl

lwz r3,stack_pos3_DosBase(r1)
stw r3,reg_a1(r2)
lwz r3,stack_pos2_ExecBase(r1)
stw r3,reg_a6(r2)
li r3,_LVOCloseLibrary
lwz r0,EmulCallDirectOS(r2)
mtctr r0
bctrl

li r3,0

exit: addi r1,r1,new_4_word_stack
lwz r0,stack_pos1_callerLR(r1)
mtlr r0
blr

.rodata

__abox__:

dosName:
.string dos.library

string1:
.string "Hello World\n"
</pre>

Save this source file as HelloWorld.p and open a shell window. Change directory to where HelloWorld.p was just saved and enter:

<pre>
vasmppc_std -Felf -o ram:hw.o HelloWorld.p
</pre>

Once again, because of the simplicity of this program, linking isn't necessary so just enter the following in the shell window:

<pre>
ram:hw.o
</pre>

Are you impressed? Feel free to modify, experiment with and improve this source code. A not-too-difficult challenge might be to change this program so that it prints the arguments given to it in the shell window - a number of small but significant changes would be needed to do this.

When choosing which registers to use in your own programs, be aware that use of r0 in some instruction operands will not always work as you might expect. In these instructions, the actual content of r0 is ignored and the result is based on the constant value zero instead. For example, imagine that r0 contains the value 100 and then this instruction is executed: '''addi r0,r0,50''' It looks like the result should be r0 = r0 + 50 = 150 The result will actually be r0 = 0 + 50 = 50 This may seem odd but, as long as the programmer is aware of it, it can be useful. A good PPC instruction reference manual will explain this, and many other things, in much greater detail. There are many of these reference documents available on the internet - this is one of them [http://www.freescale.com/files/product/doc/MPCFPE32B.pdf MPCFPE32B.pdf]

==MorphOS SDK, Objdump, ELFs & Sections==

In addition to installing vbcc, it is also recommended to install the [http://www.morphos-team.net/files/sdk-20100617.lha MorphOS SDK] and the [http://mail.pb-owl.de/~frank/vbcc/current/vbcc_target_ppc-morphos.lha vbcc MorphOS compiler target].

The installer script of the latter seems to expect that there is a pre-existing assign for include: and, if your system already assigns include: to somewhere, please skip over this next part.

What follows is my S:user-startup after the installation of vbcc, it's MorphOS compiler target and an additional assign that I made preceded by this comment -

;vbcc MorphOS target needs include: to be assigned to somewhere

<pre>
;
; MorphOS user-startup
;
; This script is executed on system boot by
; startup-sequence. You can make personal
; changes in here.
;
; $VER: user-startup 1.1
;

; Enable the following to mount the inet-handler. Note that TCP: allows
; easy access to internet, and allows scripts to listen for incoming
; connections. Some malware could abuse this.
;Mount TCP:
;BEGIN vbcc
assign >NIL: vbcc: mos26:vbcc
assign >NIL: C: vbcc:bin ADD
setenv VBCC vbcc:
;END vbcc

;vbcc MorphOS target needs include: to be assigned to somewhere
assign include: vbcc:targets/ppc-morphos/include

;BEGIN vbcc-ppc-morphos
assign >NIL: vincludemos: vbcc:targets/ppc-morphos/include
assign >NIL: vincludemos: include: add
assign >NIL: vlibmos: vbcc:targets/ppc-morphos/lib
;END vbcc-ppc-morphos
</pre>

As mentioned just before the previous source code example, some quick and dirty methods were used for the sake of simplicity and readability and this refers to the way library function offsets were established. This approach will quickly become detrimental as more offsets are added. There are a number of solutions to this problem but only one will be presented here and it involves the removal of the leading underscore character from function names and appending '@l' to the end so that, for example, '''li r3,_LVOOpenLibrary''' becomes '''li r3,LVOOpenLibrary@l'''. Assemble with vasm as before but note that the resulting object file is no longer executable. To make this object executable, vlink is needed.

<pre>
vlink -b elf32morphos -o <desired executable name> <existing object name> -lamiga
</pre>

In the above shell command, -lamiga refers to the libamiga.a file that vlink knows to look for in vlibmos: This file contains information used to resolve many library function names to numerical values. Note that any executable generated from the above vlink command will contain a lot of symbol information that, while potentially useful, increases the size of the executable. This can be avoided with a few additions to the above command.

<pre>
vlink -b elf32morphos -s -x -P__abox__ <desired executable name> <existing object name> -lamiga
</pre>

-s strip symbols from the output file 
-x discard local symbols from input file(s) 
-P<symbol> preserve this symbol 

For more information, please refer to the documentation for vlink and other programs installed with vbcc.

At this point it would be useful to have a number of freshly generated object files and executables to look at with objdump although any ELF can be used for this purpose.

''final part yet to come''

An Introduction to MorphOS PPC Assembly

2010-11-26T04:24:07Z

AusPPC: Removing unnecessary command line options. Other minor edits.

==Jump In The Deep End And Compile Something Right Now==

You could copy and paste but just entering the two lines below into a suitable text editor is probably quicker.

<pre>
.text
blr
</pre>

Save as ''shorty.s''

'''.text''' is an assembler directive - more about it later. '''blr''' is one of many branch instructions. This particular one means 'Branch to Link Register'. When a program terminates, this is the last instruction to be executed and it causes the sequence of instruction execution to pass back to the calling program or environment (shell, Ambient etc). Subroutines can also terminate with this instruction but, again, more about this later.

This is as good a time as any to ask if you've installed vbcc yet - if not, go and do it. [http://mail.pb-owl.de/~frank/vbcc/current/vbcc_bin_morphos.lha Download vbcc]

Once vbcc is installed, open a shell window and change directory to where shorty.s has been saved.

Enter:

<pre>
vasmppc_std -Felf -o ram:shorty.o shorty.s
</pre>

This tells vasm to generate an ELF formatted object file called shorty.o in ram: from the shorty.s source file.

==Hello? World's Shortest MorphOS Program - Or Is It?==

There are times when a linker is needed to further process an object file to generate an executable - this isn't one of those times.

Go ahead and enter this into the shell window:

<pre>
ram:shorty.o
</pre>

It will appear as if nothing happens - but at least it happens very quickly. However, something did happen. shorty.o was identified as an executable program and loaded into memory where the cpu instruction execution sequence passed to it. As mentioned above, the single '''blr''' instruction in this program caused the instruction execution sequence to pass directly back to where it was called from - in this case, the shell.

It may be of interest to know that all PPC instructions are four bytes long. In PPC nomenclature, this length is known as a word. But let's take a moment to have a look at the size of shorty.o

Enter this into the shell window:

<pre>
list ram:shorty.o
</pre>

2664 bytes?! But this is typical for object files as they contain much additional information that is used in the process of debugging and linking. Linking, particularly with the -s 'strip all symbols' option, will generate an executable that is noticeably smaller.

Try entering this into the shell window:

<pre>
vlink -s -o ram:shorty ram:shorty.o

list ram:shorty
</pre>

The newly generated executable is 328 bytes - much smaller than it's object file but what are those other 324 bytes doing there? They are the ELF 'container' that holds the single, four byte instruction of shorty. ELF stands for Executable and Linkable Format and it is used by MorphOS, AmigaOS4 and AROS - not to forget, Linux, UNIX, BSD and even video game consoles. There is abundant information about this file format online but this topic will be discussed a little further when the use of the objdump program is introduced.

==The Old And The New==

Generally, in order to make a program that does something useful or to at least produce an observable result, it is necessary to use operating system library functions. Despite the markedly different cpu family that MorphOS runs on compared to the 68k family used by the classic AmigaOS, MorphOS is largely compatible with AmigaOS. This compatibility is reflected in a very similar API shared with AmigaOS and extends to using a MorphOS system structure as if it were the internal data and address registers of an actual 68k processor. This is called the EmulHandle structure and it is always available through the PPC GPR2 register. Also, as with 68k AmigaOS, the address of the Exec library base is always to be found at memory location 4. Many aspects of the AmigaOS API fit closely to the features available in the 68k cpu and the following code comparison should illustrate how it is echoed in the PPC MorphOS API.

A common task performed during the initialisation of many programs - opening the Dos Library. It is a particularly simple example of library usage but most functions follow this form.

[[File:Old-and-new.png]]

@ha & @l are needed to specify the high and low halfwords of 32 bit immediate values because the fixed 32 bit size of PPC instructions does not allow enough space for an instruction opcode and additional 32 bits of data.

One could be forgiven for thinking that the PPC code snippet looks a little ungainly compared to the former. Whereas every PPC instruction is four bytes long, 68k instructions can be as little as two bytes but up to as many as ten. A single 68k instruction can load a value from a 32 bit memory address specified by one instruction operand and store it at another 32 bit memory address specified by the second instruction operand. The 68k can also perform other operations beyond simple loads and stores directly on memory. Or at least appear to... In truth, computer memory only sends and receives data - no other data processing (like adding, subtracting & etc) occurs in memory. While the 68k instruction '''add.l #$12345678,(a0)''' appears to add the immediate value of it's first operand to whatever may already be stored at the address pointed to by a0, the contents of that address are actually loaded from memory into a private work register, the addition is performed and then the result is stored back to the same memory location. So this instruction actually performs two memory accesses where it might appear that there was only one. Contrast this with PPC assembly programming where memory loads and stores are all done explicitly. Before data can be operated upon it must be loaded from memory into a GPR (General Purpose Register), zero (in the case of a simple memory copy) or more operations can then be performed and then the data may be stored back to memory.

Unless you are brand-spanking-new to the topic of PPC assembly, you will already know that the PPC has 32 GPRs - r0 through r31. But did you know that the desired use of these registers is set out in something called the System V.4 ABI which MorphOS adheres to?

<pre>
r0 - volatile
r1 - stack pointer
r2 - for system use (with MorphOS, r2 points to the EmulHandle structure)

r3 - initialised with a pointer to a Dos command buffer
r4 - initialised with the length of the Dos command buffer
r5 - initialised with a pointer to an ELF structure

r3 ... r10 volatile & can be used to pass function arguments. If more
arguments are required, the stack is used.

r11 & r12 - volatile

r13 - small data area pointer. If this register is needed by a function or
subroutine, it must be saved first and then restored before
returning to where it was called from.

r14 ... r31 - No predefined purpose. If these registers are needed by a
function or subroutine, they must be saved first and then restored
before returning to where it was called from.
</pre>

The above use of the word 'volatile' means that functions are not expected to preserve the contents of these registers. r1 & r2 are the only registers that must be restored to their initial values by a terminating program, however, while most programs will modify r1 and later restore it, it is best to have not modified r2 in the first place.

This System V.4 ABI also sets out a particular way for programs and subroutines to organise their stack frames. When a program is loaded into memory and the instruction execution sequence passes to it, the stack pointer is still pointing to the calling program's stack frame and there is also an important address stored in the Link Register at this time. Unless this program is very simple (like shorty) it must save the Link Register address and, most likely, create it's own stack frame. Somewhat conveniently, there is a special position in the caller's stack frame that a callee program can save the contents of the Link Register to. This is a fairly common example of a program or subroutine's very first instructions.

[[File:Awkward-program-initialisation.png]]

Uh indeed... Let's try to visualise some memory being used as stack space.

[[File:Stack-diagram16.png]]

Note that '''stwu r1,-8(r1)''' creates a two-word stack frame which is the smallest stack that a program or subroutine can have if it, in turn, calls another program, subroutine or library function. More often, a larger stack frame is created although, '''stwu r1,-4(r1)''' could be used by a program or subroutine to create a one-word stack frame but this would be redundant and such a program must not call any other program, subroutine or library function. Such a program would not need to store the value in the Link Register (LR) to prevent it from being overwritten by subsequent calls and can terminate and return to it's caller with a simple '''blr''' instruction - just like shorty does.

A further note about larger stack frames and appropriate stack sizes: For reasons relating to PPC architecture, it is a good idea to choose stack frame sizes that are multiples of 16 bytes.

This is a less common example of a program's first instructions but it may better illustrate how to use stack frames.

[[File:Program-initialisation.png]]

Let's jump ahead and look at the last few instructions involved in program termination that would 'undo' the above instructions.

[[File:Program-termination.png]]

==A Little Less Talk And A Little More Action Please==

It's time to compile another program - this one will actually do something.

But wait...

Not another 'Hello World' program... I'm afraid so. This time, copy and paste is probably quicker. ''A fully commented version will be made available for download soon.''

Note that this example does not use the MorphOS SDK. Instead, some 'quick and dirty' methods are used for the sake of simplicity and readability.

<pre>
# Various library function offsets
.set _LVOOpenLibrary,-552
.set _LVOCloseLibrary,-414
.set _LVOVPrintf,-954
.set _AbsExecBase,4

# EmulHandle structure (always pointed to by r2)
.set reg_d0,0
.set reg_d1,4
.set reg_d2,8
.set reg_d3,12
.set reg_d4,16
.set reg_d5,20
.set reg_d6,24
.set reg_d7,28
.set reg_a0,32
.set reg_a1,36
.set reg_a2,40
.set reg_a3,44
.set reg_a4,48
.set reg_a5,52
.set reg_a6,56
.set reg_a7,60
.set EmulCallDirectOS,100

# Stack frame offsets
.set stack_pos0_caller_stack,0
.set stack_pos1_callerLR,4
.set stack_pos2_ExecBase,8
.set stack_pos3_DosBase,12
.set new_4_word_stack,16

.text

mflr r0
stw r0,stack_pos1_callerLR(r1)
stwu r1,-new_4_word_stack(r1)

lis r3,dosName@ha
addi r3,r3,dosName@l
stw r3,reg_a1(r2)
li r3,0
stw r3,reg_d0(r2)
li r3,_AbsExecBase
lwz r3,0(r3)
stw r3,stack_pos2_ExecBase(r1)
stw r3,reg_a6(r2)
li r3,_LVOOpenLibrary
lwz r0,EmulCallDirectOS(r2)
mtctr r0
bctrl

cmpwi r3,0
beq exit

stw r3,stack_pos3_DosBase(r1)

lis r4,string1@ha
addi r4,r4,string1@l
stw r4,reg_d1(r2)
li r4,0
stw r4,reg_d2(r2)
stw r3,reg_a6(r2)
li r3,_LVOVPrintf
lwz r0,EmulCallDirectOS(r2)
mtctr r0
bctrl

lwz r3,stack_pos3_DosBase(r1)
stw r3,reg_a1(r2)
lwz r3,stack_pos2_ExecBase(r1)
stw r3,reg_a6(r2)
li r3,_LVOCloseLibrary
lwz r0,EmulCallDirectOS(r2)
mtctr r0
bctrl

li r3,0

exit: addi r1,r1,new_4_word_stack
lwz r0,stack_pos1_callerLR(r1)
mtlr r0
blr

.rodata

__abox__:

dosName:
.string dos.library

string1:
.string "Hello World\n"
</pre>

Save this source file as HelloWorld.p and open a shell window. Change directory to where HelloWorld.p was just saved and enter:

<pre>
vasmppc_std -Felf -o ram:hw.o HelloWorld.p
</pre>

Once again, because of the simplicity of this program, linking isn't necessary so just enter the following in the shell window:

<pre>
ram:hw.o
</pre>

Are you impressed? Feel free to modify, experiment with and improve this source code. A not-too-difficult challenge might be to change this program so that it prints the arguments given to it in the shell window - a number of small but significant changes would be needed to do this.

When choosing which registers to use in your own programs, be aware that use of r0 in some instruction operands will not always work as you might expect. In these instructions, the actual content of r0 is ignored and the result is based on the constant value zero instead. For example, imagine that r0 contains the value 100 and then this instruction is executed: '''addi r0,r0,50''' It looks like the result should be r0 = r0 + 50 = 150 The result will actually be r0 = 0 + 50 = 50 This may seem odd but, as long as the programmer is aware of it, it can be useful. A good PPC instruction reference manual will explain this, and many other things, in much greater detail. There are many of these reference documents available on the internet - this is one of them [http://www.freescale.com/files/product/doc/MPCFPE32B.pdf MPCFPE32B.pdf]

==MorphOS SDK, Objdump, ELFs & Sections==

In addition to installing vbcc, it is also recommended to install the [http://www.morphos-team.net/files/sdk-20100617.lha MorphOS SDK] and the [http://mail.pb-owl.de/~frank/vbcc/current/vbcc_target_ppc-morphos.lha vbcc MorphOS compiler target].

The installer script of the latter seems to expect that there is a pre-existing assign for include: and, if your system already assigns include: to somewhere, please skip over this next part.

What follows is my S:user-startup after the installation of vbcc, it's MorphOS compiler target and an additional assign that I made preceded by this comment -

;vbcc MorphOS target needs include: to be assigned to somewhere

<pre>
;
; MorphOS user-startup
;
; This script is executed on system boot by
; startup-sequence. You can make personal
; changes in here.
;
; $VER: user-startup 1.1
;

; Enable the following to mount the inet-handler. Note that TCP: allows
; easy access to internet, and allows scripts to listen for incoming
; connections. Some malware could abuse this.
;Mount TCP:
;BEGIN vbcc
assign >NIL: vbcc: mos26:vbcc
assign >NIL: C: vbcc:bin ADD
setenv VBCC vbcc:
;END vbcc

;vbcc MorphOS target needs include: to be assigned to somewhere
assign include: vbcc:targets/ppc-morphos/include

;BEGIN vbcc-ppc-morphos
assign >NIL: vincludemos: vbcc:targets/ppc-morphos/include
assign >NIL: vincludemos: include: add
assign >NIL: vlibmos: vbcc:targets/ppc-morphos/lib
;END vbcc-ppc-morphos
</pre>

As mentioned just before the previous source code example, some quick and dirty methods were used for the sake of simplicity and readability and this refers to the way library function offsets were established. This approach will quickly become detrimental as more offsets are added. There are a number of solutions to this problem but only one will be presented here and it involves the removal of the leading underscore character from function names and appending '@l' to the end so that, for example, '''li r3,_LVOOpenLibrary''' becomes '''li r3,LVOOpenLibrary@l'''. Assemble with vasm as before but note that the resulting object file is no longer executable. To make this object executable, vlink is needed.

<pre>
vlink -b elf32morphos -o <desired executable name> <existing object name> -lamiga
</pre>

In the above shell command, -lamiga refers to the libamiga.a file that vlink knows to look for in vlibmos: This file contains information used to resolve many library function names to numerical values. Note that any executable generated from the above vlink command will contain a lot of symbol information that, while potentially useful, increases the size of the executable. This can be avoided with a few additions to the above command.

<pre>
vlink -b elf32morphos -s -x -P__abox__ <desired executable name> <existing object name> -lamiga
</pre>

-s strip symbols from the output file 
-x discard local symbols from input file(s) 
-P<symbol> preserve this symbol 

For more information, please refer to the documentation for vlink and other programs installed with vbcc.

At this point it would be useful to have a number of freshly generated object files and executables to look at with objdump although any ELF can be used for this purpose.

''final part yet to come''

An Introduction to MorphOS PPC Assembly

2010-11-26T04:17:20Z

AusPPC: Changing source file extension to one that is recognised by MorphOS. Other minor edits.

==Jump In The Deep End And Compile Something Right Now==

You could copy and paste but just entering the two lines below into a suitable text editor is probably quicker.

<pre>
.text
blr
</pre>

Save as ''shorty.s''

'''.text''' is an assembler directive - more about it later. '''blr''' is one of many branch instructions. This particular one means 'Branch to Link Register'. When a program terminates, this is the last instruction to be executed and it causes the sequence of instruction execution to pass back to the calling program or environment (shell, Ambient etc). Subroutines can also terminate with this instruction but, again, more about this later.

This is as good a time as any to ask if you've installed vbcc yet - if not, go and do it. [http://mail.pb-owl.de/~frank/vbcc/current/vbcc_bin_morphos.lha Download vbcc]

Once vbcc is installed, open a shell window and change directory to where shorty.s has been saved.

Enter:

<pre>
vasmppc_std -Felf -o ram:shorty.o shorty.s
</pre>

This tells vasm to generate an ELF formatted object file called shorty.o in ram: from the shorty.s source file.

==Hello? World's Shortest MorphOS Program - Or Is It?==

There are times when a linker is needed to further process an object file to generate an executable - this isn't one of those times.

Go ahead and enter this into the shell window:

<pre>
ram:shorty.o
</pre>

It will appear as if nothing happens - but at least it happens very quickly. However, something did happen. shorty.o was identified as an executable program and loaded into memory where the cpu instruction execution sequence passed to it. As mentioned above, the single '''blr''' instruction in this program caused the instruction execution sequence to pass directly back to where it was called from - in this case, the shell.

It may be of interest to know that all PPC instructions are four bytes long. In PPC nomenclature, this length is known as a word. But let's take a moment to have a look at the size of shorty.o

Enter this into the shell window:

<pre>
list ram:shorty.o
</pre>

2660 bytes?! But this is typical for object files as they contain much additional information that is used in the process of debugging and linking. Linking, particularly with a few key options, will generate an executable that is noticeably smaller.

Try entering this into the shell window:

<pre>
vlink -b elf32morphos -s -x -o ram:shorty ram:shorty.o

list ram:shorty
</pre>

The newly generated executable is 328 bytes - much smaller than it's object file but what are those other 324 bytes doing there? They are the ELF 'container' that holds the single, four byte instruction of shorty. ELF stands for Executable and Linkable Format and it is used by MorphOS, AmigaOS4 and AROS - not to forget, Linux, UNIX, BSD and even video game consoles. There is abundant information about this file format online but this topic will be discussed a little further when the use of the objdump program is introduced.

==The Old And The New==

Generally, in order to make a program that does something useful or to at least produce an observable result, it is necessary to use operating system library functions. Despite the markedly different cpu family that MorphOS runs on compared to the 68k family used by the classic AmigaOS, MorphOS is largely compatible with AmigaOS. This compatibility is reflected in a very similar API shared with AmigaOS and extends to using a MorphOS system structure as if it were the internal data and address registers of an actual 68k processor. This is called the EmulHandle structure and it is always available through the PPC GPR2 register. Also, as with 68k AmigaOS, the address of the Exec library base is always to be found at memory location 4. Many aspects of the AmigaOS API fit closely to the features available in the 68k cpu and the following code comparison should illustrate how it is echoed in the PPC MorphOS API.

A common task performed during the initialisation of many programs - opening the Dos Library. It is a particularly simple example of library usage but most functions follow this form.

[[File:Old-and-new.png]]

@ha & @l are needed to specify the high and low halfwords of 32 bit immediate values because the fixed 32 bit size of PPC instructions does not allow enough space for an instruction opcode and additional 32 bits of data.

One could be forgiven for thinking that the PPC code snippet looks a little ungainly compared to the former. Whereas every PPC instruction is four bytes long, 68k instructions can be as little as two bytes but up to as many as ten. A single 68k instruction can load a value from a 32 bit memory address specified by one instruction operand and store it at another 32 bit memory address specified by the second instruction operand. The 68k can also perform other operations beyond simple loads and stores directly on memory. Or at least appear to... In truth, computer memory only sends and receives data - no other data processing (like adding, subtracting & etc) occurs in memory. While the 68k instruction '''add.l #$12345678,(a0)''' appears to add the immediate value of it's first operand to whatever may already be stored at the address pointed to by a0, the contents of that address are actually loaded from memory into a private work register, the addition is performed and then the result is stored back to the same memory location. So this instruction actually performs two memory accesses where it might appear that there was only one. Contrast this with PPC assembly programming where memory loads and stores are all done explicitly. Before data can be operated upon it must be loaded from memory into a GPR (General Purpose Register), zero (in the case of a simple memory copy) or more operations can then be performed and then the data may be stored back to memory.

Unless you are brand-spanking-new to the topic of PPC assembly, you will already know that the PPC has 32 GPRs - r0 through r31. But did you know that the desired use of these registers is set out in something called the System V.4 ABI which MorphOS adheres to?

<pre>
r0 - volatile
r1 - stack pointer
r2 - for system use (with MorphOS, r2 points to the EmulHandle structure)

r3 - initialised with a pointer to a Dos command buffer
r4 - initialised with the length of the Dos command buffer
r5 - initialised with a pointer to an ELF structure

r3 ... r10 volatile & can be used to pass function arguments. If more
arguments are required, the stack is used.

r11 & r12 - volatile

r13 - small data area pointer. If this register is needed by a function or
subroutine, it must be saved first and then restored before
returning to where it was called from.

r14 ... r31 - No predefined purpose. If these registers are needed by a
function or subroutine, they must be saved first and then restored
before returning to where it was called from.
</pre>

The above use of the word 'volatile' means that functions are not expected to preserve the contents of these registers. r1 & r2 are the only registers that must be restored to their initial values by a terminating program, however, while most programs will modify r1 and later restore it, it is best to have not modified r2 in the first place.

This System V.4 ABI also sets out a particular way for programs and subroutines to organise their stack frames. When a program is loaded into memory and the instruction execution sequence passes to it, the stack pointer is still pointing to the calling program's stack frame and there is also an important address stored in the Link Register at this time. Unless this program is very simple (like shorty) it must save the Link Register address and, most likely, create it's own stack frame. Somewhat conveniently, there is a special position in the caller's stack frame that a callee program can save the contents of the Link Register to. This is a fairly common example of a program or subroutine's very first instructions.

[[File:Awkward-program-initialisation.png]]

Uh indeed... Let's try to visualise some memory being used as stack space.

[[File:Stack-diagram16.png]]

Note that '''stwu r1,-8(r1)''' creates a two-word stack frame which is the smallest stack that a program or subroutine can have if it, in turn, calls another program, subroutine or library function. More often, a larger stack frame is created although, '''stwu r1,-4(r1)''' could be used by a program or subroutine to create a one-word stack frame but this would be redundant and such a program must not call any other program, subroutine or library function. Such a program would not need to store the value in the Link Register (LR) to prevent it from being overwritten by subsequent calls and can terminate and return to it's caller with a simple '''blr''' instruction - just like shorty does.

A further note about larger stack frames and appropriate stack sizes: For reasons relating to PPC architecture, it is a good idea to choose stack frame sizes that are multiples of 16 bytes.

This is a less common example of a program's first instructions but it may better illustrate how to use stack frames.

[[File:Program-initialisation.png]]

Let's jump ahead and look at the last few instructions involved in program termination that would 'undo' the above instructions.

[[File:Program-termination.png]]

==A Little Less Talk And A Little More Action Please==

It's time to compile another program - this one will actually do something.

But wait...

Not another 'Hello World' program... I'm afraid so. This time, copy and paste is probably quicker. ''A fully commented version will be made available for download soon.''

Note that this example does not use the MorphOS SDK. Instead, some 'quick and dirty' methods are used for the sake of simplicity and readability.

<pre>
# Various library function offsets
.set _LVOOpenLibrary,-552
.set _LVOCloseLibrary,-414
.set _LVOVPrintf,-954
.set _AbsExecBase,4

# EmulHandle structure (always pointed to by r2)
.set reg_d0,0
.set reg_d1,4
.set reg_d2,8
.set reg_d3,12
.set reg_d4,16
.set reg_d5,20
.set reg_d6,24
.set reg_d7,28
.set reg_a0,32
.set reg_a1,36
.set reg_a2,40
.set reg_a3,44
.set reg_a4,48
.set reg_a5,52
.set reg_a6,56
.set reg_a7,60
.set EmulCallDirectOS,100

# Stack frame offsets
.set stack_pos0_caller_stack,0
.set stack_pos1_callerLR,4
.set stack_pos2_ExecBase,8
.set stack_pos3_DosBase,12
.set new_4_word_stack,16

.text

mflr r0
stw r0,stack_pos1_callerLR(r1)
stwu r1,-new_4_word_stack(r1)

lis r3,dosName@ha
addi r3,r3,dosName@l
stw r3,reg_a1(r2)
li r3,0
stw r3,reg_d0(r2)
li r3,_AbsExecBase
lwz r3,0(r3)
stw r3,stack_pos2_ExecBase(r1)
stw r3,reg_a6(r2)
li r3,_LVOOpenLibrary
lwz r0,EmulCallDirectOS(r2)
mtctr r0
bctrl

cmpwi r3,0
beq exit

stw r3,stack_pos3_DosBase(r1)

lis r4,string1@ha
addi r4,r4,string1@l
stw r4,reg_d1(r2)
li r4,0
stw r4,reg_d2(r2)
stw r3,reg_a6(r2)
li r3,_LVOVPrintf
lwz r0,EmulCallDirectOS(r2)
mtctr r0
bctrl

lwz r3,stack_pos3_DosBase(r1)
stw r3,reg_a1(r2)
lwz r3,stack_pos2_ExecBase(r1)
stw r3,reg_a6(r2)
li r3,_LVOCloseLibrary
lwz r0,EmulCallDirectOS(r2)
mtctr r0
bctrl

li r3,0

exit: addi r1,r1,new_4_word_stack
lwz r0,stack_pos1_callerLR(r1)
mtlr r0
blr

.rodata

__abox__:

dosName:
.string dos.library

string1:
.string "Hello World\n"
</pre>

Save this source file as HelloWorld.p and open a shell window. Change directory to where HelloWorld.p was just saved and enter:

<pre>
vasmppc_std -Felf -o ram:hw.o HelloWorld.p
</pre>

Once again, because of the simplicity of this program, linking isn't necessary so just enter the following in the shell window:

<pre>
ram:hw.o
</pre>

Are you impressed? Feel free to modify, experiment with and improve this source code. A not-too-difficult challenge might be to change this program so that it prints the arguments given to it in the shell window - a number of small but significant changes would be needed to do this.

When choosing which registers to use in your own programs, be aware that use of r0 in some instruction operands will not always work as you might expect. In these instructions, the actual content of r0 is ignored and the result is based on the constant value zero instead. For example, imagine that r0 contains the value 100 and then this instruction is executed: '''addi r0,r0,50''' It looks like the result should be r0 = r0 + 50 = 150 The result will actually be r0 = 0 + 50 = 50 This may seem odd but, as long as the programmer is aware of it, it can be useful. A good PPC instruction reference manual will explain this, and many other things, in much greater detail. There are many of these reference documents available on the internet - this is one of them [http://www.freescale.com/files/product/doc/MPCFPE32B.pdf MPCFPE32B.pdf]

==MorphOS SDK, Objdump, ELFs & Sections==

In addition to installing vbcc, it is also recommended to install the [http://www.morphos-team.net/files/sdk-20100617.lha MorphOS SDK] and the [http://mail.pb-owl.de/~frank/vbcc/current/vbcc_target_ppc-morphos.lha vbcc MorphOS compiler target].

The installer script of the latter seems to expect that there is a pre-existing assign for include: and, if your system already assigns include: to somewhere, please skip over this next part.

What follows is my S:user-startup after the installation of vbcc, it's MorphOS compiler target and an additional assign that I made preceded by this comment -

;vbcc MorphOS target needs include: to be assigned to somewhere

<pre>
;
; MorphOS user-startup
;
; This script is executed on system boot by
; startup-sequence. You can make personal
; changes in here.
;
; $VER: user-startup 1.1
;

; Enable the following to mount the inet-handler. Note that TCP: allows
; easy access to internet, and allows scripts to listen for incoming
; connections. Some malware could abuse this.
;Mount TCP:
;BEGIN vbcc
assign >NIL: vbcc: mos26:vbcc
assign >NIL: C: vbcc:bin ADD
setenv VBCC vbcc:
;END vbcc

;vbcc MorphOS target needs include: to be assigned to somewhere
assign include: vbcc:targets/ppc-morphos/include

;BEGIN vbcc-ppc-morphos
assign >NIL: vincludemos: vbcc:targets/ppc-morphos/include
assign >NIL: vincludemos: include: add
assign >NIL: vlibmos: vbcc:targets/ppc-morphos/lib
;END vbcc-ppc-morphos
</pre>

As mentioned just before the previous source code example, some quick and dirty methods were used for the sake of simplicity and readability and this refers to the way library function offsets were established. This approach will quickly become detrimental as more offsets are added. There are a number of solutions to this problem but only one will be presented here and it involves the removal of the leading underscore character from function names and appending '@l' to the end so that, for example, '''li r3,_LVOOpenLibrary''' becomes '''li r3,LVOOpenLibrary@l'''. Assemble with vasm as before but note that the resulting object file is no longer executable. To make this object executable, vlink is needed.

<pre>
vlink -b elf32morphos -o <desired executable name> <existing object name> -lamiga
</pre>

In the above shell command, -lamiga refers to the libamiga.a file that vlink knows to look for in vlibmos: This file contains information used to resolve many library function names to numerical values. Note that any executable generated from the above vlink command will contain a lot of symbol information that, while potentially useful, increases the size of the executable. This can be avoided with a few additions to the above command.

<pre>
vlink -b elf32morphos -s -x -P__abox__ <desired executable name> <existing object name> -lamiga
</pre>

-s strip symbols from the output file 
-x discard local symbols from input file(s) 
-P<symbol> preserve this symbol 

For more information, please refer to the documentation for vlink and other programs installed with vbcc.

At this point it would be useful to have a number of freshly generated object files and executables to look at with objdump although any ELF can be used for this purpose.

''final part yet to come''

An Introduction to MorphOS PPC Assembly

2010-11-24T14:52:37Z

AusPPC: Article content

==Jump In The Deep End And Compile Something Right Now==

You could copy and paste but just entering the two lines below into a suitable text editor is probably quicker.

<pre>
.text
blr
</pre>

Save as 'shorty.p'.

'''.text''' is an assembler directive - more about it later. '''blr''' is one of many branch instructions. This particular one means 'Branch to Link Register'. When a program terminates, this is the last instruction to be executed and it causes the sequence of instruction execution to pass back to the calling program or environment (shell, Ambient etc). Subroutines can also terminate with this instruction but, again, more about this later.

This is as good a time as any to ask if you've installed vbcc yet - if not, go and do it. [http://mail.pb-owl.de/~frank/vbcc/current/vbcc_bin_morphos.lha Download vbcc]

Once vbcc is installed, open a shell window and change directory to where shorty.p is saved.

Enter:

<pre>
vasmppc_std -Felf -o ram:shorty.o shorty.p
</pre>

This tells vasm to generate an elf formatted object file called shorty.o in ram: from the shorty.p source file.

==Hello? World's Shortest MorphOS Program - Or Is It?==

There are times when a linker is needed to further process an object file to generate an executable - this isn't one of those times.

Go ahead and enter this into the shell window:

<pre>
ram:shorty.o
</pre>

It will appear as if nothing happens - but at least it happens very quickly. However, something did happen. shorty.o was identified as an executable program and loaded into memory where the cpu instruction execution sequence passed to it. As mentioned above, the single '''blr''' instruction in this program caused the instruction execution sequence to pass directly back to where it was called from - in this case, the shell.

It may be of interest to know that all PPC instructions are four bytes long. In PPC nomenclature, this length is known as a word. But let's take a moment to have a look at the size of shorty.o

Enter this into the shell window:

<pre>
list ram:shorty.o
</pre>

2660 bytes?! But this is typical for object files as they contain much additional information that is used in the process of debugging and linking. Linking, particularly with a few key options, will generate an executable that is noticeably smaller.

Try entering this into the shell window:

<pre>
vlink -b elf32morphos -s -x -o ram:shorty ram:shorty.o

list ram:shorty
</pre>

The newly generated executable is 328 bytes - much smaller than it's object file but what are those other 324 bytes doing there? They are the ELF 'container' that holds the single, four byte instruction of shorty. ELF stands for Executable and Linkable Format and it is used by MorphOS, AmigaOS4 and AROS - not to forget, Linux, UNIX, BSD and even video game consoles. There is abundant information about this file format online but this topic will be discussed a little further when the use of the objdump program is introduced.

==The Old And The New==

Generally, in order to make a program that does something useful or to at least produce an observable result, it is necessary to use operating system library functions. Despite the markedly different cpu family that MorphOS runs on compared to the 68k family used by the classic AmigaOS, MorphOS is largely compatible with AmigaOS. This compatibility is reflected in a very similar API shared with AmigaOS and extends to using a MorphOS system structure as if it were the internal data and address registers of an actual 68k processor. This is called the EmulHandle structure and it is always available through the PPC GPR2 register. Also, as with 68k AmigaOS, the address of the Exec library base is always to be found at memory location 4. Many aspects of the AmigaOS API fit closely to the features available in the 68k cpu and the following code comparison should illustrate how it is echoed in the PPC MorphOS API.

A common task performed during the initialisation of many programs - opening the Dos Library. It is a particularly simple example of library usage but most functions follow this form.

[[File:Old-and-new.png]]

@ha & @l are needed to specify the high and low halfwords of 32 bit immediate values because the fixed 32 bit size of PPC instructions does not allow enough space for an instruction opcode and additional 32 bits of data.

One could be forgiven for thinking that the PPC code snippet looks a little ungainly compared to the former. Whereas every PPC instruction is four bytes long, 68k instructions can be as little as two bytes but up to as many as ten. A single 68k instruction can load a value from a 32 bit memory address specified by one instruction operand and store it at another 32 bit memory address specified by the second instruction operand. The 68k can also perform other operations beyond simple loads and stores directly on memory. Or at least appear to... In truth, computer memory only sends and receives data - no other data processing (like adding, subtracting & etc) occurs in memory. While the 68k instruction '''add.l #$12345678,(a0)''' appears to add the immediate value of it's first operand to whatever may already be stored at the address pointed to by a0, the contents of that address are actually loaded from memory into a private work register, the addition is performed and then the result is stored back to the same memory location. So this instruction actually performs two memory accesses where it might appear that there was only one. Contrast this with PPC assembly programming where memory loads and stores are all done explicitly. Before data can be operated upon it must be loaded from memory into a GPR (General Purpose Register), zero (in the case of a simple memory copy) or more operations can then be performed and then the data may be stored back to memory.

Unless you are brand-spanking-new to the topic of PPC assembly, you will already know that the PPC has 32 GPRs - r0 through r31. But did you know that the desired use of these registers is set out in something called the System V.4 ABI which MorphOS adheres to?

<pre>
r0 - volatile
r1 - stack pointer
r2 - for system use (with MorphOS, r2 points to the EmulHandle structure)

r3 - initialised with a pointer to a Dos command buffer
r4 - initialised with the length of the Dos command buffer
r5 - initialised with a pointer to an ELF structure

r3 ... r10 volatile & can be used to pass function arguments. If more
arguments are required, the stack is used.

r11 & r12 - volatile

r13 - small data area pointer. If this register is needed by a function or
subroutine, it must be saved first and then restored before
returning to where it was called from.

r14 ... r31 - No predefined purpose. If these registers are needed by a
function or subroutine, they must be saved first and then restored
before returning to where it was called from.
</pre>

The above use of the word 'volatile' means that functions are not expected to preserve the contents of these registers. r1 & r2 are the only registers that must be restored to their initial values by a terminating program, however, while most programs will modify r1 and later restore it, it is best to have not modified r2 in the first place.

This System V.4 ABI also sets out a particular way for programs and subroutines to organise their stack frames. When a program is loaded into memory and the instruction execution sequence passes to it, the stack pointer is still pointing to the calling program's stack frame and there is also an important address stored in the Link Register at this time. Unless this program is very simple (like shorty) it must save the Link Register address and, most likely, create it's own stack frame. Somewhat conveniently, there is a special position in the caller's stack frame that a callee program can save the contents of the Link Register to. This is a fairly common example of a program or subroutine's very first instructions.

[[File:Awkward-program-initialisation.png]]

Uh indeed... Let's try to visualise some memory being used as stack space.

[[File:Stack-diagram16.png]]

Note that '''stwu r1,-8(r1)''' creates a two-word stack frame which is the smallest stack that a program or subroutine can have if it, in turn, calls another program, subroutine or library function. More often, a larger stack frame is created although, '''stwu r1,-4(r1)''' could be used by a program or subroutine to create a one-word stack frame but this would be redundant and such a program must not call any other program, subroutine or library function. Such a program would not need to store the value in the Link Register (LR) to prevent it from being overwritten by subsequent calls and can terminate and return to it's caller with a simple '''blr''' instruction - just like shorty does.

A further note about larger stack frames and appropriate stack sizes: For reasons relating to PPC architecture, it is a good idea to choose stack frame sizes that are multiples of 16 bytes.

This is a less common example of a program's first instructions but it may better illustrate how to use stack frames.

[[File:Program-initialisation.png]]

Let's jump ahead and look at the last few instructions involved in program termination that would 'undo' the above instructions.

[[File:Program-termination.png]]

==A Little Less Talk And A Little More Action Please==

It's time to compile another program - this one will actually do something.

But wait...

Not another 'Hello World' program... I'm afraid so. This time, copy and paste is probably quicker. ''A fully commented version will be made available for download soon.''

Note that this example does not use the MorphOS SDK. Instead, some 'quick and dirty' methods are used for the sake of simplicity and readability.

<pre>
# Various library function offsets
.set _LVOOpenLibrary,-552
.set _LVOCloseLibrary,-414
.set _LVOVPrintf,-954
.set _AbsExecBase,4

# EmulHandle structure (always pointed to by r2)
.set reg_d0,0
.set reg_d1,4
.set reg_d2,8
.set reg_d3,12
.set reg_d4,16
.set reg_d5,20
.set reg_d6,24
.set reg_d7,28
.set reg_a0,32
.set reg_a1,36
.set reg_a2,40
.set reg_a3,44
.set reg_a4,48
.set reg_a5,52
.set reg_a6,56
.set reg_a7,60
.set EmulCallDirectOS,100

# Stack frame offsets
.set stack_pos0_caller_stack,0
.set stack_pos1_callerLR,4
.set stack_pos2_ExecBase,8
.set stack_pos3_DosBase,12
.set new_4_word_stack,16

.text

mflr r0
stw r0,stack_pos1_callerLR(r1)
stwu r1,-new_4_word_stack(r1)

lis r3,dosName@ha
addi r3,r3,dosName@l
stw r3,reg_a1(r2)
li r3,0
stw r3,reg_d0(r2)
li r3,_AbsExecBase
lwz r3,0(r3)
stw r3,stack_pos2_ExecBase(r1)
stw r3,reg_a6(r2)
li r3,_LVOOpenLibrary
lwz r0,EmulCallDirectOS(r2)
mtctr r0
bctrl

cmpwi r3,0
beq exit

stw r3,stack_pos3_DosBase(r1)

lis r4,string1@ha
addi r4,r4,string1@l
stw r4,reg_d1(r2)
li r4,0
stw r4,reg_d2(r2)
stw r3,reg_a6(r2)
li r3,_LVOVPrintf
lwz r0,EmulCallDirectOS(r2)
mtctr r0
bctrl

lwz r3,stack_pos3_DosBase(r1)
stw r3,reg_a1(r2)
lwz r3,stack_pos2_ExecBase(r1)
stw r3,reg_a6(r2)
li r3,_LVOCloseLibrary
lwz r0,EmulCallDirectOS(r2)
mtctr r0
bctrl

li r3,0

exit: addi r1,r1,new_4_word_stack
lwz r0,stack_pos1_callerLR(r1)
mtlr r0
blr

.rodata

__abox__:

dosName:
.string dos.library

string1:
.string "Hello World\n"
</pre>

Save this source file as HelloWorld.p and open a shell window. Change directory to where HelloWorld.p was just saved and enter:

<pre>
vasmppc_std -Felf -o ram:hw.o HelloWorld.p
</pre>

Once again, because of the simplicity of this program, linking isn't necessary so just enter the following in the shell window:

<pre>
ram:hw.o
</pre>

Are you impressed? Feel free to modify, experiment with and improve this source code. A not-too-difficult challenge might be to change this program so that it prints the arguments given to it in the shell window - a number of small but significant changes would be needed to do this.

When choosing which registers to use in your own programs, be aware that use of r0 in some instruction operands will not always work as you might expect. In these instructions, the actual content of r0 is ignored and the result is based on the constant value zero instead. For example, imagine that r0 contains the value 100 and then this instruction is executed: '''addi r0,r0,50''' It looks like the result should be r0 = r0 + 50 = 150 The result will actually be r0 = 0 + 50 = 50 This may seem odd but, as long as the programmer is aware of it, it can be useful. A good PPC instruction reference manual will explain this, and many other things, in much greater detail. There are many of these reference documents available on the internet - this is one of them [http://www.freescale.com/files/product/doc/MPCFPE32B.pdf MPCFPE32B.pdf]

==MorphOS SDK, Objdump, ELFs & Sections==

In addition to installing vbcc, it is also recommended to install the [http://www.morphos-team.net/files/sdk-20100617.lha MorphOS SDK] and the [http://mail.pb-owl.de/~frank/vbcc/current/vbcc_target_ppc-morphos.lha vbcc MorphOS compiler target].

The installer script of the latter seems to expect that there is a pre-existing assign for include: and, if your system already assigns include: to somewhere, please skip over this next part.

What follows is my S:user-startup after the installation of vbcc, it's MorphOS compiler target and an additional assign that I made preceded by this comment -

;vbcc MorphOS target needs include: to be assigned to somewhere

<pre>
;
; MorphOS user-startup
;
; This script is executed on system boot by
; startup-sequence. You can make personal
; changes in here.
;
; $VER: user-startup 1.1
;

; Enable the following to mount the inet-handler. Note that TCP: allows
; easy access to internet, and allows scripts to listen for incoming
; connections. Some malware could abuse this.
;Mount TCP:
;BEGIN vbcc
assign >NIL: vbcc: mos26:vbcc
assign >NIL: C: vbcc:bin ADD
setenv VBCC vbcc:
;END vbcc

;vbcc MorphOS target needs include: to be assigned to somewhere
assign include: vbcc:targets/ppc-morphos/include

;BEGIN vbcc-ppc-morphos
assign >NIL: vincludemos: vbcc:targets/ppc-morphos/include
assign >NIL: vincludemos: include: add
assign >NIL: vlibmos: vbcc:targets/ppc-morphos/lib
;END vbcc-ppc-morphos
</pre>

As mentioned just before the previous source code example, some quick and dirty methods were used for the sake of simplicity and readability and this refers to the way library function offsets were established. This approach will quickly become detrimental as more offsets are added. There are a number of solutions to this problem but only one will be presented here and it involves the removal of the leading underscore character from function names and appending '@l' to the end so that, for example, '''li r3,_LVOOpenLibrary''' becomes '''li r3,LVOOpenLibrary@l'''. Assemble with vasm as before but note that the resulting object file is no longer executable. To make this object executable, vlink is needed.

<pre>
vlink -b elf32morphos -o <desired executable name> <existing object name> -lamiga
</pre>

In the above shell command, -lamiga refers to the libamiga.a file that vlink knows to look for in vlibmos: This file contains information used to resolve many library function names to numerical values. Note that any executable generated from the above vlink command will contain a lot of symbol information that, while potentially useful, increases the size of the executable. This can be avoided with a few additions to the above command.

<pre>
vlink -b elf32morphos -s -x -P__abox__ <desired executable name> <existing object name> -lamiga
</pre>

-s strip symbols from the output file 
-x discard local symbols from input file(s) 
-P<symbol> preserve this symbol 

For more information, please refer to the documentation for vlink and other programs installed with vbcc.

At this point it would be useful to have a number of freshly generated object files and executables to look at with objdump although any ELF can be used for this purpose.

''final part yet to come''

File:Program-termination.png

2010-11-24T13:58:39Z

AusPPC: diagram of commented PPC instructions for program termination

diagram of commented PPC instructions for program termination

File:Program-initialisation.png

2010-11-24T13:57:13Z

AusPPC: diagram of commented PPC instructions for early program initialisation

diagram of commented PPC instructions for early program initialisation

File:Stack-diagram16.png

2010-11-24T13:54:36Z

AusPPC: diagram of commented stack entries

diagram of commented stack entries

File:Awkward-program-initialisation.png

2010-11-24T13:52:19Z

AusPPC: diagram showing three, commented PPC instructions

diagram showing three, commented PPC instructions

File:Old-and-new.png

2010-11-24T13:28:53Z

AusPPC: diagram showing commented 68k and PPC instructions

diagram showing commented 68k and PPC instructions

Main Page

2010-11-24T13:07:19Z

AusPPC: /* Development */

__NOTOC__

<div id="siteLogo" style="float: right;"> </div>

<div style="font-size:162%; border:none; margin:0; padding:.1em; color:#274572;">Welcome to the MorphOS Library,</div>
<div style="top:+0.2em; font-size:95%;">the wiki based library of MorphOS related documentation.</div>
<div id="articlecount" style="width:100%; text-align:left; font-size:85%;">[[Special:Statistics|{{NUMBEROFARTICLES}}]] articles in [[English language|English]]</div>

Do you have suggestions or would like to contribute? Please contact: <div id="message2library"></div>

'''Important notes to editors:''' [[Basic Guidelines]] - [[List of Wanted Articles]]

==MorphOS - The Lightning OS==

* [[What is MorphOS?]]
* [[Hardware Platforms]]
* [[Installation]]
* [[Characteristic features]]
* [[MorphOS integration]]
* [[MorphOS Development]]
* [[Developer tools]]
* [[3D graphics]]
* [[Games]]
* [[MorphOS key applications]]
* [[Platform expansion]]
* [[Who needs MorphOS?]]
* [[Conclusions]]
* [[Useful links]]
* [[F.A.Q.]]
* [[Historical notes]]
* [[Contributors]]

==Articles==
The core of the MorphOS Library can be found here. Along with the provided manuals, there are several documents designed to help users get the most out of their MorphOS powered computer.

* [[Fundamentals of MorphOS]]
* [[Dictionary of Terms]]
* [[Shell Commands|Shell: Commands]]
* [[Pattern matching|Shell: Pattern Matching]]
* [[Volume Names]]

==Tutorials==
Welcome to the Tutorials section of the MorphOS Library. In this aisle of the library you can find examples and step by step instructions to help get the most out of your MorphOS experience.

*[[Modifying the User-Startup file]]
*[[Dual-boot MorphOS and MacOS X on a Mac Mini G4]]
*[[How to write Mails with SimpleMail]]
*[[MorphOS External USB Drive Backup Guide]]
*[[Scanning with SCANdal]]

==Development==
In the development section of the MorphOS Library, you can find a collection of helpful articles and tutorials focused on MorphOS software development.

*[[First steps in MorphOS programming]]
*[[Magic User Interface Programming]]
*[[In-depth: The New MorphOS Memory System]]
*[[Reggae: MorphOS multimedia framework]]
*[[An Introduction to MorphOS PPC Assembly]]

==Benchmarks, Reports & Reviews==
*[[jPV's MorphOS 2 Review]]

==Links==
The MorphOS Link Database is a collection of websites that are of interest to all current and potential future users of MorphOS. For easier navigation, we have separated the list of websites into multiple categories.

*[[Links#Community_Portals_.26_Forums|Community Portals]]
*[[Links#File_Repositories|File Repositories]]
*[[Links#Software|Software]]
*[[Links#Developers|Developers]]

==Work in Progress==
*[[ReTooled]]

File:Ruler1000px.gif

2010-11-24T07:58:51Z

AusPPC: Used to test width limit for images in library articles.

Used to test width limit for images in library articles.

"Hello world!" in MUI

2010-11-19T05:28:08Z

AusPPC: minor readability fixes

''Grzegorz Kraszewski''

[[File:helloworld.png|left]] This is the window of the example MUI application. It is very simple, it contains only one static text object and no gadgets, except for window border gadgets. Note that the number of gadgets on the right side of the window depends on user MUI settings. The source code of the application is very simple too and fits into 60 lines, including proper vertical spacing. It is cut in pieces in the article for better reading. A complete, ready to compile version [http://krashan.ppa.pl/morphzone_tutorials/helloworld_mui.c is available] too.

#include <proto/muimaster.h>
#include <proto/intuition.h>

Header files for ''muimaster.library'' and ''intuition.library'' are included. Note that these libraries will be [[MorphOS_API_and_Its_Organization#How_to_Use_a_Library_in_an_Application|opened and closed automatically]].

Object *App, *Win;

Global pointers for the application object and the window object. While using many global variables is considered inelegant, having globals for the most important objects is handy, especially in such a small project.

Object* build_gui(void)
{
App = MUI_NewObject(MUIC_Application,
MUIA_Application_Author, (ULONG)"Grzegorz Kraszewski",
MUIA_Application_Base, (ULONG)"HELLOWORLD",
MUIA_Application_Copyright, (ULONG)"© 2010 Grzegorz Kraszewski",
MUIA_Application_Description, (ULONG)"Hello World in MUI.",
MUIA_Application_Title, (ULONG)"Hello World",
MUIA_Application_Version, (ULONG)"$VER: HelloWorld 1.0 (16.11.2010)",
MUIA_Application_Window, (ULONG)(Win = MUI_NewObject(MUIC_Window,
MUIA_Window_Title, (ULONG)"Hello World",
MUIA_Window_RootObject, MUI_NewObject(MUIC_Group,
MUIA_Group_Child, MUI_NewObject(MUIC_Text,
MUIA_Text_Contents, (ULONG)"Hello world!",
TAG_END),
TAG_END),
TAG_END)),
TAG_END);
}

The above function creates the complete object tree for ''HelloWorld''. The master object is the ''Application'' class instance. It has a ''Window'' object. The window root is a ''Group'' object containing one ''Text'' object. The application object has 6 attributes working as descriptors used in different places in the system. They are not required for running the program, but help integrating it with the system. The meaning of these attributes is explained in the autodoc of ''Application'' class in the SDK. The rest of the attributes are self-explaining, please refer to the autodocs of respective MUI classes for details.

The function illustrates a typical way of creating a MUI interface. The complete object tree is created in one big ''MUI_NewObject()'' call containing nested sub-calls. The order of code execution is different to the order of reading. The most nested objects are created first and passed to constructors of their parents. The application object is created last. This way of creating the application also ensures automatic error handling. If any of constructors fails, it passes ''NULL'' to a parent constructor, making it fail too and then dispose all successfully constructed child objects. Finally the application constructor fails and returns ''NULL''. Then only two states of the application are possible: either the application is fully constructed, or it is not constructed at all. This behaviour greatly simplifies error handling.

void notifications(void)
{
DoMethod(Win, MUIM_Notify, MUIA_Window_CloseRequest, TRUE, App, 2,
MUIM_Application_ReturnID, MUIV_Application_ReturnID_Quit);
}

The next step is to make notifications. This simple program contains only one notification, which terminates the program after the window close gadget is clicked. MUI maps a left mouse button click on the gadget to a change of ''MUIA_Window_CloseRequest'' attribute. The notification target is the application, the ''MUIM_Application_ReturnID()'' method then passes the quit action identifier to the main loop.

void main_loop(void)
{
ULONG signals = 0;

set(Win, MUIA_Window_Open, TRUE);

while (DoMethod(App, MUIM_Application_NewInput, &signals) != MUIV_Application_ReturnID_Quit)
{
signals = Wait(signals | SIGBREAKF_CTRL_C);
if (signals & SIGBREAKF_CTRL_C) break;
}

set(Win, MUIA_Window_Open, FALSE);
}

The standard main loop has been discussed in the [[Event_Driven_Programming,_Notifications#The_Ideal_MUI_Main_Loop|previous chapter]]. The only addition is opening the window before the loop and closing it after.

int main(void)
{
App = build_gui();

if (App)
{
notifications();
main_loop();
MUI_DisposeObject(App);
}

return 0;
}

Finally, the main function of the program. It builds the object tree first and checks if it succeeded. In case of a fail, the program ends immediately. After all the objects are created, notifications are added and the program enters the main loop. When the loop finishes, the application object is disposed. It also disposes all its sub-objects.

Event Driven Programming, Notifications

2010-11-19T02:35:27Z

AusPPC: minor readability fixes

''Grzegorz Kraszewski''

==Event Driven Programming==

Event driven programming is the natural consequence of the invention and development of graphical user interfaces. Most traditional, command line programs work like a pipe: data are loaded, processed and saved. There is no, or limited user interaction (like adjusting processing parameters, or choosing an alternative path). A GUI changes all that. A GUI based program initializes itself, opens a window with some icons and gadgets, then '''waits''' for user actions. Fragments of the program are executed in response to user input, after an action is finished, the program goes back to waiting. This way the program flow is determined not by the code, but rather by input events sent to the program by the user via the operating system. This is the basic paradigm of event driven programming.

[[File:mzone_eventdriven_1.png|center]]

<center>''Fig. 1. Execution flow of an event driven program.''</center>

==Notifications in MUI==

There are two approaches to input event decoding in an event driven program: centralized and decentralized. Centralized decoding is programmed as a big conditional statement (a ''switch'' statement usually, or a long cascade of ''if'' statements) inside the main loop of the fig. 1. flowchart. Depending on the decoded event, subroutines performing requested actions are called. Decentralized input event decoding is a more modern idea. In this case, the GUI toolkit receives and handles incoming input events internally and maps them to attribute changes of GUI objects (for example, clicking with the mouse on a button changes its attribute to "pressed"). Then an application programmer can assign actions to attribute changes of chosen objects. This is done by creating '''notifications''' on objects.

MUI uses decentralized input event decoding. All input events are mapped to attribute changes of different objects. These are visible GUI gadgets (controls) usually, but some events may be mapped to attributes of a window object, or an application object (the last one has no visible representation). After creating the complete object tree, but before entering the main loop, the program sets up notifications, assigning actions to attribute changes. Notifications can also be created and deleted dynamically at any time.

A notification connects two objects together. The source object triggers the action after one of its attributes changes. The assigned action (method) is then performed on the target object. The notification is set up by calling the ''MUIM_Notify()'' method on the source object. Arguments of the method can be divided into the source part and the target part. The general form of the ''MUIM_Notify()'' call is shown below:

DoMethod(source, '''MUIM_Notify''', attribute, value, target, param_count, action, /* parameters */);

The first four arguments form the '''source''' part, the rest is the '''target''' part. The complete call can be "translated" to a human language in the following way:

<big><center>When the '''source''' object changes its '''attribute''' to the '''value''', perform '''action''' method on the '''target''' object with '''parameters'''.</center></big>

There is one argument not explained with the above sentence, namely ''param_count''. This is just the number of parameters following this argument. The minimum number of parameters is 1 (the action method identifier), there is no upper limit other than using common sense.

A notification is triggered when an attribute is set to a specified value. It is often useful to have a notification on '''any''' attribute change. A special value ''MUIV_EveryTime'' should be used as a triggering value in this case.

The target action of a notification can be any method. There are a few methods designed specifically to be used in notifications:

'''''MUIM_Set()''''' is another method for setting an attribute. It is used when a notification has to set an attribute on the target object. ''OM_SET()'' is not suitable for using in notifications because it takes a [[Taglists|taglist]] containing attributes to be set. This taglist cannot be built from arguments and must be defined separately. ''MUIM_Set()'' sets a single attribute to a specified value. They are passed to the method directly as two separate arguments. The example below opens a window when a button is pressed:

DoMethod(button, MUIM_Notify, MUIA_Pressed, FALSE, window, 3, MUIM_Set, MUIA_Window_Open, TRUE);

Those not familiar with MUI may ask why the triggering value is set as ''FALSE''. It is related to the default behaviour of button gadgets. The gadget triggers when the left mouse button is '''released''', so at the end of a click. The ''MUIA_Pressed'' attribute is set to ''TRUE'' when the mouse button is pushed down, and set to ''FALSE'' when the mouse button is released. Now it should be obvious why the notification is set to trigger at a ''MUIA_Pressed'' change to ''FALSE''.

'''''MUIM_NoNotifySet()''''' works the same as ''MUIM_Set()'' with one important exception. It does not trigger any notifications set on the target object when the attribute has changed. It is often used to avoid notification loops, not only in notification, but also standalone in the code.

'''''MUIM_MultiSet()''''' allows for setting the same attribute to the same value for multiple objects. Objects are specified as this method's arguments and the final argument should be ''NULL''. Here is an example, disabling three buttons after a checkmark is deselected:

DoMethod(checkmark, MUIM_Notify, MUIA_Selected, FALSE, application, 7, MUIM_MultiSet,
MUIA_Disabled, TRUE, button1, button2, button3, NULL);

What is interesting is that while the target notification object is completely irrelevant here, it must still be a valid object pointer. The application object is usually used for this purpose, or the notification source object.

'''''MUIM_CallHook()''''' calls an external callback function called a [[hook]]. It is often abused by programmers being reluctant to perform subclassing of standard classes, instead implementing program functionality as new methods. Calling a method from a notification is usually faster and easier (however, a hook needs some additional structures to be defined).

'''''MUIM_Application_ReturnID()''''' returns a 32-bit integer number to [[#The_Ideal_MUI_Main_Loop|the main loop]] of a MUI program. With this method MUI's decentralized handling of input events can be turned into a centralized one. MUI programming beginners tend to abuse this method and redirect all the event handling back to the main loop, putting a big ''switch'' statement there. While rather simple, this programming technique should be avoided in favour of implementing program functionality in methods. Adding code inside the main loop degrades the GUI responsiveness. The only legitimate use of ''MUIM_Application_ReturnID()'' is to return a special value ''MUIV_Application_ReturnID_Quit'' used for ending the program.

==Reusing Triggering Value==

When the action of a notification is to set an attribute in the target object, it is often desired to forward the triggering value to the target object. It is very easy, when the notification is set to occur on a particular value. Things change however, when the notification is set to occur on any value with ''MUIV_EveryTime''. A special value ''MUIV_TriggerValue'' may be used for this. It is replaced with the actual value of the triggering attribute at every trigger. Another special value, ''MUIV_NotTriggerValue'' is used for boolean attributes and is replaced by a logical negation of the current value of the triggering attribute.

The first example uses ''MUIV_Trigger_Value'', to display the value of a slider in a string gadget:

DoMethod(slider, MUIM_Notify, MUIA_Numeric_Value, MUIV_EveryTime, string, 3,
MUIM_Set, MUIA_String_Integer, '''MUIV_TriggerValue''');

The second example connects a checkmark with a button. When the checkmark is selected, the button is enabled. Deselecting the checkmark disables the button:

DoMethod(checkmark, MUIM_Notify, MUIA_Selected, MUIV_EveryTime, button, 3,
MUIM_Set, MUIA_Disabled, '''MUIV_NotTriggerValue''');

''MUIV_EveryTime'', ''MUIV_TriggerValue'' and ''MUIV_NotTriggerValue'' are defined as particular values in the 32-bit range. Because of this, it is impossible to set a notification on the value 1 233 727 793 (which is ''MUIV_EveryTime''). It is also impossible to set the value to a fixed number 1 233 727 793 (''MUIV_TriggerValue'') or 1 233 727 795 (''MUIV_NotTriggerValue'') using ''MUIM_Set()'' in a notification.

==Notification Loops==

There may be hundreds of notifications defined in a complex program. Changing an attribute may trigger a notification cascade. It is possible that the cascade contains loops. The simplest example of a notification loop is a pair of objects having notifications on each other. Let's assume there are two sliders which should be coupled together. It means moving one slider should move the other one as well. A set of two notifications can ensure this behaviour.

DoMethod(slider1, MUIM_Notify, MUIA_Numeric_Value, MUIV_EveryTime, slider2, 3,
MUIM_Set, MUIA_Numeric_Value, MUIV_Trigger_Value);
DoMethod(slider2, MUIM_Notify, MUIA_Numeric_Value, MUIV_EveryTime, slider1, 3,
MUIM_Set, MUIA_Numeric_Value, MUIV_Trigger_Value);

When the user moves ''slider1'' to value 13, the first notification triggers and sets ''slider2'' value to 13. This triggers the second notification. Its action is to set ''slider1'' value to 13, which in turn triggers the first notification again. Then the loop triggers itself endlessly... Or rather it would, if MUI had no anti-looping measures. The solution is very simple: '''if an attribute is set for an object to the same value as the current one, any notifications on this attribute in this object are ignored'''. In our example the loop will be broken after the second notification sets the value of ''slider1''.

==The Ideal MUI Main Loop==

The ideal main loop of a MUI program should contain almost no code inside. All actions should be handled with notifications. Here is the code of the loop:

ULONG signals = 0;

while (DoMethod(application, MUIM_Application_NewInput, (ULONG)&signals)
!= (ULONG)MUIV_Application_ReturnID_Quit)
{
signals = Wait(signals | SIGBREAKF_CTRL_C);
if (signals & SIGBREAKF_CTRL_C) break;
}

The variable ''signals'' contains a bit-mask of input event signals sent to the process by the operating system. Its initial value 0 just means "no signals". When the ''MUIM_Application_NewInput()'' method is performed on the application object, MUI sets signal bits for input events it expects in the ''signals'' variable. These signals are usually signals of application windows' message ports, where ''Intuition'' sends input events. Then the application calls the ''exec.library'' function ''Wait()''. Inside this function, the execution of the process is stopped. The process scheduler will not give any processor time to the process until one of the signals in the mask arrives. Other than input event signals set by MUI, only the system CTRL-C signal is added to the mask. Every well written MorphOS application should be breakable by sending this signal. It can be sent via the console by pressing the CTRL + C keys, or from tools like the TaskManager. When one of the signals in the mask arrives at the process, the program returns from ''Wait()''. If the CTRL-C signal is detected, the main loop ends. If not, MUI decodes the received input events based on its received signal mask, translates events to changes of attributes of relevant objects and performs the triggered notifications. All this happens inside the ''MUIM_Application_NewInput()'' method. Finally the signal mask is updated. If any notification calls the ''MUIM_Application_ReturnID()'' method, the identifier passed is returned as the result of ''MUIM_Application_NewInput()''. In the event of receiving the special value ''MUIV_Application_ReturnID_Quit'' the loop ends.

Any additional code inserted into the loop will introduce delay in GUI handling and redrawing. If a program does some processor intensive calculations, the best way to deal with them is to delegate them into a subprocess. Loading the main process with computational tasks may result in the program being perceived as slow and unresponsive to user actions.

Short BOOPSI Overview

2010-11-19T01:22:23Z

AusPPC: minor readability fixes

''Grzegorz Kraszewski''
==Object Oriented Programming==

Object oriented programming is a technique developed as a response to two trends in the computer market. The first one was increasing complexity of software. Management of a traditionally written codebase becomes harder when the code size increases. The second trend was the increasing popularity of graphical user interfaces, which meant the end of sequential execution of programs. Instead modern programs are '''event driven''', which means the flow of code execution is determined by external events (like user input) and is not known at the time of writing the program. Object oriented programming divides a program into a set of objects interacting with each other using well defined interfaces. Such a modularization simplifies the management of a software project and also fits naturally with the concept of modern graphical user interfaces. User controls (called "gadgets" in MUI) are just objects in the code and they interact with other objects representing user data.

This short introduction is not intended to be a complete lecture on object oriented programming. On the other hand no knowledge of any particular object oriented programming language is required to get familiar with BOOPSI. Usually the support for OOP techniques comes with a programming language, which is either designed for OOP (like C++, C# or Java) or has OOP support added in a more or less logical way (Objective C, PHP). This is not the case for BOOPSI and MUI however. In this case object oriented programming support comes from the operating system. BOOPSI and MUI can be used with any programming language, including traditional ones, for example C and even assembler.

The BOOPSI module is located in the ''intuition.library'', with some important functions being added from a statically linked ''libabox''. Its primary design goal was to build a framework for wrapping Intuition GUI elements in an object oriented interface. This approach was unfortunately not flexible enough, so MUI uses only the basic BOOPSI framework. This framework provides the four basic concepts of object oriented programming: '''classes''', '''objects''', '''methods''' and '''attributes'''. It also supports class inheritance. Because of its simplicity, BOOPSI is easy to understand and use, especially when compared to more sophisticated frameworks, like the one in the C++ programming language.

==Classes==

A class is the basic term of object oriented programming. It is the complete description of its objects, their attributes and methods. In the BOOPSI framework, a class consists of:
*An ''IClass'' structure. A pointer to this structure is used as a reference to the class. The ''IClass'' structure is defined in the ''<intuition/classes.h>'' system header file. There is also the ''Class'' type, which is the same as ''struct IClass''.
* A class dispatcher function. When an application calls a method on an object, the object's class dispatcher is called. The dispatcher checks the method's identifier and jumps to this method code. The dispatcher is usually implemented as a big ''switch'' statement. For simple classes, which implement only a few short methods, code of these methods is often placed inside ''case'' statements. Bigger classes have methods' code separated into functions placed outside of the dispatcher. As every method goes through a dispatcher, all BOOPSI methods are virtual in the C++ meaning. For this reason, calling a method in BOOPSI is usually slower than in C++.

A class defines a set of methods available for its objects (instances) by the set of ''case'' statements in the dispatcher. Object's attributes are set using the ''OM_SET()'' method and are gotten using ''OM_GET()''. The attributes may also be passed to the object constructor directly. The set of attributes for a class and applicability of the attributes are then defined by the source code of ''OM_NEW()'' (the constructor), ''OM_SET()'' and ''OM_GET()'' methods. There is no formal declaration of class. There is also no division between public and private methods and attributes. Some kind of formal declaration and levels of access may be imposed by putting every class in a separate source code file. An accompanying header file would contain definitions of method identifiers, attribute identifiers and method parameters structures, but only those considered "public". Private method identifiers should be defined inside the source code of the class, so they are not visible outside of the class source code.

A BOOPSI class can be shared between applications. All the MUI built-in classes are shared ones. The BOOPSI maintains a system-wide list of public classes (the list can be browsed with the ''Scout'' monitoring tool). Shared classes are identified by names. A part of the MUI standard classes is contained inside the main MUI library – ''muimaster.library''. The library adds these classes to the system list when opened for the first time. The rest of the MUI standard classes are stored on the system disk partition in the ''MOSSYS:Classes/MUI/'' directory. Additional third party classes may be placed in the ''SYS:Classes/MUI'' directory.

Shared classes use the MorphOS shared library framework, in other words a shared BOOPSI class is just a kind of shared library. The class adds itself to the public list of classes, when it is opened from disk. As such, a BOOPSI shared class should be opened with ''OpenLibrary()'' before use ([[MorphOS_API_and_Its_Organization#Manual_Library_Opening_and_Closing|see details]]), especially as BOOPSI classes are usually not included into the list of libraries opened automatically. '''This is not the case for MUI classes''' however. MUI shared classes can be used without opening them. It is explained below, in the [[Short_BOOPSI_Overview#MUI_Extensions_to_BOOPSI|MUI Extensions to BOOPSI]] section.

==Methods and Attributes==

====Methods====
Methods are just actions, which can be performed on an object. A set of available methods is defined by the object's class. Technically speaking, a method is a function called with an object as its parameter in order to change the object's state. In BOOPSI, methods are called using the ''DoMethod()'' call from ''libabox'':

result = DoMethod(object, method_id, ... /* method parameters */);
result = DoMethodA(object, method_struct);

The first, more popular form of the call just builds the method structure on the fly, from arguments passed to it. Any method structure always has the method identifier as the first field. The ''DoMethodA()'' call gets a pointer to the method structure, the structure is built by the application. The second form is rarely used. The number and meaning of parameters, as well as the meaning of the result are method specific. Comparison of executing a method with both forms of the call is given below:

struct MUIP_SomeMethod
{
ULONG MethodID;
LONG ParameterA;
LONG ParameterB;
};

DoMethod(object, MUIM_SomeMethod, 3, 7);

struct MUIP_SomeMethod mparams = { MUIM_SomeMethod, 3, 7 };
DoMethodA(object, &mparams);

The ''DoMethod()'' form is more convenient, so it is commonly used. MUI uses specific prefixes for all its structures and constants:
* '''''MUIM_''''' for method identifiers.
* '''''MUIP_''''' for method parameter structures.
* '''''MUIA_''''' for attribute identifiers.
* '''''MUIV_''''' for special, predefined attribute values.

The C types used in the method structure above may need some explanation. LONG is a 32-bit signed integer, ULONG is an unsigned one. Because the structure is usually built on the processor stack, all parameters are extended and aligned to 32 bits. Then every parameter in the structure must be defined either as a 32-bit integer or a pointer. Any parameter larger than 32 bits must be passed via pointer (for example double precision floats or strings).

====Setting an Attribute====

An object's attributes represent its properties. They are written and read using special methods, ''OM_SET()'' and ''OM_GET()'' respectively. This differs from most object oriented programming languages, where attributes (being implemented as an object's fields) are accessed directly. Manipulating attributes in BOOPSI is slower then, as it implies performing a method.

The ''OM_SET()'' method does not take a single attribute and its value, but a [[Taglists|taglist]] of them, so one can set multiple attributes at once. The setting of two attributes to an object may be done as follows:

struct TagItem attributes[] = {
{ MUIA_SomeAttr1, 756 },
{ MUIA_SomeAttr2, 926 },
{ TAG_END, 0 }
};

DoMethod(object, OM_SET, (ULONG)attributes);

However, this is cumbersome and the code is not easily readable. The ''intuition.library'' makes it easier by providing the ''SetAttrsA()'' function, which is a wrapper for the ''OM_SET()'' method. Using this function and the array defined above, one can write:

SetAttrsA(object, attributes);

It still requires definition of a temporary [[Taglists|taglist]], but the function also has a variadic (meaning it can take a variable number of arguments) form ''SetAttrs()'', which allows for building the taglist on-the-fly:

SetAttrs(object,
MUIA_SomeAttr1, 756,
MUIA_SomeAttr2, 926,
TAG_END);

This is not all however. Programmers are lazy and decided that in the common case of setting a single attribute, ''SetAttrs()'' is still too much typing. A common practice found in sources using MUI was to define an ''xset()'' or ''set()'' macro, which is now defined in the system headers, in the ''<libraries/mui.h>'' file.

#define set(object, attribute, value) SetAttrs(object, attribute, value, TAG_END)

Then, setting a single attribute can be coded as follows:

set(object, MUIA_SomeAttr1, 756);

The ''OM_SET()'' method returns the number of attributes applied to the object. If some attributes are not known to the object's class (and superclasses), they are not counted. This return value is usually ignored, it may be used for testing an attribute applicability.

MUI provides a few additional methods for setting attributes, namely ''MUIM_Set()'', ''MUIM_NoNotifySet()'' and ''MUIM_MultiSet()''. They are mainly used in [[Event_Driven_Programming,_Notifications#Notifications_in_MUI|notifications]].

====Getting an Attribute====

The ''OM_GET()'' method gets a single attribute from an object. There is no multiple attributes getting method. Its first, obvious parameter is the attribute identifier. The attribute value is not returned as the result of the method however. Instead the second parameter is a pointer to a memory area, where the value is to be stored. This allows for passing attributes larger than 32 bits, they are just copied to the pointed memory area. This only works for fixed size attributes. Text strings cannot be passed this way, so they are passed as pointers (a pointer to the string is stored at a place in memory pointed to by the second parameter of ''OM_GET()''). The three examples below demonstrate all three cases:

LONG value1;
QUAD value2; /* 64-bit signed integer */
STRPTR *value3;

DoMethod(object, OM_GET, MUIA_Attribute1, (ULONG)&value1); /* integer attr */
DoMethod(object, OM_GET, MUIA_Attribute2, (ULONG)&value2); /* fixed size big attr */
DoMethod(object, OM_GET, MUIA_Attribute3, (ULONG)&value3); /* string attr */

In cases when an attribute is returned by pointer, the data pointed to should be treated as read-only unless documented otherwise.

Similarly as for ''OM_SET()'', there is a wrapper function for ''OM_GET()'' in the ''intuition.library'', named ''GetAttr()''. This function unexpectedly changes the order of arguments: attribute identifier is the first, object pointer is the second. The three examples above may be written with ''GetAttr()'' as follows:

GetAttr(MUIA_Attribute1, object, &value1);
GetAttr(MUIA_Attribute2, object, (ULONG*)&value2);
GetAttr(MUIA_Attribute3, object, (ULONG*)&value3);

The third parameter, a storage pointer is prototyped as pointer to ULONG, so in the first example type casting is not needed.

The ''<libraries/mui.h>'' system header file defines a macro ''get()'', which reverses the order of the two first arguments of ''GetAttr()'' and adds the typecasting to ''ULONG*''. The order of arguments of ''get()'' is the same as for ''set()'', which helps to avoid mistakes. The third line of the above example may be rewritten with ''get()'' this way:

get(object, MUIA_Attribute3, &value3);

The most often used attributes are integers (32-bit or shorter) and strings. Both of them fit into a 32-bit variable, as strings have to be passed via pointers. Taking this into account, MUI programmers invented a function (sometimes defined as a macro), which just returns the attribute value instead of storing it at a specified address. The function is named ''xget()'' and works as shown below:

value1 = xget(object, MUIA_Attribute1);
/* MUIA_Attribute2 can't be retrieved with xget() */
value3 = (STRPTR)xget(object, MUIA_Attribute3);

The ''xget()'' function may be defined in the following way:

inline ULONG xget(Object *obj, ULONG attribute)
{
ULONG value;

GetAttr(attribute, object, &value);
return value;
}

The function is very simple and is compiled to a few processor instructions. That is why it is declared as ''inline'', which causes the compiler to insert the function's code in-place instead of generating a jump. This makes the code faster, albeit a bit bigger. Except for working only with 32-bit attributes, ''xget()'' also has the disadvantage of loosing the ''OM_GET()'' return value. The value is boolean and is ''TRUE'' if the object's class (or any of its superclasses) recognizes the attribute, ''FALSE'' otherwise. This value is usually ignored, but may be useful for scanning objects for supported attributes.

The ''xget()'' function is not defined in the system headers. It has been described here because of its common use in MUI applications. Its counterparts for bigger sized arguments may be defined if needed.

==Object Construction==

Having a class, the programmer can create an unlimited number of objects (instances) of this class. Every object has its own instance data area, which is allocated and cleared automatically by the BOOPSI. Of course only object data are allocated for each instance. The code is not duplicated, so it must be reentrant (static variables and code self-modification must not be used).

Objects are created and disposed with two special methods: the constructor, ''OM_NEW()'' and the destructor, ''OM_DISPOSE()''. Of course the constructor method cannot be called on an object, because it creates a new one. It needs a pointer to the object's class instead, so it cannot be invoked with ''DoMethod()''. The ''intuition.library'' provides ''NewObjectA()'' and ''NewObject()'' functions for calling the constructor. The difference between them is that ''NewObjectA()'' takes a pointer to a [[Taglists|taglist]] specifying initial values for objects. ''NewObject()'' allows the programmer to build this taglist from a variable number of function arguments.

''NewObject[A]()'' has two alternative ways of specifying the created object's class. Private classes are specified by pointers of ''Class'' type. Shared classes are specified by name, which is a null-terminated string. If the pointer is used for class specification, the name should be NULL, if a name is used, the pointer should be ''NULL''. Four examples below show creating instances of private and public class with both ''NewObjectA()'' and ''NewObject()'':

Object *obj;
Class *private;

struct TagItem initial = {
{ MUIA_Attribute1, 4 },
{ MUIA_Attribute2, 46 },
{ TAG_END, 0 }
};

A private class, NewObjectA():

obj = NewObjectA(private, NULL, initial);

A private class, NewObject():

obj = NewObject(private, NULL,
MUIA_Attribute1, 4,
MUIA_Attribute2, 46,
TAG_END);

A public class, NewObjectA():

obj = NewObjectA(NULL, "some.class", initial);

A public class, NewObject():

obj = NewObject(NULL, "some.class",
MUIA_Attribute1, 4,
MUIA_Attribute2, 46,
TAG_END);

''NewObject[A]()'' returns ''NULL'' in case of an object creation failure. Usual reasons are: wrong class pointer/name, lack of free memory, wrong/missing initial values of attributes. The return value of ''NewObject[A]()'' should always be checked in the code.

==Object Destruction==

The ''OM_DISPOSE()'' method is used to destroy an object. Unlike ''OM_NEW()'' the destructor may be invoked with ''DoMethod()'':

DoMethod(object, OM_DISPOSE);

The ''intuition.library'' has a wrapper for this however, named ''DisposeObject()'':

DisposeObject(object);

==MUI Extensions to BOOPSI==

The Magic User Interface not only builds on BOOPSI but also extends it. Other than providing a broad set of classes, MUI also modifies the BOOPSI mode of operation a bit. Two modifications are discussed in this chapter: extension of the ''IClass'' structure and MUI's own functions for object construction and destruction.

MUI uses the ''MUI_CustomClass'' structure for its internal class representation. This structure contains the standard ''Class'' structure inside. It is important when creating objects from MUI private classes with ''NewObject()'', that the ''Class'' structure must be extracted from the ''MUI_CustomClass'' structure:

struct MUI_CustomClass *priv_class;
Object *obj;

obj = NewObject('''priv_class->mcc_Class''', NULL, /* ... */ TAG_END);

MUI's second modification of BOOPSI is using its own functions for object construction and destruction, ''MUI_NewObject[A]()'' and ''MUI_DisposeObject()'' respectively. These two functions are used '''only''' for objects of MUI shared (public) classes. Objects of private classes are created with ''NewObject()'' as shown above. The main advantage of ''MUI_NewObject()'' is automatic opening and closing of disk based shared classes. Here is an example:

Object *text;

text = MUI_NewObject(MUIC_Text, MUIA_Text_Contents, "foobar", TAG_END);

'''MUIC_Text'' is a macro defined in ''<libraries/mui.h>'' and it expands to "Text.mui" string. All MUI public classes should be referenced by their ''MUIC_'' macros rather than by direct string literals. It helps to detect mistyped class names, as a typo in a macro will be detected during compilation. The MUI checks if a class named ''Text.mui'' has been added to the public list of classes. If not, the class is found on disk, opened and used for creating the requested object. Closing the class when no longer in use is handled automatically too. All MUI objects should be disposed using ''MUI_DisposeObject()'', which takes the object to be disposed as its only argument, the same as ''DisposeObject()''.

MUI_DisposeObject(text);

Short BOOPSI Overview

2010-11-05T23:33:58Z

AusPPC: Spelling and grammar fixes - some of which I introduced...

''Grzegorz Kraszewski''
==Object Oriented Programming==

Object oriented programming is a technique developed as a response to two trends in the computer market. The first one was increasing complexity of software. Management of a traditionally written codebase becomes harder when the code size increases. The second trend was the increasing popularity of graphical user interfaces, which meant the end of sequential execution of programs. Instead modern programs are '''event driven''', which means the flow of code execution is determined by external events (like user input) and is not known at the time of writing the program. Object oriented programming divides a program into a set of objects interacting with each other using well defined interfaces. Such a modularization simplifies the management of a software project and also fits naturally with the concept of modern graphical user interfaces. User controls (called "gadgets" in MUI) are just objects in the code and they interact with other objects representing user data.

This short introduction is not intended to be a complete lecture on object oriented programming. On the other hand no knowledge of any particular object oriented programming language is required to get familiar with BOOPSI. Usually the support for OOP techniques comes with a programming language, which is either designed for OOP (like C++, C# or Java) or has OOP support added in a more or less logical way (Objective C, PHP). This is not the case for BOOPSI and MUI however. In this case object oriented programming support comes from the operating system. BOOPSI and MUI can be used with any programming language, including traditional ones, for example C and even assembler.

The BOOPSI module is located in the ''intuition.library'', with some important functions being added from a statically linked ''libabox''. Its primary design goal was to build a framework for wrapping Intuition GUI elements in an object oriented interface. This approach was unfortunately not flexible enough, so MUI uses only the basic BOOPSI framework. This framework provides the four basic concepts of object oriented programming: '''classes''', '''objects''', '''methods''' and '''attributes'''. It also supports class inheritance. Because of its simplicity, BOOPSI is easy to understand and use, especially when compared to more sophisticated frameworks, like the one in the C++ programming language.

==Classes and Objects==

====Classes====

A class is the basic term of object oriented programming. It is the complete description of its objects, their attributes and methods. In the BOOPSI framework, a class consists of:
*An ''IClass'' structure. A pointer to this structure is used as a reference to the class. The ''IClass'' structure is defined in the ''<intuition/classes.h>'' system header file. There is also the ''Class'' type, which is the same as ''struct IClass''.
* A class dispatcher function. When an application calls a method on an object, the object's class dispatcher is called. The dispatcher checks the method's identifier and jumps to this method code. The dispatcher is usually implemented as a big ''switch'' statement. For simple classes, which implement only a few short methods, code of these methods is often placed inside ''case'' statements. Bigger classes have methods' code separated into functions placed outside of the dispatcher. As every method goes through a dispatcher, all BOOPSI methods are virtual in the C++ meaning. For this reason, calling a method in BOOPSI is usually slower than in C++.

A class defines a set of methods available for its objects (instances) by the set of ''case'' statements in the dispatcher. Object's attributes are set using the ''OM_SET()'' method and are gotten using ''OM_GET()''. The attributes may also be passed to the object constructor directly. The set of attributes for a class and applicability of the attributes are then defined by the source code of ''OM_NEW()'' (the constructor), ''OM_SET()'' and ''OM_GET()'' methods. There is no formal declaration of class. There is also no division between public and private methods and attributes. Some kind of formal declaration and levels of access may be imposed by putting every class in a separate source code file. An accompanying header file would contain definitions of method identifiers, attribute identifiers and method parameters structures, but only those considered "public". Private method identifiers should be defined inside the source code of the class, so they are not visible outside of the class source code.

A BOOPSI class can be shared between applications. All the MUI built-in classes are shared ones. The BOOPSI maintains a system-wide list of public classes (the list can be browsed with the ''Scout'' monitoring tool). Shared classes are identified by names. A part of the MUI standard classes is contained inside the main MUI library – ''muimaster.library''. The library adds these classes to the system list when opened for the first time. The rest of the MUI standard classes are stored on the system disk partition in the ''MOSSYS:Classes/MUI/'' directory. Additional third party classes may be placed in the ''SYS:Classes/MUI'' directory.

====Objects====

==Methods and Attributes==

====Methods====
Methods are just actions, which can be performed on an object. A set of available methods is defined by the object's class. Technically speaking, a method is a function called with an object as its parameter in order to change the object's state. In BOOPSI, methods are called using the ''DoMethod()'' call from ''libabox'':

result = DoMethod(object, method_id, ... /* method parameters */);
result = DoMethodA(object, method_struct);

The first, more popular form of the call just builds the method structure on the fly, from arguments passed to it. Any method structure always has the method identifier as the first field. The ''DoMethodA()'' call gets a pointer to the method structure, the structure is built by the application. The second form is rarely used. The number and meaning of parameters, as well as the meaning of the result are method specific. Comparison of executing a method with both forms of the call is given below:

struct MUIP_SomeMethod
{
ULONG MethodID;
LONG ParameterA;
LONG ParameterB;
};

DoMethod(object, MUIM_SomeMethod, 3, 7);

struct MUIP_SomeMethod mparams = { MUIM_SomeMethod, 3, 7 };
DoMethodA(object, &mparams);

The ''DoMethod()'' form is more convenient, so it is commonly used. MUI uses specific prefixes for all its structures and constants:
* '''''MUIM_''''' for method identifiers.
* '''''MUIP_''''' for method parameter structures.
* '''''MUIA_''''' for attribute identifiers.
* '''''MUIV_''''' for special, predefined attribute values.

The C types used in the method structure above may need some explanation. LONG is a 32-bit signed integer, ULONG is an unsigned one. Because the structure is usually built on the processor stack, all parameters are extended and aligned to 32 bits. Then every parameter in the structure must be defined either as a 32-bit integer or a pointer. Any parameter larger than 32 bits must be passed via pointer (for example double precision floats or strings).

An object's attributes represent its properties. They are written and read using special methods, ''OM_SET()'' and ''OM_GET()'' respectively. This differs from most object oriented programming languages, where attributes (being implemented as an object's fields) are accessed directly. Manipulating attributes in BOOPSI is slower then, as it implies performing a method.

====Setting an Attribute====

The ''OM_SET()'' method does not take a single attribute and its value, but a [[Taglists|taglist]] of them, so one can set multiple attributes at once. The setting of two attributes to an object may be done as follows:

struct TagItem attributes[] = {
{ MUIA_SomeAttr1, 756 },
{ MUIA_SomeAttr2, 926 },
{ TAG_END, 0 }
};

DoMethod(object, OM_SET, (ULONG)attributes);

However, this is cumbersome and the code is not easily readable. The ''intuition.library'' makes it easier by providing the ''SetAttrsA()'' function, which is a wrapper for the ''OM_SET()'' method. Using this function and the array defined above, one can write:

SetAttrsA(object, attributes);

It still requires definition of a temporary [[Taglists|taglist]], but the function also has a variadic (meaning it can take a variable number of arguments) form ''SetAttrs()'', which allows for building the taglist on-the-fly:

SetAttrs(object,
MUIA_SomeAttr1, 756,
MUIA_SomeAttr2, 926,
TAG_END);

This is not all however. Programmers are lazy and decided that in the common case of setting a single attribute, ''SetAttrs()'' is still too much typing. A common practice found in sources using MUI was to define an ''xset()'' or ''set()'' macro, which is now defined in the system headers, in the ''<libraries/mui.h>'' file.

#define set(object, attribute, value) SetAttrs(object, attribute, value, TAG_END)

Then, setting a single attribute can be coded as follows:

set(object, MUIA_SomeAttr1, 756);

The ''OM_SET()'' method returns the number of attributes applied to the object. If some attributes are not known to the object's class (and superclasses), they are not counted. This return value is usually ignored, it may be used for testing an attribute applicability.

MUI provides a few additional methods for setting attributes, namely ''MUIM_Set()'', ''MUIM_NoNotifySet()'' and ''MUIM_MultiSet()''. They are mainly used in [[notifications]] and are discussed in the [[Notifications|relevant chapter]].

====Getting an Attribute====

The ''OM_GET()'' method gets a single attribute from an object. There is no multiple attributes getting method. Its first, obvious parameter is the attribute identifier. The attribute value is not returned as the result of the method however. Instead the second parameter is a pointer to a memory area, where the value is to be stored. This allows for passing attributes larger than 32 bits, they are just copied to the pointed memory area. This only works for fixed size attributes. Text strings cannot be passed this way, so they are passed as pointers (a pointer to the string is stored at a place in memory pointed to by the second parameter of ''OM_GET()''). The three examples below demonstrate all three cases:

LONG value1;
QUAD value 2; /* 64-bit signed integer */
STRPTR *value3;

DoMethod(object, OM_GET, MUIA_Attribute1, (ULONG)&value1); /* integer attr */
DoMethod(object, OM_GET, MUIA_Attribute2, (ULONG)&value2); /* fixed size big attr */
DoMethod(object, OM_GET, MUIA_Attribute3, (ULONG)&value3); /* string attr */

In cases when an attribute is returned by pointer, the data pointed to should be treated as read-only unless documented otherwise.

Similarly as for ''OM_SET()'', there is a wrapper function for ''OM_GET()'' in the ''intuition.library'', named ''GetAttr()''. This function unexpectedly changes the order of arguments: attribute identifier is the first, object pointer is the second. The three examples above may be written with ''GetAttr()'' as follows:

GetAttr(MUIA_Attribute1, object, &value1);
GetAttr(MUIA_Attribute2, object, (ULONG*)&value2);
GetAttr(MUIA_Attribute3, object, (ULONG*)&value3);

The third parameter, a storage pointer is prototyped as pointer to ULONG, so in the first example type casting is not needed.

The ''<libraries/mui.h>'' system header file defines a macro ''get()'', which reverses the order of the two first arguments of ''GetAttr()'' and adds the typecasting to ''ULONG*''. The order of arguments of ''get()'' is the same as for ''set()'', which helps to avoid mistakes. The third line of the above example may be rewritten with ''get()'' this way:

get(object, MUIA_Attribute3, &value3);

The most often used attributes are integers (32-bit or shorter) and strings. Both of them fit into a 32-bit variable, as strings have to be passed via pointers. Taking this into account, MUI programmers invented a function (sometimes defined as a macro), which just returns the attribute value instead of storing it at a specified address. The function is named ''xget()'' and works as shown below:

value1 = xget(object, MUIA_Attribute1);
/* MUIA_Attribute2 can't be retrieved with xget() */
value3 = (STRPTR)xget(object, MUIA_Attribute3);

The ''xget()'' function may be defined in the following way:

inline ULONG xget(Object *obj, ULONG attribute)
{
ULONG value;

GetAttr(attribute, object, &value);
return value;
}

The function is very simple and is compiled to a few processor instructions. That is why it is declared as ''inline'', which causes the compiler to insert the function's code in-place instead of generating a jump. This makes the code faster, albeit a bit bigger. Except for working only with 32-bit attributes, ''xget()'' also has the disadvantage of loosing the ''OM_GET()'' return value. The value is boolean and is ''TRUE'' if the object's class (or any of its superclasses) recognizes the attribute, ''FALSE'' otherwise. This value is usually ignored, but may be useful for scanning objects for supported attributes.

The ''xget()'' function is not defined in the system headers. It has been described here because of its common use in MUI applications. Its counterparts for bigger sized arguments may be defined if needed.

==Object Construction and Destruction==