//------------------------------------------------------------------------
//  Readme.txt
//------------------------------------------------------------------------
This project stationery is designed to get you up and running
quickly with CodeWarrior for MC9S12XDP512.
It is set up for the selected CPU and target connection,
but can be easily modified.

Sample code for the following language(s) is at your disposal:
- C

The wizard has prepared CodeWarrior target(s) with the connection methods of
your choice:
- Simulator:
  This interface/target is prepared to use the FCS (Full Chip Simulation).

- SofTec:
  This target interface connects to any of the USB-based SofTec Microsystems tools for HC(S)12.


Additional connections can be chosen in the simulator/debugger,
use the menu Component > Set Target.

//------------------------------------------------------------------------
//  Getting Started
//------------------------------------------------------------------------
To build/debug your project, use the menu Project > Debug or press F5.
This will open the simulator/debugger.
Press again F5 in the debugger (or menu Run > Start/Continue) to start
the application. The menu Run > Halt or F6 stops the application.
In the debugger menu Component > Open you can load additional components.

//------------------------------------------------------------------------
// Project structure
//------------------------------------------------------------------------
The project generated contains various files/folders:
- readme.txt: this file
- Sources: folder with the application source code
- Startup Code: C/C++ startup code (initializing stack pointer and doing
  global variable initialization). If you want to only do stack pointer
  initialization, add -D__ONLY_INIT_SP to the compiler command line.- Prm:
   - burner.bbl file to generate S-Records
   - the linker .prm file
- Linker Map: the .map file generated by the linker
- Libraries: needed library files (ANSI, derivative header/implementation files)
- Debugger Project File: contains a .ini file for the debugger for each
  connection
- Debugger Cmd Files: contains sub-folders for each connection with command
  files

//------------------------------------------------------------------------
//  Adding your own code
//------------------------------------------------------------------------
Once everything is working as expected, you can begin adding your own code
to the project. Keep in mind that we provide this as an example of how to
get up and running quickly with CodeWarrior. There are certainly other
ways to handle interrupts and set up your linker command file. Feel free
to modify any of the source files provided.

//------------------------------------------------------------------------
//  Changing the derivative
//------------------------------------------------------------------------
If you decided to use a derivative A during the project creation, but later you
would like to use a derivative B, you have to consider following points:
- You will need to adapt the CodeWarrior project settings: In the 'Assembler for
  HC12' and 'Compiler for HC12' panels make sure that the new CPU will be used
  in the 'Command Line Arguments':
  - HC12:   -CpuHC12
  - HCS12:  -CpuHCS12
  - HCS12X: -CpuHCS12X
- The derivative header and source files are located in the following directories:
  - {CodeWarrior}lib\hc12c\include (derivative header files)
  - {CodeWarrior}lib\hc12c\src (derivative source files)
  You will need to drag and drop from the directories above the new derivative
  header and source files to the 'Libraries' project folder.
  HINT: A 'Windows Explorer' with a near path: context menu/right mouse click on
        the old derivative header/source file in the 'Libraries' project folder
        and select 'Open in the Windows Explorer'.
- You can now remove the old derivative header and source files that are referenced
  by the wizard from the project. Remove the old derivative header and source files
  in the 'Libraries': context menu/right mouse click on the old derivative header
  and source files in the 'Libraries' project folder and select 'Remove'.
- You will need to adapt the main source file, this file can be found in the
  'Sources' project folder. Open this file and change the name of the included
  derivative header file to the new one. In case of a C or C++ project you will
  also need to adapt the pragma 'LINK_INFO DERIVATIVE' to the new derivative.
  This pragma tells the simulator which derivative to simulate. However you can
  also remove this pragma and setup the new derivative in the HI-WAVE debugger
  itself (see next point).
- You will need to adapt the PRM file as well. PRM files are located in the
  following directory:
  - {CodeWarrior}lib\hc12c\prm
  You need to open the new PRM file and copy & past the content to your currently
  used PRM file. In case you dont have a banked memory model, you will need to
  adapt the content as well. You may have a look at the old prm file.
- After successful compilation and linkage you can start the HI-WAVE debugger.
  You will need to setup the debugger for the new derivative. Between the menu
  option 'Run' and 'Component' in the HI-WAVE debugger you will find the current
  target menu. In case of the simulator you will see a 'Simulator' menu. Within
  this menu click on 'Set Derivative...'. In the opened dialog box you can
  select the new derivative. The names used there might also be used with the
  pragma 'LINK_INFO DERIVATIVE'.
- Now you should have a project for the derivative B.

//------------------------------------------------------------------------
//  Enabling Processor Expert
//------------------------------------------------------------------------
If you decided not to enable Processor Expert during the project creation,
you can do this later as well. However, you have to consider following points:
- it only makes sense for C or C++ projects, not for an absolute
  assembly or relocatable assembly project.
- Then you need to select the correct CPU bean for your project. Do so with
  the bean selector (menu Processor Expert > View > Bean Selector) and
  double click on the desired CPU bean in the CPU tree. This will add the
  CPU bean to your project.
