Application Programming
There are several language options available for writing application programs for the Adapt9S12XDP module. One can use Assembler, C, Basic, Forth, or a combination of these. This section will list descriptions and hardware specific setup instructions for the various systems available. The choice of what to use is left to the user. Generally though it will be based on application requirements, budget, and what the programmer is familiar with or willing to learn.
Many of the language options available will require the use of uBug12 to program the generated S-records into the S12X Flash memory. uBug12 is also usful for real-time debugging when a BDM pod is not available. You can find instructions on how to download and use uBug12 at this URL:
http://www.technologicalarts.ca/shop/documentation/63-debugging-tools/171-ubug12je-user-manual.html
Keep in mind that there is a difference between a programming language and an Integrated Development Environment (IDE). An IDE combines several functions of the development process into one program. It can be designed to work with a specific language, like C or Forth. However the language does not define the IDE functionality. An IDE can include an editor, assembler, compiler, simulator, debugger, serial monitor interface or BDM pod interface, or some subset of these capabilities. It will depend upon the IDE. So review what each can do before choosing one to work with. An IDE can be useful because it can combine several development steps into one, or allow blending of the functions. (i.e. Source level debugging, or using both assembly and the featured language.)
Another important factor to remember are the differences between the S12X CPU and its predecessor, the HCS12. There is much software written for the HCS12, and you can still find many boards available that use the MC9S12DP256 processor, its most common variant. The two processors are code compatible, so it is theoretically possible to write code on for the HCS12 and have it run on the S12X. However there are some critical differences between the two environments. Here are a few of the more important ones:
- The HCS12 instruction set is a subset of the S12X. There are no Global addressing instructions, for example. You will need to review the Freescale manual on the S12X for a full list of the differences, as there are many new instructions.
- The HCS12 has no XGATE coprocessor.
- The HCS12 based hardware has registers that are not in the S12X, like INITEE, etc.
- The S12X has registers that are not in the HCS12, for example EPAGE and RPAGE which are used for accessing banked EEPROM and RAM respectively.
- The PPAGE register, which is used to select the Flash bank seen at $8000-$BFFF, has different allowed values. The HCS12 for the 256K Flash only allowed $30-$3F. The 512K S12X uses $E0-$FF instead.
What this means is that there are development environments available (IDE) and debugging tools that were written for the HCS12 and might be used for the S12X, but with limitations. The most obvious indication of this will be if the IDE or programming language states that it uses the as12 assembler, which was written for the HCS12, not the S12X. Debugging tools for the HCS12 will have to be considered carefully, as they may not be compatible enough to work with the S12X due to the hardware differences. Of course this also means that if you have to migrate code from the HCS12 to the S12X, you will need to check that the source is modified to take these differences into account.
To assist you in getting a better idea of what is available, here is a table of the major development platforms that are available, and that can be used to develop software for the Adapt9S12XDP:
| Language | Assembler | IDE | XGATE | Serial Com | BDM Com | Other | |
| CodeWarrior Special | C | S12X/XGATE | x | x | x |
32K for C | |
| CodeWarrior Pro | C | S12X/XGATE | x | x | x |
commercial product | |
| FIG-Forth | Forth | S12X/XGATE | x | ||||
| HSW12 | Assembler | S12X/XGATE | x | x | x | Linux |
|
| AsmIDE | Assembler | S12X/XGATE | x | x | |||
| MiniIDE | Assembler | as12 | x | x | limited assember | ||
| SBASIC | BASIC | as12 | limited assember | ||||
| GCC-Syncode | C | as12 | limited assember | ||||
| GCC-Eclipse | C | as12 | limited assember | ||||
| Imagecraft C | C | as12 | limited assember | ||||
| Cosmic C | C | S12X/XGATE | x | x | x | commercial product |
All of these will work with an assembler, and allow assembly code to be embedded within the language. The main difference will be in what assembler is used. There are several S12X/XGATE assemblers available that can be used to write software: Code Warrior from Freescale, Cosmic Software's cas12x (part of their C programming environment), and Dirk Heisswolf's HSW12. Each of these come with their own IDE programs as well. There are other assemblers that are compatible, but these were written for earlier processor versions in the HC12 line. As a result, they do not cover the full instruction set of the S12X, but only a subset of it, and are therefore not covered in detail here.
What follows are brief descriptions, and instructions where needed, for each of these development tools.
CodeWarrior
CodeWarrior is considered the industry standard, and is available in different suites from Freescale. Each suite has different capabilities and prices. The least expensive of these is the Special suite, and is available for free. Its main limitation is that it only allows C programs to compile to a maximum size of 32 KB. The assembler is not bound by this limitation though. On the other end of the suites is the Professional version. CodeWarrior includes an IDE and a simulator. You can find out more by visiting the Freescale site for CodeWarrior at:
http://www.freescale.com/webapp/sps/site/prod_summary.jsp?code=CW-HCS12X&fsrch=1
You will find a link on this page to download the Special suite of the software. The link will download an executable to run that does the actual installation. Please be aware that the file size is over 300 MB, so it is best to use the fastest network connection possible. However you can also order a CD to obtain the software.
Here are some other links for documentation to help get CodeWarrior up and running. This is a comprehensive, and therefore complex, package. Plan to spend some time learning how to use it.
CodeWarrior Documentation List
Quick Start Instructions
Compiler Documentation
CodeWarrior Development Tools Learning Center
If you plan on using CodeWarrior to do interactive debugging with your hardware, you will need a BDM pod that is compatible with CodeWarrior. It is not guaranteed to work with any BDM, nor will it work via a serial monitor interface. (Compatible BDM pods are listed in the Freescale documentation.) However it will generate S-records that can be programmed into a target module via the serial monitor and uBug12x.
Dirk Heisswolf's HSW12
This S12X/XGATE assembler is part of Dirk Heisswolf's HSW12 IDE. This is a freeware IDE and assembler available on the web. (The site is listed in the instructions to follow.) The main difference with this development platform from others is that it is designed to be run on Linux systems. The IDE is also designed to work with a BDM pod when loading and debugging programs. However the assembler itself can easily be made to run on Windows computers, with the additional installation of a Perl interpreter, which is also freely available.
Here are the instructions to install Dirk Heisswolf's assembler onto a Windows computer:
- Get the free ActiveState Perl executive installed. To do this, first go to the URL: http://www.activestate.com
- Under Community Tools, click on ActivePerl.
- On the next page that appears, click on the ActivePerl Download Now button.
- Choose to Save the file.
- After it is saved, then double click on the file to run it.
- You have to agree to the license to proceed.
- Standard settings work fine. Just click on Next each time it shows.
- The Perl interpreter is now installed on your computer.
- Get Dirk's freeware S12X assembler installed. To do this, go to his web site at: http://hotwolf.github.io/HSW12/hsw12asm.html
- Click on the Download link.
- Click on Save when prompted, and choose where to save the file.
- Once this file is saved, you will have to uncompress the archive. However, if you used IE to get the file, the file you get is also an archive! (If you use Firefox, you don't get this extra complication.)
- To uncompress this file, first rename it so it has a ‘.zip’ extension.
- Now decompress the zip archive.
- Take the folder that is created, called 'hsw12', and move it to the root directory of the C: drive.
To run the assembler, a DOS command window will have to be used. This can be done by going on your Windows system to the Start button, and clicking on Run under that. The command to run is 'cmd'. This will bring up a DOS window to type commands in. Here is an example of the command to run to use the assembler:
c:\Perl\bin\Perl.exe /hsw12/perl/hsw12asm.pl /MyProgram/Fconfig.asm -s19 -L /hsw12/perl
Note that there are no spaces used in the pathnames or filenames. If that was the case, that component would have to be enclosed in quotes. Complete pathnames have to be specified too for it to work. Therefore the command format used is cumbersome to type. To help make this process easier, an IDE like AsmIDE can be configured to do the command for us.
When using the HSW12 assembler, you will need to keep the following points in mind:
- The assembler likes code fields separated by the Tab character rather than by a space. This seems to be more an effect of using the ActiveState Perl interpreter than Dirk's assembler. Under certain circumstances, the assembler will flag a line as an error when the first character is a space rather than a tab, or when a space separate fields like label and instruction. I haven't spent time noting the exact circumstances of the effect. I just use tabs regardless now, and have not had a problem.
- Arithmetic expressions may have different rules of precedence than other assemblers. You need to specify parentheses for everything to make sure expressions get evaluated correctly. Evaluation seems to be right to left, whereas other assemblers may be left to right. The assembler is made to have the following precendence order: -/~, &, |, ^, >>, <<, *, /, %, +, -
- Comments after an instruction need to be prefixed by a semicolon, or they are considered part of the instruction. This also means that regardless of where a semicolon is in a line, it starts the comment section. Therefore the semicolon can't be part of of an instruction parameter like FCS ";CODE", where the programmer assumes the semicolon is supposed to be part of a string.
- If you need to use Indexed-indirect Program Counter Relative addressing, you will have to use the format [TARGET] for the instruction target address. Dirk does do offsets relative to the PC register, but uses this format to implement the PCR option seen in some other processor assemblers. So to do an indirect jump to an address held in memory location TARGET, the code will be: JMP [TARGET] ;Instruction is generated with offset relative to the PC register
- S2 records generated need to be checked carefully to make sure they are created to go into the correct place in memory. Using the ORG instruction can be tricky, and will produce bad results if not done correctly. Please read DIrk's comments on this thoroughly.
- The BRA instruction will change automatically to an LBRA instruction if the target address gets too far away. This is generally a good thing, but it does add two extra bytes to the code. So be aware of it if you end up needing to count bytes used by a routine. You can force the assembler not to switch to LBRA by prefixing the target address with the left angle bracket character "<".
- By default, the assembler assumes direct page addressing for addresses starting in $00xx. If you change the contents of the Direct Page register, you can let the assembler know about it with the SETDP directive. You can force direct addressing by prefixing the target address with the left angle bracket character "<".
Once you have an S-record generated, you can use uBug12x to program it into the S12x.
AsmIDE
AsmIDE is not an assembler, but an IDE that is capable of being adapted to using Dirk's HSW12 assembler. (It comes with the default as12 assembler, which is compatible with the S12X, but only implements a subset of the assembly code.) The install package for this IDE is available from several sites. The URLs are:
http://hcs12text.com/files/asmide340.zip
http://mamoru.tbreesama.googlepages.com/asmide340.zip
http://mamoru.tbreesama.googlepages.com/asmide-src.zip (This provides the source.)
To set this up to use the HSW12 assembler, you will first need to install the assembler and Perl interpreter as per the instructions previously provided in the HSW12 section. Next, download the AsmIDE zip file and extract the files into a directory created to contain them. You will find in your directory an executable called AsmIDE.exe.
Start the AsmIDE.exe program so it can be configured. Once the application window appears:
- Go on the Menu bar to View > Options. This will bring up a dialog box that sets the IDE options.
- Select the Assembler tab at the top.
- You will need to change one of the default CPU settings. Under 'Currently Selected Chip family' select 6808. The recommended tab to pick is '6808 Options', as this is hardly used now.
- For 'Full pathname of Assembler', enter: c:\Perl\bin\Perl.exe
- For 'Full pathname of helpfile..', enter: C:\hsw12\doc\hsw12.html
- The last text box on the dialog is for assembler switches. This should have: hsw12asm.pl % -L /hsw12/perl/ -s19
- You will need to have your source code located where the Perl assembler is, at: C:\hsw12\perl
Now you can use the IDE to create assembler source files. They can be assembled by going to Build > Assemble on the IDE. This will generate an S1 S-record that can be downloaded to the Adapt9S12XDP module via uBug12x.
MiniIDE
This is another IDE that comes with the older as12 assembler as its default, and so is compatible with the Adapt9S12XDP. However it can not be adapted to use one of the full S12X assemblers. Also, while it is designed to communicate with the target board via a serial port, it expects the target to be running DBUG12, not the serial monitor as is in the Adapt9S12XDP. Its description is included for completeness. It is located at URL:
SBASIC
The SBASIC language is a 'no line numbers' variation of BASIC, with a compiler that runs on Windows computers. It uses the older as12 assembler to generate object code, and therefore has its inherent limitations. You will have to download as12 and install it to use SBASIC. The URL for obtaining both SBASIC and the as12 code is:
http://www.seanet.com/~karllunt/sbasic.htm
Or if you prefer, here at the direct links:
SBASIC ZIP archive
as12 ZIP archive
Once this is extracted to its own directory, you will find within it the SBASIC compiler, called sbasic.exe. SBASIC is a command line run compiler. Typing the command by itself generates the following message, providing a summary of it's usage:
SBasic compiler (version 2.7) for the 68HC11/68HC12
usage: sbasic infile [options]
where infile is the name of an SBasic source file.
Input files have a .bas extension by default.
Output will be written to stdout.
Options are: /cxxxx /vxxxx /sxxxx /b /mxxxx /i
where xxxx is an address given as four hex digits.
/cxxxx sets first address of executable code
/vxxxx sets start of variables
/sxxxx sets top of return stack
/b generates branch opcodes, not jump opcodes
/mxxxx sets target MCU (6811 or 6812)
/i does not generate interrupt vector table
There are several sample programs included in the archive with SBASIC, along with a manual that explains its use in greater detail. You can pipe the output to a file that can be used by the assembler:
sbasic infile >outfile
You must specify options to have the program generate code that will work on the S12X, as the default values will not work. Read the manual for more information on the options for variable location, stack, etc. that must be configured.
Once SBASIC generates an assembly file, you will need to use as12 to parse that file. It in turn will generate an S-record that you can program into your target board. To start the as12 assembler, enter the following command at the prompt:
as12 file.ext
where file.ext is the path, name, and extension of the file you want to assemble, in this case the output saved from the sbasic command. The as12 assembler will assemble the file, sending the listing output to the console and writing the S19 object output to a file named m.out. You will want to then rename the m.out file to something ending in .s19 to load into the target system with uBug12x.
Please note that SBASIC and as12 by themselves do not do any hardware setup. It is up to you to write the code to set up the hardware.
SynCode and Eclipse GCC
The URL for these is:
Imagecraft C
Imagecraft C is a commercial product that supports the S12X and XGATE processors. It includes support for the NoICE12 debugger. You can download and use it for free during a 45 day trial period. The URL is:
Cosmic C Cross Development Environment
Cosmic C is a commercial product that includes their S12X assembler, called cas12x, and C compiler. XGATE capability is available as an add-on. They also have a full featured BDM source code debugger available, and full S12X/XGATE simulator. Their IDE is called IDEA. It is available in versions for both Windows and Linux based computers. The URL is:
http://www.cosmic-software.com/s12x_des.php
Forth
There is a freeware version of FIG-Forth available that was designed specifically with the Adapt9S12XDP module in mind. Forth provides the power of assembly, the compactness of compiled C, and an interactive environment to write and test code directly on the module. This capability does not exist with any of the other platforms mentioned. (They all require the program to be burned into Flash before you can test it on the module.) Because of this, the Flash will not be stressed nearly as much with erase-and-burn cycles as code is developed. The final result can be burned into Flash/EEPROM as an application that runs upon power-up of the board.
The FIG-Forth URL is: https://sites.google.com/site/mamorutbreesama/
The web site includes detailed instructions on installation and operation. The IDE that is included is designed to run on Windows computers, and uses Dirk Heisswolf's HSW12 assembler to assemble the Forth code. However if you do not need to modify the initial Forth kernel for your system then, technically, the assembler is not needed. The IDE also includes an S12X simulator, which allows binary object code to be tested before it is burned into Flash. The S2 S-record files generated are also directly compatible with the uBug12 program designed for use with the Adapt9S12XDP module.
