An Introduction to MorphOS PPC Assembly - Revision history

AusPPC: Fixed bad link to source archive.

2011-02-16T08:40:06Z

Fixed bad link to source archive.

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

2011-01-22T09:33:20Z

The __abox__ symbol was incorrectly defined in the source example.

AusPPC: /* The Old And The New */

2011-01-07T06:00:00Z

‎The Old And The New

AusPPC at 23:10, 6 January 2011

2011-01-06T23:10:03Z

AusPPC at 23:08, 6 January 2011

2011-01-06T23:08:00Z

AusPPC at 23:00, 6 January 2011

2011-01-06T23:00:16Z

AusPPC at 22:53, 6 January 2011

2011-01-06T22:53:37Z

AusPPC: Small addition to @ha @l explanation

2011-01-06T22:50:35Z

Small addition to @ha @l explanation

AusPPC at 22:01, 6 January 2011

2011-01-06T22:01:57Z

AusPPC at 21:58, 6 January 2011

2011-01-06T21:58:01Z

@@ Line 121: / Line 121: @@
 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].
+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.

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

@@ Line 64: / Line 64: @@
 [[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...
+<small>'''@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...  </small>
 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&nbsp;#$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.

@@ Line 299: / Line 299: @@
 </pre>
--s strip all symbols from the output file<br>
+'''-s''' strip all symbols from the output file<br>
--P<symbol> preserve this symbol<br>
+'''-P<symbol>''' preserve this symbol<br>
 For more information, please refer to the documentation for ''vlink'' and other programs installed with ''vbcc''.

@@ Line 244: / Line 244: @@
 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.
+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 -
+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''
@@ Line 281: / Line 281: @@
 </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.
+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.
+''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&nbsp;r3,_LVOOpenLibrary''' becomes '''li&nbsp;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.
+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&nbsp;r3,_LVOOpenLibrary''' becomes '''li&nbsp;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>
@@ Line 293: / Line 293: @@
 </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.
+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
+vlink -s -P__abox__ -o <desired executable name> <existing object name> -lamiga
 </pre>
@@ Line 302: / Line 302: @@
 -P<symbol> preserve this symbol<br>
-For more information, please refer to the documentation for vlink and other programs installed with vbcc.
+For more information, please refer to the documentation for ''vlink'' and other programs installed with ''vbcc''.

@@ Line 222: / Line 222: @@
 </pre>
-Save this source file as HelloWorld.s and open a shell window.  Change directory to where HelloWorld.s was just saved and enter:
+Save this source file as ''HelloWorld.s'' and open a shell window.  Change directory to where ''HelloWorld.s'' was just saved and enter:
 <pre>
@@ Line 236: / Line 236: @@
 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.
+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&nbsp;r0,r0,50''' It looks like the result should be r0&nbsp;=&nbsp;r0&nbsp;+&nbsp;50&nbsp;=&nbsp;150  The result will actually be r0&nbsp;=&nbsp;0&nbsp;+&nbsp;50&nbsp;=&nbsp;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]
+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&nbsp;r0,r0,50''' It looks like the result should be '''r0&nbsp;=&nbsp;r0&nbsp;+&nbsp;50&nbsp;=&nbsp;150'''  The result will actually be '''r0&nbsp;=&nbsp;0&nbsp;+&nbsp;50&nbsp;=&nbsp;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==

@@ Line 64: / Line 64: @@
 [[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.
+'''@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&nbsp;#$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.
@@ Line 95: / Line 95: @@
 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.
+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.
+'Uh?' indeed...  Let's try to visualise some memory being used as stack space.
 [[File:Stack-diagram16.png]]
-Note that '''stwu&nbsp;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&nbsp;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.
+Note that '''stwu&nbsp;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&nbsp;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.

@@ Line 34: / Line 34: @@
 </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 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
+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:
@@ Line 44: / Line 44: @@
 </pre>
-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.
+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:
@@ Line 54: / Line 54: @@
 </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 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==

@@ Line 22: / Line 22: @@
 </pre>
-This tells vasm to generate an ELF formatted object file called shorty.o in ram: from the shorty.s source file.
+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?==