1 OVERVIEW

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

1.1 Introduction

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

1.2 Basic Assembly, Linking and Locating of an XA Program

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.

1.2.1 Using EDE

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.

How to Start EDE

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.

How to Select a Toolchain

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.

How to Open an Existing Project

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.

How to Load/Open Files

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

How to Build the Demo Application

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.

How to View the Results of a 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

How to Start the CrossView Pro Debugger

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.

How to Set the Communication Parameters of XVW-ROM

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.

How to Load an Application

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.

How to View and Execute an Application

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.

How to Start a New Project

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.2.2 Using the Control Program

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:

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.

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.

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.

1.2.3 Using the Makefile

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:

This command will build the example using the file makefile.

To see which commands are invoked by mkxa without actually executing them, type:

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:

1.3 Environment Variables

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

1.4 Temporary Files

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:

UNIX:

Bourne shell, Korn shell:

csh:

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.

1.5 Debugging with CrossView Pro

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:

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:

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.

1.6 File Extensions

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,

only has the same effect as

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

1.7 Preprocessing

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.

1.8 Assembler Listing

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:

the listing file text.lst is created.

1.9 Errors and Warnings

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.

1.10 Command Line Processing

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.

1.10.1 Batch Files

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:

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:

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:

DOS will return on the screen the actual command line executed, with all the parameters expanded to the values used.

1.10.2 UNIX Scripts

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:

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:

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:


Copyright © 2000 TASKING, Inc.