This chapter contains the following sections:
Introduction
Basic Assembly, Linking and Locating of an XA Program
Using EDE
Using the Control Program
Using the Makefile
Environment Variables
Temporary Files
Debugging with CrossView Pro
File Extensions
Preprocessing
Assembler Listing
Errors and Warnings
Command Line Processing
Batch Files
UNIX Scripts
TASKING offers a complete toolchain for the 80C51XA microcontroller and its derivatives. This manual uses 'XA' as a shorthand notation for the 80C51XA microcontroller and its derivatives.
The XA cross-assembler package produces load files running on the XA. The assembler asxa accepts programs written according to the assembly language specification for the XA.
The assembler generates relocatable object files in the IEEE-695 object format. This file format specifies code parts as well as symbol definition and symbolic debug information parts. The locator optionally produces absolute output files in Motorola S-file format or Intel Hex format. You can load these formats into a PROM programmer.
The product contains the following programs:
ccxa A handy control program which activates the other programs depending on its input files.
mppxa An Intel compatible string-macro preprocessor allowing macro substitution, file inclusion and conditional assembly, according to the Macro Preprocessor Language described in the chapter Utilities. It is recommended that you use the internal preprocessor of the assembler asxa. Preprocessor mppxa is supplied for those who need a Intel MPL compatible preprocessor syntax.
asxa The assembler program which produces a relocatable object file from a given assembly file.
lkxa A linker combining several objects and object libraries into one target load file.
lcxa A locator that links a number of linker output files to one absolute load file. This program can also produce files in the Motorola S-file format or the Intel Hex format.
arxa An IEEE archiver. This is a librarian facility, which can be used to create and maintain object libraries.
prxa An IEEE object reader. This utility dumps the contents of IEEE files which have been created by a tool from the TASKING XA toolchain.
The XA assembler package is part of a toolchain that provides an environment for modular program development and debugging.
Figure 1-1: XA development flow
This section illustrates the typical input format of an XA assembly program for the cross-assembler. As a part of the installation a directory examples\asm (examples/asm for UNIX) is created depending on the place where you installed the package on your system. This example directory contains, among others, the following assembly source files:
Note that this program has been written for illustrative purposes only.
EDE stands for "Embedded Development Environment" and is the Windows oriented Integrated Development Environment you can use with your TASKING toolchain to design and develop your application.
To use EDE on the calc demo program in the subdirectory asm in the examples subdirectory of the XA product tree follow the steps below.
A detailed description of the process using the sample program calc.c is described below. This procedure is outlined as a guide for you to build your own executables for debugging.
The dialog boxes shown in this manual serve as an example. They may slightly differ from the ones in your product.
You can launch EDE by double-clicking on the EDE shortcut on your desktop.
The EDE screen provides you with a menu bar, a ribbon bar (command buttons) and one or more windows (for example, for source files), a status bar and numerous dialog boxes.
EDE supports all the TASKING toolchains. When you first start EDE, the correct toolchain of the product you purchased is selected and displayed in the title of the EDE desktop window.
If you selected the wrong toolchain or if you want to change toolchains do the following:
1. Access the EDE menu and select the Select Toolchain... menu item. This opens the Select Toolchain dialog.
2. Select the toolchain you want. You can do this by clicking on a toolchain in the Toolchains list box and press OK.
If no toolchains are present, use the Browse... or Scan Disk... button to search for a toolchain directory. Use the Browse... button if you know the installation directory of another TASKING product. Use the Scan Disk... button to search for all TASKING products present on a specific drive. Then return to step 2.
Follow these steps to open an existing project:
1. Access the Project menu and select Set Current....
2. Select the project file to open. For the demo program select the file calc.pjt in the subdirectory asm in the examples subdirectory of the XA product tree. If you have used the defaults, the file calc.pjt is in the directory c:\cxa\examples\asm.
The next two steps are not needed for the demo program because the files startup.src, initseg.src and calc.src are already open. To load the file you want to look at:
1. In the Project menu click on Load files....
This opens the Choose Project Files to Edit dialog.
2. Choose the file(s) you want to open by clicking on it. You can select multiple files by pressing the <Ctrl> or <Shift> key while you click on a file. With the <Ctrl> key you can make single selections and with the <Shift> key you can select everything from the first selected file to the file you click on. Then press the OK button.
This launches the file(s) so you can edit it (them).
The next step is to compile the file(s) together with its dependent files so you can debug the application.
Steps 1 and 2 are optional. Follow these steps if you want to specify additional build options such as to stop the build process on errors and to select a command to be executed as foreground or background process.
1. Access the EDE menu and select the Build Options... menu item.
This opens the Build Options dialog.
If you set the Show command line options at the bottom of a tool tab check box EDE shows the command line equivalent of the selected tool option. You can get the same effect when you select the button left from the OK button in a tool options dialog.
2. Make your changes and press the OK button.
3. Select the EDE | Directories menu item and check the directory paths for programs, include files and libraries. You can add your own directories here, separated by semicolons.
4. Access the EDE menu and select the Scan All Dependencies menu item.
5. Click on the Execute 'Make' command button. The following button is the execute Make button which is located in the ribbon bar.
If there are any unsaved files, EDE will ask you in a separate dialog if you want to save them before starting the build.
Once the files have been processed you can inspect the generated messages in the Build tab:
TASKING program builder vx.y rz SN00000001-018 (c) year TASKING, Inc. Assembling initseg.src Assembling startup.src Assembling calc.src Linking to calc.out Creating IEEE-695 absolute file calc.abs
Once the files have been compiled, assembled, linked, located and formatted they can be executed by CrossView Pro.
To execute CrossView Pro:
1. Click on the Debug application button. The following button is the Debug application button which is located in the ribbon bar.
CrossView Pro is launched. CrossView Pro will automatically download the compiled file for debugging.
When you use CrossView Pro ROM for the first time, you must setup the communication parameters.
To set the communication parameters:
1. Select the File | Communication Setup... item from the menu. This option opens up the Emulator Communication Setup dialog box.
2. In this dialog you need to identify the COM port (probably COM1: or COM2:) and the baud rate (9600 for RISM).
3. Close the dialog box by clicking on the OK button.
You must tell CrossView Pro which program you want to debug. To do this:
1. Click on File in the menu bar and select the Load Symbolic Debug Info... item. This opens up the Load Symbolic Debug Info dialog box.
2. Click Load.
To view your source while debugging, the Source Window must be open. To open this window,
1. Click on View in the menu bar and select the Source->Source lines item.
Before starting execution you have to reset the target system to its initial state. The program counter, stack pointer and any other registers must be set to their initial value. The easiest way to do this is:
2. Click on Run in the menu bar and select the Program Reset item.
3. Again click on Run in the menu bar and now select the Animate item.
The program calc.abs is now stepping through the high level language statements. Using the Accelerator bar or the menu bar you can set breakpoints, monitor data, display registers, simulate I/O and much more. See the CrossView Pro Debugger User's Guide for more information.
When you first use EDE you need to setup a project space and add a new project:
1. Access the Project menu and select Project Space | New....
2. Give your project space a name and then click OK.
3. Click on the Add new project to project space button.
4. Give your project a name and then click OK.
The Project Properties dialog box then appears for you to identify the files to be added.
5. Add all the files you want to be part of your project. Then press the OK button. To add files, use one of the 3 methods described below.
The new project is now open.
6. Click Project | Load Files to open files you want on your EDE desktop.
EDE automatically creates a makefile for the project. EDE updates the makefile every time you modify your project.
1. Instead of invoking all the individual translation phases by hand, it is possible (and recommended) to use the control program ccxa, which calls all phases automatically:
ccxa -ihex -M -nolib startup.src initseg.src calc.src -o calc.hex
As you can see, you may enter multiple input files on the command line. Also, you may specify options and controls for the assembler, linker and locator together. The control program recognizes the options and controls and places them in the appropriate command when invoking the assembler, linker or locator. The control program is described in detail in Chapter 11, Utilities.
The -ihex option is the same as specifying -f3 to the locator and selects the Intel Hex format.
The -M option specifies to generate map files.
The -nolib option specifies not to link with the standard libraries.
The -o option specifies the name of the output file.
2. If you want to see how the control program calls the assembler, linker and locator, you can use the -v0 option or -v option. The -v0 option only displays the invocations without executing them. The -v option also executes them.
ccxa -ihex -M -nolib startup.src initseg.src calc.src -o calc.hex -v0
The control program shows the following command invocations without executing them (UNIX output):
XA control program vx.y rz SN00000000-018 (c) year TASKING, Inc. startup.src: + asxa startup.src -e -o startup.obj initseg.src: + asxa initseg.src -e -o initseg.obj calc.src: + asxa calc.src -e -o calc.obj + lkxa -e startup.obj initseg.obj calc.obj -dxa_t.dsc -ocalc.out -Ocalc + lcxa -e -f3 -M -ocalc.hex -dxa_t.dsc calc.out
The -e option removes output files after errors occur. The -O option of the linker specifies the basename of the map file. The -d option of the locator specifies the name of the locator description file: dx_t.dsc.
3. In step 2, the tools use temporary files for intermediate results. In this case the file calc.out will be removed afterwards. If you want to keep the intermediate files you can use the -tmp option. The following command makes this clear.
ccxa -ihex -M -nolib startup.src initseg.src calc.src -o calc.hex -v0 -tmp
This command produces the same output as in step two, but when you replace -v0 with -v (verbose execute) the file calc.out will remain present.
Assuming the program assembles successfully, the assembler produces the relocatable output modules, startup.obj, init.obj and calc.obj.
Linking and locating the program to absolute addresses is done by two programs: the linker combines objects into a relocatable file with the extension .out. The locator binds the program to absolute addresses. The linker takes a.out as the default name of the output file. If this name is not suitable, you can specify another filename with the -o option.
Due to the -M option, the linker produces the linker map file calc.lnl and the locator produces the locator map file calc.map.
Besides the output file produced by the linker, the locator takes a so-called description file as input. This file contains a description of the virtual and physical addresses of the program. The chapter Locator discusses the exact contents and layout of a description file.
The result of locator command is the absolute output file calc.hex. The -f3 option specifies that the output file is in Intel Hex format. The file calc.hex can be loaded into an EPROM programmer.
Programs are easier to maintain if they are broken down
into smaller functional units.
The subdirectories in the examples directory each contain a makefile which can be processed by mkxa. Also each subdirectory contains a readme.txt file with a description of how to build the example.
To build the calc demo example follow the steps below. This procedure is outlined as a guide for you to build your own executables for debugging.
1. Make the subdirectory asm of the examples directory the current working directory.
This directory contains a makefile for building the calc demo example. It uses the default mkxa rules.
2. Be sure that the directory of the binaries is present in the PATH environment variable.
3. Compile, assemble, link and locate the modules using one call to the program builder mkxa:
mkxa
This command will build the example using the file makefile.
To see which commands are invoked by mkxa without actually executing them, type:
mkxa -n
This command produces the following output:
XA program builder vx.y rz SN00000001-018 (c) year TASKING, Inc. ccxa -c -Wa-ga -l calc.src ccxa -c -Wa-ga -l startup.src ccxa -c -Wa-ga -l initseg.src ccxa -nolib calc.obj startup.obj initseg.obj
The -c option in the makefile is used to suppress the linking phase.
To remove all generated files type:
mkxa clean
This section contains an overview of the environment variables used by the XA toolchain.
Environment Variable | Description |
ASXAINC | Specifies an alternative path for include files for the assembler. |
CXAINC | Specifies an alternative path for #include files for the C compiler cxa. |
CXALIB | Specifies a path to search for library files used by the linker lkxa. See also the section Library Search Path in the chapter Linker. |
CCXABIN | When this variable is set, the control program, ccxa, prepends the directory specified by this variable to the names of the tools invoked. |
CCXAOPT | Specifies extra options and/or arguments to each invocation of ccxa. The control program processes the arguments from this variable before the command line arguments. |
LM_LICENSE_FILE | Identifies the location of the license data file. Only needed for hosts that need the FLEXlm license manager. |
PATH | Specifies the search path for your executables. |
TMPDIR | Specifies an alternative directory where programs can create temporary files. Used by cxa, ccxa, asxa, lkxa, lcxa, arxa. See also the next section. |
Table 1-1: Environment variables
The assembler, linker, locator and archiver may create temporary files. By default these files will be created in the current directory. If you want the tools to create temporary files in another directory you can enforce this by setting the environment variable TMPDIR.
PC:
set TMPDIR=c:\tmp
UNIX:
Bourne shell, Korn shell:
TMPDIR=\tmp ; export TMPDIR
csh:
setenv TMPDIR /tmp
Note that if you create your temporary files on a directory which is accessible via the network for other users as well, conflicts in the names chosen for the temporary files may arise. It is safer to create temporary files in a directory that is solely accessible to yourself. Of course this does not apply if you run the tools with several users on a multi-user system, such as UNIX. Conflicts may arise if two different computer systems use the same network directory for tools to create their temporary files.
To facilitate debugging, you can include symbolic debug information in the load file. During compilation of a high-level-language program, symbolic debug information must be retained that serves as input for the symbolic debugger (-g option). The compiler passes symbolic debug information to the assembler by generating SYMB assembler directives in the assembly source file. The assembler translates the SYMB directives to be included in the symbolic debug part of an IEEE-695 object file.
See the debugging controls DEBUG and LOCALS in the chapter Assembler Controls for more information on symbolic debugging of assembly programs.
The CrossView Pro debugger (XVW) accepts files with the IEEE-695 format. This is the default output format of the locator. So, you can directly load the file generated by the locator into the XVW debugger.
The simplest way to build this assembly program ready for debugging is:
ccxa -M -nolib startup.src initseg.src calc.src -o calc.abs
The result of this command is (output of -v0 option):
XA control program vx.y rz SN00000000-033 (c) year TASKING, Inc. startup.src: + asxa startup.src -e -o startup.obj initseg.src: + asxa initseg.src -e -o initseg.obj calc.src: + asxa calc.src -e -o calc.obj + lkxa -e -M startup.obj initseg.obj calc.obj -dxa_t.dsc -ocalc.out -Ocalc + lcxa -e -M -ocalc.abs -dxa_t.dsc calc.out
You can start the CrossView Pro debugger for debugging the absolute file calc.abs with:
xfwxa calc.abs
For more information on the debugger, see the XA CrossView Pro Debugger User's Guide.
Note that the debugger examples are installed in the subdirectory xvw of the examples directory.
Both files with extension .src and .asm can be used as input files for the assembler. Files with the extension .asm serve as input files for the macro preprocessor whereas files with the extension .src are output files of the string macro preprocessor or the C compiler. Actually, the assembler accepts files with any extension (or even no extension), but by adding the extension .src or .asm to assembler source files, you can recognize them more easily.
If you do not provide a filename extension the assembler will try:
1. the filename itself
2. the filename with .asm extension
3. the filename with .src extension
So,
asxa text
only has the same effect as
asxa text.asm
if the file text is not present. In this case, both these commands assemble the file text.asm and create a relocatable object module text.obj.
For compatibility with future TASKING Cross-Software the following extensions are suggested:
.asm input assembly
source file for mppxa
.src output from
the string macro preprocessor mppxa
or one of the C compilers / input for asxa
.obj relocatable
IEEE-695 object files
.a object
library files, output from arxa
.out relocatable
output files from lkxa
.dsc description
file, input for lcxa and CrossView Pro debugger
.abs absolute IEEE-695 output
files from lcxa
.hex absolute
Intel Hex output files from lcxa
.sre absolute
Motorola S-record output files from lcxa
.lst assembler
list file
.cal C functions
call tree
.lnl linker map
file
.map locator
map file
The assembler asxa has a built-in macro preprocessor. For a description of the possibilities offered by the macro preprocessor see the chapter Macro Operations.
The assembler generates a listing file by default. You can suppress the generation of a listing file with the -l option. (See also the -L option, for the listing options). As a result of the command:
asxa text.src
the listing file text.lst is created.
Any errors detected by the assembler are displayed in the listing file after the actual line containing the error is printed. If no listing file is produced, error messages are still displayed to indicate that the assembly process did not proceed normally.
This section contains a description of the use of DOS batch files and UNIX scripts. The use of Makefiles is explained in the chapter Utilities.
Batch files are a facility within DOS whereby one or more commands can be executed from within a file.
Assume that the following sequence of calls is frequently used:
ccxa -c ifile.src -o outfile.obj
The files ifile and outfile may vary from one call to the next. To reduce the number of calls you can make a batch file, for example, proj.bat. Note that whatever the batch file is called it must end with the file extension .bat. The file should contain:
ccxa -c %1.src -o %2.obj
On invocation %1 and %2 will be replaced by the first and second parameters after the batch file name. Using the name mentioned above (proj - note that the file extension .bat is not needed for invocation) the call becomes:
proj ifile outfile
DOS will return on the screen the actual command line executed, with all the parameters expanded to the values used.
Scripts are a facility within UNIX whereby one or more commands can be executed from within a file.
Assume that the following sequence of calls is frequently used:
ccxa -c ifile.src -o outfile.obj
The files ifile and outfile may vary from one call to the next. To reduce the number of calls you can make a script, for example, proj. The file should contain:
ccxa -c $1.src -o $2.obj
On invocation $1 and $2 will be replaced by the first and second parameters after the script file name. Using the name mentioned above (proj) the call becomes:
sh proj ifile outfile