PortAsm/68K for ColdFire Technical Notes

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


PortAsm/68K for ColdFire can be used with a number of different source 680x0 assembler syntax conventions, together with several ColdFire 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 ColdFire 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. (In order to ensure that only ColdFire instructions are produced by the assembler, you should make sure that DTARGET and DOBJECT are correctly set up for the ColdFire processor and environment you are using. We recommend using the ELF object file format.)

The only problem which has been reported is that, in Version 3.7a of the Diab tools, the assembler sometimes doesn't report overflow errors on branches which go out of range. We believe this problem has been fixed by Diab Data in Version 4.0 and later. (If you are using 3.7a, we recommend that you select the PortAsm options -branch_short_unsized and -branch_islands which should work around the problem).

Source-level debugging on code assembled and linked using the Diab tools and the ELF object-file format works very well. 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 (see below).

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 ColdFire 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.

At the time of writing, the ColdFire versions of the Gnu tools are fairly new, and so the information presented here may be subject to change. When testing against the Gnu assembler (Version 2.8.1), we found the following:

  1. You need to tell the Gnu assembler that you are generating code for ColdFire (use the -m5200 option). However, even if you do this, the assembler will sometimes generate long displacements in effective addresses, which are not valid for ColdFire. To get round this problem, set the -l ("use 1 word for refs to undefined symbols") and --disp-size-default-16 ("displacement with unknown size is 16-bits") options when assembling code translated using PortAsm.

  2. Do NOT set the --bitwise-or ("do not treat '|' as a comment character") option. When generating code for Gnu, PortAsm uses the '|' character for comments, and works around the fact that this clashes with bitwise-OR by a method which is too embarrassing to mention on a public web site.

  3. The Gnu tools can output the final object code in a number of formats (set using the OUTPUT_FORMAT command in the linker command file). We tested S-record, COFF, and IEEE formats, and all three worked correctly. However, we did encounter a problem with symbolic debugging using the Gnu tools together with SingleStep. With symbolic debugging enabled, SingleStep gave an error when loading the object files.

  4. Instead of using the default Gnu syntax styles (with % characters on the front of register names), you can also use the Gnu --mri option which causes it to expect input in the Microtec format. In this case, you need to select the PortAsm option -a mri. Symbolic debugging will be disabled in this mode.

The Mentor Graphics Microtec assembler & linker

PortAsm will generate output in the Microtec format if you select the -a mri option, ready for assembling using Microtec's ASMCF assembler. Although PortAsm-generated symbolic debugging directives are not supported with this option set, you can use Microtec's automatic source-level debugging on the translated assembler file (assembler option -g). This provides full source-level debugging without the need for PortAsm to insert extra debugging directives in the output files.

More information on the Microtec tools is available from Mentor Graphics Microtec Division.

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 ColdFire 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.

Known Bugs and Limitations in PortAsm/68K for ColdFire

These apply to Version 2.4.1

  1. The translation of rotate instructions such as ROL, ROR, ROXL and ROXR will not be correct for over-rotates (eg rotating a byte operand 20 times). It was felt that the extra code which we would have to generate to handle this (very unusual) case would impose too much of an overhead on the normal cases where the rotate count is less than or equal to the operand width.

  2. MOVEM.W will not be translated if the list of registers includes A7 or if no spare register is available. PortAsm will issue an error. You should be able to work around the problem by splitting the MOVEM into two or more instructions. (Note: This restriction applies only to word-size MOVEM instructions).

  3. Indirect jumps or calls where a spare register is required for the effective address will not translate (PortAsm gives an error). An example is: JSR ([A0]). The problem here is that PortAsm needs a spare register to represent the intermediate effective address, but has no opportunity to restore the register's correct value. You should be able to work around the problem by minor recoding.

  4. The option to optimize sequences of BCD instructions is recognized but the optimization is not currently implemented.

Bugs fixed and Changes in Version 2.4.1 (18th April 2001)

  1. Support for ColdFire version 4 core added. Some useful 680x0 instructions which are missing from the earlier ColdFire cores have been put back, and new MVS and MVZ instructions have been added and are used by PortAsm.

  2. Improved front-end support. The 'structured control' directives in Microtec and Motorola 68K source are now supported and emulation of the Gnu and Diab front-ends, macro-language and directives is now complete.