PortAsm/68K for M·CORE®

Please note that PortAsm/68K for M·CORE is an older tool which is no longer supported. See here for our current range.

Technical Tips, Limitations & Known Bugs

PortAsm/68K for M·CORE can be used with a number of different source 680x0 assembler syntax conventions, together with several M·CORE toolsets. This page gathers together some tips to help deal with specific situations you might encounter. MicroAPL will update this page periodically, so please let us know of any mistakes or omissions. Also please tell us if you have experience of using PortAsm with other toolsets, or if you have tips to pass on to other users.

We have grouped information on this page as follows:

Tips for using different M·CORE toolsets

Other practical information

Diab Data assembler & linker

Select the -a diab option in PortAsm to generate code for the Diab assembler. There are no special options which you need to set for the Diab tools themselves; code translated by PortAsm should assemble without problems using the default assembler settings.

Source-level debugging on code assembled and linked using the Diab tools works very well. You should use the DWARF 1.1 debug format (this is the default, so you don't need to set any special options). Setting the PortAsm -sym option will cause PortAsm to generate the necessary debugging directives in the output code. You can test this out with SingleStep or GDB (see below).

We have encountered two problems when targeting the Diab tools (we tested using Version 4.3):

  1. The Diab assembler does not warn when it automatically outputs a literal table (i.e. constants and addresses accessed by the LRW and JSRI instructions). This can sometimes cause problems if the logic of your program depends on instructions being at particular locations (for example, jump table immediately following a particular instruction). PortAsm will ouput a .literals directive after the translation of each RTS instruction in order to reduce the impact of this problem; if it still occurs, you can include a .literals directive (inside an ASM...ENDASM section) to force the literal table to be flushed out at a point where you know it will not cause the program to fail.

  2. The Diab assembler can give spurious errors on certain instructions containing immediates which are forward references. For example, it fails on:

    movi r1,table_size

    where table_size is the difference between two labels defined later in the file. You may need to rearrange things to avoid the forward reference.

For more information, see the Diab Data site.

SingleStep (Software Development Systems, Inc)

SingleStep provides an excellent Background Debug Mode (BDM) debugging environment for code translated using PortAsm and assembled using (for example) the Diab assembler and linker. You need to remember to set the default directory in SingleStep to point at the '.lst' files which PortAsm produces (to do this, bring up the SingleStep Command window and use the cd command to set the directory. It is best to do this before using the File/Debug.. command to download the object code to your target board).

If the entry point of the code you are debugging is an assembler label (rather than a C 'main' function), you need to disable the 'Execute until main' checkbox in the File/Debug.. dialog box - otherwise SingleStep will keep trying to execute instructions waiting for a label called 'main' to be reached - which may be never!

For more information, see the Software Development Systems, Inc, site.

The Gnu assembler & linker

You need to set the PortAsm -a gnu option in order to generate code in the format expected by the Gnu assembler.

Source-level debugging on code assembled and linked using the Gnu tools can be done using either the DWARF 1.1 or DWARF 2.0 debug formats. Setting the PortAsm -sym option will cause PortAsm to generate the necessary debugging directives in the output code. However, different versions of the Gnu tools seem to default to different DWARF formats, and the Gnu command-line option for selecting the DWARF version don't seem to work in some versions. You must use the same DWARF format for PortAsm-translated code and any C files incorporated in your project. If in doubt, try translating with and without the -dwarf2 option selected.

We have encountered the following problems when targeting the Gnu tools (we tested with MTC Versions 4.3 and 4.5):

  1. The Gnu assembler does not warn when it automatically outputs a literal table (i.e. constants and addresses accessed by the LRW and JSRI instructions). This can sometimes cause problems if the logic of your program depends on instructions being at particular locations (for example, jump table immediately following a particular instruction). PortAsm will ouput a .literals directive after the translation of each RTS instruction in order to reduce the impact of this problem; if it still occurs, you can include a .literals directive (inside an ASM...ENDASM section) to force the literal table to be flushed out at a point where you know it will not cause the program to fail.

  2. The assembler sometimes seems to output literal tables too late, giving rise to offsets going out of range. Again, you can work round this by placing a .literals directive inside an ASM...ENDASM section earlier in the file.

  3. The Gnu assembler can give spurious errors on certain instructions containing immediates which are forward references, or backward references where the value depends on address alignment. For example, it fails on:

    movi r1,table_size

    where table_size is the difference between two labels defined later in the file. It also fails for backwards references if there is a .align directive between the labels. You may need to rearrange things to avoid the forward reference, or eliminate the .align directive.

You may find that debugging using the Gnu tools is much easier if you use the Cygnus InSight graphical front-end to GDB. This is available for free download via the Freescale's M·CORE site, and it seems to work well. However, as far as we have been able to determine, this front-end does not support ordinary console I/O from the M·CORE simulator, which limits its usefulness.

Metrowerks CodeWarrior

PortAsm will generate output in the Metrowerks format if you select the -a mwerks option. We tested with Version 1.0 of the M·CORE tools. No problems have been reported in this case. See the Metrowerks site for more information.

Running PortAsm under Microsoft Developer Studio (Visual C++)

Developer Studio can be used to host PortAsm (and also assemblers such as Diab Data's). This provides an integrated development enviroment where you can edit files, translate them, and assemble them under the control of the Developer Studio 'make' process. The Windows hosted version of PortAsm outputs error messages in the correct format for Developer Studio, so you can double-click on the file reference in the error message, and Developer Studio will automatically open the source file at the correct line.

To use PortAsm in this environment, you need to download the Windows version of PortAsm. This needs to be placed in a directory where it is in the execution path. You then run Developer Studio, and set up a new project (it's best to specify a Console Application type) in which you place your original 68K source files. You will need to specify a 'Custom Build Step' to cause Developer Studio to call PortAsm (and possibly the assembler) to handle the files.

For an illustration of this, see our Developer Studio screen shot which shows an example of setting up the custom build step.

The final stages of linking and downloading the assembled M·CORE files needs to be done outside Developer Studio. For example, you could run both Developer Studio and SingleStep on your development machine, and switch to SingleStep for linking, downloading and debugging.

Release History

Version 1.0.0 (9th November 1999)

Initial release.