|
www.riscos.com Technical Support: |
ObjAsm is the ARM assembler forming part of the Acorn C/C++ product. It processes text files containing program source written in ARM assembly language into linkable object files. Object files can be linked by the Link tool with each other or with libraries of object files to form executable image files or relocatable modules. ObjAsm multitasks under the RISC OS desktop, allowing other tasks to proceed while it operates.
The sources for large programs can be split into several files, each of which only need be re-assembled to an object file when you have altered it.
An example use of ObjAsm would be to construct a binary image file !RunImage in a RISC OS desktop application from the two source files s.interface and s.portable. ObjAsm processes the source files to form o.interface and o.portable, which the Link tool processes to form !RunImage.
The controls of ObjAsm are similar to those of other non-interactive Desktop tools, with the common features described in the General features of the accompanying Desktop Tools guide. You adjust options for the next assembly operation on a SetUp dialogue box and menu which by default appear when you click Select on the main icon or drag a source file to it. Once you have set options you click on a Run action icon and the assembly starts. While the assembly is running output windows display any text messages from the assembler and allow you to stop the job if you wish.
There is no file type to double click on to start ObjAsm - it owns no file type unlike, for example, Draw.
Like other non-interactive Desktop tools, ObjAsm can be used under the management of Make, with its assembly options specified by the makefile passed to Make. For such managed use, ObjAsm is started automatically by Make; you don't have to load ObjAsm onto the icon bar.
To use ObjAsm directly, unmanaged by Make, first open a directory display on the AcornC_C++.Tools directory, then double click Select on !ObjAsm. The ObjAsm main icon appears on the icon bar:
Clicking Select on this icon or dragging an assembly language source file from a directory display to this icon brings up the ObjAsm SetUp dialogue box:
Source will appear containing the name of the last filename entered there, or empty if there isn't one.
Dragging a file on to the icon will bring up the dialogue box and automatically insert the dragged filename as the Source file.
Clicking Menu on the SetUp dialogue box brings up the ObjAsm SetUp menu:
The SetUp dialogue box and menu specify the next assembly job to be done. You start the next job by clicking Run on the dialogue box (or Command line menu dialogue box). Clicking Cancel removes the SetUp dialogue box and clears any changes you have just made to the options settings back to the state before you brought up the SetUp box. The options last until you adjust them again or !ObjAsm is reloaded. You can also save them for future use with an option from the main icon menu.
When the SetUp dialogue box is displayed the Source writable icon contains the name of the source file to be assembled. The sourcefile can be specified in two ways:
When the SetUp box appears the Source icon has input focus, and can be edited in the normal RISC OS fashion. If a further source file is selected in a directory display and dragged to Source, its name replaces the one already there.
The Include SetUp dialogue box icon adds directories to the source file search path so that arguments to GET/INCLUDE directives (see Links to other source files) do not need to be fully qualified. The search rule used is similar to the ANSI C search rule - the current place being the directory in which the current file was found.
The directories are searched in the order in which they are given in the Include icon.
The Throwback option switches editor throwback on (the default) or off. When enabled, if the DDEUtils module and SrcEdit are loaded, any assembly errors cause the editor to display an error browser. Double clicking Select on an error line in this browser makes the editor display the source file containing the error, with the offending line highlighted. For more details, see the chapter entitled SrcEdit of the accompanying Desktop Tools guide.
The Debug option switches on or off the production of debugging tables. When enabled, extra information is included in the output object file which enables source level debugging of the linked image (as long as Link's Debug option is also enabled) by the DDT debugger. If this option is disabled, any image file finally produced can only be debugged at machine level. Source level debugging allows the current execution position to be indicated as a displayed line of your source, whereas machine level debugging only shows the position on a disassembly of memory.
The ObjAsm RISC OS desktop interface works by driving an ObjAsm tool underneath with a command line constructed from your SetUp options. The Command line item at the top of the SetUp menu leads to a small dialogue box in which the command line equivalent of the current SetUp options is displayed:
The Run action icon in this dialogue box starts assembly in the same way as that in the main SetUp box. Pressing Return in the writable icon in this box has the same effect. Before starting assembly from the command line box, you can edit the command line textually, although this is not normally useful.
The next few entries in the SetUp menu all control the acceptable syntax for the Assembler:
No APCS registers specifies whether the variant of the ARM Procedure Call Standard used by RISC OS is in use, or the APCS is not in use at all. By default the APCS is in use, and ObjAsm pre-declares extra register names and variables, and also specifies some attributes of code areas:
When this menu option is chosen (i.e. it has a tick beside it), the APCS is not in use, and so the above points no longer hold.
You can specify other APCS variants using the -APCS option in the Others writable field at the bottom of the menu; see Specifying other command line options, and Command line options not available from the desktop.
C strings, when enabled, allows the assembler to accept C style string escapes such as '\n'. C strings is not enabled by default, as it results in '\' characters in string constants being interpreted in a different way compared to previous Acorn assemblers.
Upper case, when chosen, makes ObjAsm recognise instruction mnemonics only if they are entirely in upper case. By default, Upper case is not chosen, and ObjAsm recognises mnemonics that are entirely in upper or lower case (but not a mixture of both).
This option is provided mainly to support old code that might have used lower case versions of instruction mnemonics as macro names; it allows the macros to still be recognised as such.
CPU sets the target ARM core. Currently this can take the values ARM6, ARM7 and ARM7M, and defaults to ARM6. Some processor specific instructions will produce warnings if assembled for the wrong ARM core:
The next entry - Define - allows you to set an initial value for an assembler global variable:
You must give a valid variable name, followed by a SETL, SETA or SETS directive, followed by a value. The value may be a simple constant or a constant expression (in ObjAsm syntax) of appropriate type - logical, arithmetic or string for SETL, SETA and SETS respectively - provided that its value can be computed at the start of assembly. The variable is set as if the directive occurs before the start of the source; an implicit GBLL, GBLA or GBLS directive is also executed. In the case of SETS, quotation marks are usually necessary around the value, since it is a string expression.; these must be escaped by preceding each with a backslash ('\').
ObjAsm is a two pass assembler - it examines each source file twice. To avoid reading each source file twice from disk the assembler can cache the source in memory, reading it from disk for the first pass, then storing it in RAM for the second. This makes very heavy use of memory, and so is unsuitable for smaller machines.
The next two menu options control this cacheing:
NoCache disables cacheing when chosen, which is the default. When NoCache is switched off, cacheing is enabled.
MaxCache allows you to specify the maximum amount of RAM to be used for cacheing source files, provided that NoCache is off. The maximum cache is specified in megabytes; the default is 8MB:
The next menu options control handling of warnings and errors:
Suppress warnings, when chosen, turns off the warning messages that ObjAsm generates. It is off by default (i.e. warning messages are generated).
Errors to file allows you to specify a file to which error messages are output for later inspection:
The next options control whether or not a listing is produced, and its format:
The Listing option enables assembler source code to be sent to a file:
This option turns on the Assembler listing, and during assembly the source code, object code, memory addresses and reference line numbers will be sent to the named file. Listing is off by default.
NoTerse modifies the listing that is output, which normally only includes the conditionally assembled parts of your program. If you choose NoTerse, conditionally non-assembled parts are listed as well. NoTerse is off by default.
Width sets the width, in characters, of the listing that is output:
This should be between 1 and 254. The default width is 131; a width of 76 is suitable for a Mode 12 RISC OS window.
Length sets the number of lines per page for printer output. At the end of each page ObjAsm inserts a form feed character. The default length is 60:
If you choose Cross reference, then after assembly ObjAsm outputs an alphabetically sorted cross reference of all symbols encountered. Note that the text output may be very large for a big program, and so this option may not function on a machine with restricted memory. Cross reference is off by default.
Work directory allows you to specify the work directory:
The GET and LNK directives both result in the assembler loading source files specified with the directive. The work directory is the place where these source files are to be found. An example is a source file:
adfs::HardDisc4.$.Source.s.foo
containing the line:
GET s.macros
If the work directory is ^ then the file loaded is:
adfs::HardDisc4.$.Source.s.^.s.macros
(i.e. adfs::HardDisc4.$.Source.s.macros)
The work directory must be given relative to the position of the source file containing the GET or LNK, without a trailing dot.
The default work directory is ^.
The Others option on the SetUp menu leads to a writable icon in which you can add an arbitrary extra section of text to the command line to be passed to ObjAsm:
This facility is useful if you wish to use any feature which is not supported by any of the other entries on the SetUp dialogue box and menu. This may be because the feature is used very little, or because it may not be supported in the future.
For a full description of command line options, see ObjAsm command lines.
ObjAsm outputs text messages as it proceeds. These include source listings and symbol cross references (as described in the previous sections). By default any such text is directed into a scrollable output window:
This window is read-only; you can scroll up and down to view progress, but you cannot edit the text without first saving it. To indicate this, clicking Select on the scrollable part of this window has no effect.
The contents of the window illustrated above are typical of those you see from a successful assembly; the title line of the assembler with version number, followed by no error messages.
Clicking Adjust on the close icon of the output window switches to the output summary dialogue box. This presents a reminder of the tool running (ObjAsm), the status of the task (Running, Paused, Completed or Aborted), the time when the task was started, and the number of lines of output that have been generated (ie those that are displayed by the output window):
Clicking Adjust on the close icon of the summary box returns to the output window.
Both the above ObjAsm output displays follow the standard pattern of those of all the non-interactive Desktop tools. The common features of the non-interactive Desktop tools are covered in more detail in the General features of the accompanying Desktop Tools guide. Both ObjAsm output displays and the menus brought up by clicking Menu on them offer the standard features, which allow you to abort, pause or continue execution (if the execution hasn't completed), to save output text to a file, or to repeat execution.
ObjAsm error messages appear in the output viewer, with copies in the editor error browser when throwback is working. The Error messages of this manual contains a list of common ObjAsm error messages together with brief explanations.
Assembly listings and cross references appearing in the output window are often very large for assemblies of complex source files. The scrolling of the output window is useful to view them. To investigate them with the full facilities of the source editor, you can save the output text straight into the editor by dragging the output file icon to the SrcEdit main icon on the icon bar.
The ObjAsm main icon bar menu follows the standard pattern for non-interactive Desktop tools:
Save options saves all the current ObjAsm options, including both those set from the SetUp dialogue box and from the Options item on this menu. When ObjAsm is restarted it is initialised with these options rather than the defaults.
The Options submenu allows you to set the following options:
Clicking on Help on the main ObjAsm menu displays a short text summary of the various SetUp options, in a scrollable read-only window:
The programming example AcornC_C++.Examples.AsmHello is a non-desktop free standing command line program written in assembly language. It outputs the text 'Hello World'.
The assembly language source is held in the s subdirectory, in the file HelloW. The code demonstrates the ObjAsm directives needed for a free standing program;
To assemble HelloW, first run !Objasm and !Link by double clicking on them. Drag the HelloW source text file to the ObjAsm icon. The SetUp dialogue box of ObjAsm appears. Check that the default SetUp options are enabled:
Click on Run to proceed, and save the object file produced in the o subdirectory. Drag the object file to the Link icon, and Run Link to produce an AIF executable image file, the link having the HelloW object file as its only input file. Save the image file in AcornC_C++.Examples.AsmHello.!RunImage. The command line program is now ready for use.
To run the program under the desktop, double click on it. A window appears with the text 'Hello World':
As the window instructs you to do, press the space bar or click on your mouse. The window disappears.
ObjAsm, in common with the other non-interactive Desktop tools, can be driven with a text command line without its RISC OS desktop interface appearing. This enables ObjAsm to be driven by Make as specified in textual makefiles.
You can use ObjAsm outside the RISC OS desktop from its command line, in the same way that it could be used in the previous Acorn Desktop Assembler product. However, as all the useful ObjAsm features can be more conveniently used from the RISC OS desktop there is little reason for you to do this. The desktop removes the need for you to understand the command line syntax.
The ObjAsm RISC OS desktop interface drives the ObjAsm tool underneath by issuing a command line constructed from your SetUp options. The Command line SetUp menu option allows you to view the command line constructed in this way.
The Make tool allows you to construct makefiles with assembly operations specified using the ObjAsm desktop interface (by following the Tool options item of Make). You can therefore construct makefiles without understanding the command line syntax of ObjAsm.
The command to invoke ObjAsm takes either of the forms:
ObjAsm «options» sourcefile objectfile ObjAsm «options» -o objectfile sourcefile
The options are listed below, split into two sections: those for which there is a direct equivalent in the SetUp dialogue box or menu, and those others for which there is no equivalent. Upper case is used to show the allowable abbreviations. Note that to understand what many of these options do it may be necessary to refer to some of the documentation above.
The table below shows the various command line options that correspond to the options available from the SetUp dialogue box and menu, together with a reference to the desktop equivalent, which you should see for full details of the option:
| Command line option | Desktop equivalent |
|---|---|
| -I dir«,dir» | Include writable icon in dialogue box |
| -ThrowBack | Throwback option icon in dialogue box |
| -G | Debug option icon in dialogue box |
| (See -Apcs below) | No APCS registers in menu |
| -Esc | C strings in menu |
| -UpperCase | Upper case in menu |
| -CPU ARMcore | CPU in menu |
| -PreDefine directive | Define in menu |
| -NOCache | NoCache in menu |
| -MaxCache n | MaxCache in menu |
| -NOWarn | Suppress warnings in menu |
| -ERRors errorfile | Errors to file in menu |
| -LIST listingfile | Listing in menu |
| -NOTerse | NoTerse in menu |
| -WIdth n | Width in menu |
| -Length n | Length in menu |
| -Xref | Cross reference in menu |
| -Desktop dirname | Work directory in menu |
The table below shows those command line options for which there is no direct equivalent in the SetUp dialogue box or menu. Should you need to use any of these more esoteric options from the desktop, you can add them to the SetUp menu's Others option (see Specifying other command line options).
| Command line option | Description | |
|---|---|---|
| -Help | Outputs a summary of the command line options. | |
| -VIA filename | Reads in extra command line arguments from the given filename. | |
| -LIttleend | Assemble code suitable for a little-endian ARM, by setting the built-in variable {ENDIAN} to "little". | |
| -BIgend | Assemble code suitable for a big-endian ARM, by setting the built-in variable {ENDIAN} to "big". | |
| -Apcs option«/qualifier»«/qualifier...» | ||
| Specifies whether the ARM Procedure Call Standard is in use, and also specifies some attributes of CODE AREAs. By default the register names R0-R15, r0-r15, sp, SP, lr, LR, pc, and PC are pre-declared. If the APCS is in use the following register names are also pre-declared: a1-a4, v1-v6, sl, fp, and ip.
There are two APCS options: NONE and 3. The SetUp menu's No APCS registers option - when chosen - declares the APCS in use as NONE. The default behaviour is to use the 3/26bit/SWStackcheck APCS variant used by RISC OS The qualifiers - which should only be used with option 3 - are as follows: | ||
| /REENTrant | Sets the reentrant attribute for any code AREAs, and predeclares sb (static base) in place of v6. | |
| /32bit | Is the default setting and informs the Linker that the code being generated is written for 32 bit ARMs. The built-in variable {CONFIG} is also set to 32. | |
| /26bit | Tells the Linker that the code is intended for 26 bit ARMs. The built-in variable {CONFIG} is also set to 26.
Note that these options do not of themselves generate particular ARM-specific code, but allow the Linker to warn of any mismatch between files being linked, and also allow programs to use the standard built-in variable {CONFIG} to determine what code to produce. | |
| /SWSTackcheck | Marks CODE AREAs as using sl for the stack limit register, following the APCS (the default setting). | |
| /NOSWstackcheck | Marks CODE AREAs as not using software stack-limit checking, and predeclares an additional v-register, v6 if reentrant, v7 if not. | |
| -Depend dependfile | Saves source file dependency lists, which are suitable for use with 'make' utilities. | |
| -ABSolute | Accepts AAsm source code to provide some backwards compatibility in this release. See the chapter entitled Support for AAsm source. | |
| -FRom filename | Supported, for backward compatibility with previous release. | |
| -TO filename | Supported, for backward compatibility with previous release. | |
| Supported, for backward compatibility with previous release. | ||
| -Quit | Recognised but ignored, for backward compatibility with previous release. | |