- As Processor Expert is generating it's own 'main' function/source file, you need to
  remove the one createad by the wizard from the project. Remove the main file
  in the 'Sources': context menu/right mouse click on the main file in the 'Sources'
  project folder and select 'Remove'.
- Same applies to the derivative header file. Processor Expert maintains it's own version,
  so you need to remove them from the CodeWarrior project: You find the .c and .h file
  in the 'Libs' project folder: context manu/right mouse click and select 'Delete' to
  have the .h and the .c file removed.
- Processor Expert maintains as well its own linker .prm file. You need to remove the
  one added to the project by the wizard in the 'Prm' project folder by context menu/right
  mouse click and selecting 'Remove'.
- Enable Processor Expert using the menu
  Processor Expert > Enable Processor Expert for <projectName>
- A dialog will ask you if you want to enable Processor Expert for the project:
  click on 'Yes'.
- Now you can build/make your project as usually (menu Project > Make).

//------------------------------------------------------------------------
//  Changing the memory model
//------------------------------------------------------------------------
If you decided to use a memory model A during the project creation, but later you
would like to use the memory model B, you have to consider following points:
- You will need to adapt the CodeWarrior project settings: In the 'Assembler for
  HC12' and 'Compiler for HC12' panels make sure that the new memory model will
  be used in the 'Command Line Arguments':
  - Small memory model:  -ms
  - Large memory model:  -ml
  - Banked memory model: -mb
- You may need to change the standard libraries. The library files are located in
  the following directory:
  - {CodeWarrior}lib\hc12c\lib (HC12)
  - {CodeWarrior}lib\xgatec\lib (XGATE)
- You will need to drag and drop from the directories above the new library files
  to the 'Libraries' project folder. For the naming schema please have a look to
  the following readme.txt:
  - {CodeWarrior}lib\hc12c\readme.txt (HC12)
  - {CodeWarrior}lib\xgatec\readme.txt (XGATE)
- You can now remove the old library files that are referenced by the wizard from
  the project. Remove the old library files in the 'Libraries': context menu/right
  mouse click on the library files in the 'Libraries' project folder and select
  'Remove'.
- Now you should have a project for the memory model B.

//------------------------------------------------------------------------
//  Appending an additional remote connection
//------------------------------------------------------------------------
If you missed to add a specific remote connection during the project creation,
you can do this later as well. However, you have to consider following points:
- In 'CodeWarrior' within your project choose the 'Target' tab and use the menu
  option: 'Project' -> 'Create Target...'. In this dialog enter a the new remote
  connection name and choose 'Clone existing target'. You may choose any existing
  target.
- In 'CodeWarrior' select the newly create Project. We need now to prepare the
  debugger.
- In case you need a different memory mapping for that specific remote connection.
  (e.g. the 'HCS12 Serial Monitor' remote connection could be a candidate)
  You will need to add the modified prm file to the 'CodeWarrior' project. Make
  sure that the new .prm file is selected in the 'CodeWarrior' target and the old
  one is no longer.
- The debugger configuration files (.ini) are located in the '{Project}' directory.
  You will need to copy an existing '.ini' file to the same location. For the file
  name use the remote connection name. You can now drag and drop the ini file to
  'Debugger Project File' in the 'CodeWarrior'.
- You will need to adapt the 'Arguments' option in the 'CodeWarrior' project setting
  panel 'Build Extras'. Replace the '.ini' file name with the new one. In the same
  option line replace the '-instance=x' with '-instance=y', where y is the new
  remote connection.
- We need now to setup the debugger. You can do this by starting the debugger and
  opening the 'Set Target' dialog with 'Component' -> 'Set Target'. Within this
  dialog you will need to choose the correct settings.
- Between the menu option 'Run' and 'Component' in the HI-WAVE debugger you will
  find the current target menu. In this menu you may need to choose the derivative,
  the communication type (COM1, LPT1, USB, ..), etc.
- In case you need 'Command Files', you can create empty files in the '{Project}cmd'
  directory. In the debugger you can use the 'Command Files...' dialog in the target
  menu to adapt the debugger.
- Now you should have a new remote connection in the project.

//------------------------------------------------------------------------
//  Simulator/Debugger: Additional components
//------------------------------------------------------------------------
In the simulator/debugger, you can load additional components. Try the menu
Component > Open.

//------------------------------------------------------------------------
//  Additional documentation
//------------------------------------------------------------------------
Read the online documentation provided. Use in CodeWarrior IDE the menu 
Help > CodeWarrior Help.

//------------------------------------------------------------------------
//  Contacting Metrowerks
//------------------------------------------------------------------------
For bug reports, technical questions, and suggestions, please use the
forms installed in the Release_Notes folder and send them to:
USA:          support@metrowerks.com
EUROPE:       support_europe@metrowerks.com
ASIA/PACIFIC: j-emb-sup@metrowerks.com