This chapter contains the following sections:
Introduction
Basic Assembly and Linking of an 8051 Program
Using EDE
Using the Makefile
Environment Variables
Temporary Files
Formatting a File for a Debugger
File Extensions
Preprocessing
Assembler Listing
Error Messages
Symbolic Debugging
Command Line Processing
Batch Files
UNIX Scripts
The 8051 cross-assembler package can produce load files for running on the entire 8051 family.
The assembler asm51 accepts programs written according to the Intel assembly language specification for the 8051. A formatter enables the load file to be formatted into IEEE format ready for loading into a debugger. Another formatter enables the load file to be formatted into Intel Hex format ready for loading into an (E)PROM programmer, or into an emulator using a terminal emulation program.
The product contains the following programs:
mpp51 A string-macro preprocessor allowing macro substitution, file inclusion and conditional assembly, according to the Macro Preprocessor Language described in the chapter Macro Preprocessor.
asm51 The assembler program which produces an object file from a given assembly file.
link51 An overlaying linker which combines several object files and object libraries into one target load file.
xfw51 The 8051 CrossView Pro Debugger.
ar51 Librarian facility, which can be used to create and maintain object libraries.
dmp51 A utility program to report the contents of an object file.
ieee51 A program which formats files generated by the assembler to the IEEE format (used by a debugger).
ihex51 A program which formats files generated by the linker to Intel Hex Format Format.
omf51 A formatter to translate TCP a.out formatted files into absolute OMF51 format.
srec51 A program which formats files generated by the linker to Motorola S Format.
The ASM51-assembler package is part of a toolchain that provides an environment for modular program development and debugging. The following figure explains the relationship between the different parts of the TASKING 8051 toolchain:
Figure 1-1: 8051 development flow
This section illustrates the typical input format of an 8051 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 demo program in the subdirectory asm in the examples subdirectory of the 8051 product tree follow the steps below.
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 toolbar (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 have more than one TASKING product installed and you want to change toolchains, do the following::
1. From the Project menu, select Select Toolchain...
The Select Toolchain dialog appears.
2. Select the toolchain you want. You can do this by clicking on a toolchain in the Toolchains list box and click 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. From the Project menu, select Set Current ->.
2. Select the project file to open. For the demo program select the file asm.pjt in the subdirectory asm in the examples subdirectory of the 8051 product tree. If you have used the defaults, the file asm.pjt is in the directory c:\cc51\examples\asm.
The next two steps are not needed for the demo program because the files main.src, write.src and makefile are already open. To load the file you want to look at.
1. From the Project menu, select Load Files...
The Choose Project Files to Edit dialog appears.
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 click OK.
This launches the file(s) so you can edit it (them).
1. From the Project menu, select Directories....
The Directories dialog appears.
2. Check the directory paths for programs, include files and libraries. You can add your own directories here, separated by semicolons.
3. Click OK.
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 keep temporary files that are generated during a build.
1. From the Build menu, select Options...
The Build Options dialog appears.
2. Make your changes and press the OK button.
3. From the Build menu, select Scan All Dependencies.
4. Click on the Execute 'Make' command button. The following button is the execute Make button which is located in the toolbar.
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.yrz Build nnn SN 00000000 Assembling main.src Assembling write.src Linking to asm.out Creating IEEE-695 absolute file asm.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 toolbar.
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. From the File menu, select Communication Setup....
The Communication Setup dialog appears.
2. In this dialog you need to identify the COM port (probably COM1: or COM2:) and the baud rate (9600 for RISM).
3. Click OK to close the dialog.
You must tell CrossView Pro which program you want to debug. To do this:
1. From the File menu, select Load Symbolic Debug Info....
The Load Symbolic Debug Info dialog box appears.
2. Click Load.
To view your source while debugging, the Source Window must be open. To open this window,
1. From the View menu, select Source->Source lines.
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. From the Run menu, select Reset Target System.
To run your application step-by-step:
3. From the Run menu, select Animate.
The program message.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. From the File menu, select New Project Space...
The Create a New Project Space dialog appears.
2. Give your project space a name and then click OK.
The Project Properties dialog box appears.
3. Click on the Add new project to project space button.
The Add New Project to Project Space dialog appears.
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. From the Project menu, select Load Files... to open the 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.
The subdirectories in the examples directory each contain a makefile which can be processed by mk51. Also each subdirectory contains a readme.txt file with a description of how to build the example.
To build the asm 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 asm demo example. It uses the default mk51 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 mk51:
mk51
This command will build the example using the file makefile.
To see which commands are invoked by mk51 without actually executing them, type:
mk51 -n
To remove all generated files type:
mk51 clean
This section contains an overview of the environment variables used by the 8051 toolchain.
Environment Variable | Description |
ASMDIR | Specifies an alternative path for include files for the macro preprocessor mpp51. |
CC51INC | Specifies an alternative path for #include files for the C compiler cc51. |
CC51LIB | Specifies an alternative path for library files for the linker link51. |
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. |
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.
Before a file generated by the linker can be loaded into a debugger it must be in a suitable format. This format is known as IEEE-695. The 8051 Cross-Assembler package includes a utility program ieee51 which can format output files into this IEEE format.
The simplest call of this program follows; for a full description of ieee51 see the chapter Utilities.
ieee51 opprog3 opprog3.abs
The output file opprog3.abs can now be loaded into a debugger.
All the assembler source files so far have had the extension .src. Actually, the assembler accepts files with any extension (or even no extension), but by adding the extension .src to assembler source files, you can distinguish them easily.
If you do not provide a filename extension the assembler will try:Another reason for using the .src extension is that the assembler uses this extension by default if it is omitted. So,
asm51 write
has the same effect as
asm51 write.src
Both these commands assemble the file write.src and create a list file write.lst and a relocatable object module write.obj.
For compatibility with future TASKING Cross-Software the following extensions are suggested:
.asm input assembly
source file for mpp51
.src output from
the string macro preprocessor mpp51
or the C compiler / input for asm51
.obj relocatable
object files
.lib object
libraries files in archive format
.out relocatable
output files from link51
.abs absolute
IEEE-695 output files
.hex absolute
Intel Hex output files
.sre absolute
Motorola S-record output files
.lst assembler
list file
.l51 linker list
file
For a description of the possibilities offered by the string macro preprocessor see the chapter Macro Preprocessor. In this section we shall merely show how it can be used in conjunction with the assembler.
The program write.src does not need to be preprocessed using mpp51. We shall nevertheless use write.src file to demonstrate the use of the macro preprocessor. First the file write.src is renamed to write.asm.
The simplest call to mpp51 is:
mpp51 write.asm
The result of this command is that the file write.src will be created. The contents of this file will be the same as write.asm.
The assembler generates a listing file by default. As a result of the command:
asm51 write.src
the listing file write.lst is created. If a listing is not desired the NOPRINT control can be used. For example:
asm51 write.src NOPRINT
To redirect the listing information to another file the PRINT control is available. For example:
asm51 write.src PRINT(list.lst)
asm51 is a three-pass assembler. The listing file is generated in the last phase.
Error messages from the cross-assembler are sent to the standard error device and written in the list file. If severe errors occur in one of the first two passes the error messages only occur on the standard error device because the assembler aborts before the third pass. It may however be useful to have a (not yet complete) list file of these first phases with the error messages inserted on the place where they occurred. This can be done using the LISTALL control.
If this control is specified the assembler creates a listing file in every phase. If a phase ends successfully, the listing file will be overwritten in the next phase.
To facilitate debugging, the programmer can decide how much symbolic debugging information to include in the load file. The following categories of information are available:
1. PUBLIC names
2. local names
3. compiler generated names
4. names defined in ?SYMB directives
5. records for ?LINE and ?FILE directives
6. segment names
7. version information
Each category is associated with one bit of a 7-bit pattern; for a full description see the chapter Assembler Controls. By default all categories except compiler generated names are included in the load file, which is correct for user written assembly programs.
PL/M51 generated assembly source files contain the control DEBUGINFO( 0F9H ), which exports everything except compiler generated names and assembler local symbols.
In the following example we shall use DEBUGINFO, requesting that all possible information be generated.
asm51 write.src DEBUGINFO( 377O )
For more information, see the the debugging directives ?SYMB, ?LINE, ?FILE in the chapter Assembler Directives.
This section contains a description of the use of batch files and UNIX scripts. The use of Makefiles is explained in the chapter Utilities.
Batch files are a facility on the PC whereby one or more commands can be executed from within a file.
Assume that the following sequence of calls is frequently used:
mpp51 ifile.asm asm51 ifile.src LISTALL PRINT( listfile )
The files ifile and listfile vary from one call to the next. To reduce the number of calls, you can make a batch file, for example, proj51.bat. Note that whatever the batch file is called it must end with the file extension .bat. The file should contain:
mpp51 %1.asm asm51 %1.src LISTALL PRINT( %2 )
On invocation %1 and %2 will be replaced by the first and second parameters after the batch file name. Using the name mentioned above (proj51 - note that the file extension .bat is not needed for invocation) the call becomes:
proj51 ifile listfile
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:
mpp51 ifile.asm asm51 ifile.src LISTALL PRINT( listfile )
The files ifile and listfile vary from one call to the next. To reduce the number of calls, you can make a script, for example, proj51. The file should contain:
mpp51 $1.asm asm51 $1.src LISTALL PRINT( $2 )
On invocation $1 and $2 will be replaced by the first and second parameters after the script file name. Using the name mentioned above (proj51) the call becomes:
sh proj51 ifile listfile