DragonFly On-Line Manual Pages
HCS12MEM(1) User Commands HCS12MEM(1)
NAME
hcs12mem - Freescale S12 MCU family memory reader/writer
SYNOPSIS
hcs12mem [ option | filename ] ...
DESCRIPTION
hcs12mem is a tool for operating on Freescale S12 MCU's internal
memories (EEPROM and FLASH). It can:
- load any program into S12 RAM and execute it,
- erase, read, write EEPROM, set EEPROM protection,
- erase, read, write FLASH,
- secure and unsecure whole MCU.
SUPPORTED INTERFACES
hcs12mem can communicate with the target device using BDM link or
serial port.
BDM POD
Using BDM link requires special interface device - so called BDM POD.
Supported BDM PODs are:
tbdml - Daniel Malik's TBDML (Turbo BDM Light USB POD), see
http://www.freegeeks.org
bdm12pod - Kevin Ross's BDM12 POD, see http://www.kevinro.com
podex-bug - original Marek Peca's PODEX (with firmware bugs that
significantly slow the communication down), see
http://www.duch.cz/podex/
podex - PODEX with improved firmware, with my fixes for memory
access bugs found in original design, see
http://cml.mfk.net.pl/podex
podex-25 - special PODEX version dedicated for fixed 25MHz
target (especially MC9S12NE64), see http://cml.mfk.net.pl/podex
BOOTLOADER (Freescale's LRAE via serial port)
hcs12mem supports operations on target memory using Freescale's LRAE
(Load RAM And Execute) bootloader, using serial port connection (SCI0
on target hardware). Prior to all operations, presence of LRAE
bootloader is required in target's FLASH memory. LRAE is available for
a wide selection of S12 MCUs. Source code, S-record files and
description can be obtained from Freescale as Application Note -
AN2546. This bootloader is supposedly loaded into new S12 MCUs as last
stage of factory processing, thus some "fresh" parts straight from
Freescale should have this bootloader already in FLASH memory.
MONITOR (Freescale's serial monitor - AN2548)
hcs12mem supports operations on target memory using Freescale's serial
monitor (AN2548). This monitor uses serial port connection (SCI0 on
target hardware). Prior to all operations, presence of serial monitor
is required in target's FLASH memory. Monitor is available for a wide
selection of S12 MCUs. Source code, S-record files and description can
be obtained from Freescale as Application Note - AN2548. Port of the
source code to GNU tools is available, see "SEE ALSO" section.
SUPPORTED MCUs
Support for various S12 derivatives is dependent on target device
connection.
BDM
hcs12mem running via BDM supports almost all S12 derivatives (not all
are tested, though, especially parts with multiple FLASH blocks are not
tested):
<MC9S12> A32, A64, A128, A256, A512, C32, C64, C96, C128, GC16, GC32,
GC64, GC96, GC128, D32, D64, D128, D256, D512, E32, E64, E128, E256,
H128, H256, UF32, NE64.
LRAE BOOTLOADER
hcs12mem using LRAE supports all derivatives that can run LRAE,
according to AN2546 (maybe some others too, if LRAE can work on them):
<MC9S12> A32, A64, A128, A256, A512, C32, C128, D32, D64, D128, D256,
D512, E128.
SERIAL MONITOR
hcs12mem using serial monitor supports all derivatives that can run
serial monitor. AN2548 has variants of serial monitor for the following
targets (compiling dedicated version for other target is easy):
<MC9S12> C32, D32, D64, D128, D256, D512, E128, H256.
My port to GNU tools adds support for A64 and NE64.
OPTIONS
-h, --help
Show usage info.
-q, --quiet
Be quiet (no progress/status messages).
-f, --force
Force operation, if questionable.
-i <interface>, --interface <interface>
Use given interface for target connection. Supported ones are:
lrae - Freescale's LRAE (Load RAM And Execute) boot loader
(AN2546)
sm - Freescale's serial monitor (AN2548)
tbdml - Daniel Malik's TBDML (Turbo BDM Light) USB POD
bdm12pod - original Kevin Ross's BDM12 POD
podex - PODEX with firmware bugfixes
podex-bug - original Marek Peca's PODEX (with memory access
bugs)
podex-25 - special PODEX version dedicated for 25MHz target
See more below in SUPPORTED INTERFACES section.
This option is mandatory and must be specified exactly once.
-p <port>, --port <port>
Use given serial port for target connection. Port is a path to
device special file, typically /dev/something
-b <bps>, --baud <bps>
Use given baud rate for serial port connection. This is
optional, and must correspond with target interface baud rate.
Value is specified in bits-per-second, for example 115200, 9600,
etc.
-t <target>, --target <target>
Use given target description. Target description is a file with
some key-value pairs, determining configuration. target can be
specified in two ways: direct file name (this file is used as
target description), or target nick name (target description
file name is created by appending .doc to the target argument,
then looked up in program's data directory).
For example, -t some_file_name.dat will treat this file as
target description, and -t some_other_target will look for
/usr/local/share/hcs12mem/some_other_target.dat file, if that's
where program data files are located.
-o <freq>, --osc <freq>
Specify target device oscillator frequency, if interface
requires it and cannot auto-detect it. freq can be specified
directly as value in Hz, or suffix [k|kHz|M|MHz] can be used,
for example these all are equivalent: -o 8000000, -o 8000kHz, -o
8MHz
-j <addr>, --start-address <addr>
Use this start address for program loaded into RAM, if this
address is not specified by S-record file.
-a <type>, --flash-address <type>
Use address type when reading/writing S-record file:
non-banked - FLASH linear area within 64kB, without banking
banked-linear - Freescale banked linear format
banked-ppage - banked format with PPAGE value as MSB
This selection refers to addresses within S-record file.
When not specified, non-banked addressing is used.
-e, --include-erased
Include erased areas of memory in written S-record file (default
is to skip 0xff blocks). Using this option, one gets S-record
file with every byte defined to explicit value.
-s <size>, --srecord-size <size>
Specify size of single S-record written to file, default: 16.
-v, --verify
Verify result of all erase/write operations.
Following options can be specified multiple times, any of them,
processing is according to occurence order:
-R, --reset <file>
Reset target into normal mode.
-U, --unsecure
Unsecure secured microcontroller. This means erasing EEPROM and
FLASH memories as part of the process !
-S, --secure
Secure the microcontroller. This means disabling access to
EEPROM and FLASH memories, any further access requires
unsecuring first.
-X <file>, --ram-run <file>
Load S-record file into RAM and execute. Addresses of data to
load must correspond to target MCU RAM area. Program is run from
address supplied in apropriate S-record, it can be overriden
using -j option.
-A, --eeprom-erase
Erase internal MCU EEPROM memory.
-B <file>, --eeprom-read <file>
Read internal MCU EEPROM memory contents into S-record file
-C <file>, --eeprom-write <file>
Write internal MCU EEPROM memory contents from S-record file
-D <range>, --eeprom-protect <range>
Write EEPROM protection byte, range can be one of the following:
<all|64B|128B|192B|256B|320B|384B|448B|512B>
all - protects whole EEPROM array
xxxB - protects last xxx bytes of EEPROM array
-E, --flash-erase
Erase entire FLASH memory, leave security byte in unprogrammed
state (0xff) thus leaving whole MCU in secured state.
-F, --flash-erase-unsecure
Erase entire FLASH memory, then program security byte to
unsecured state. This leaves MCU in usecured state with FLASH
memory in erased state, except security byte with value 0xfe.
-G <file>, --flash-read <file>
Read FLASH memory contents into S-record file.
-H <file>, --flash-write <file>
Write FLASH memory contents from S-record file.
Options specific for particular interfaces:
-Z, --keep-lrae
Option applicable for LRAE bootloader only - when erasing FLASH
memory, keep LRAE in memory (do not erase FLASH area containing
LRAE image). Default is to bulk erase whole memory, thus
erasing LRAE.
-Y, --tbdml-bulk
Option applicable for TBDML USB POD only - use bulk USB
transfers, which are violating USB specification, but give
better data transfer rates. Check if it works for you and use
it if you feel good about it. Known to work under FreeBSD and
MS Windows, linux unfortunatelly rejects bulk transfers, but
Your Mileage May Vary.
EXAMPLES
There are some common options that must be specified in most cases:
interface type, interface port, target type, target oscillator
frequency (if interface requires it and cannot auto-detect). Almost
every call requires these, so for clarity they will be stated only once
as an example, and omitted in the following examples, substituted by
[-ipto] symbol.
BDM
Depending on the interface in use, different options are required:
TBDML - interface type and target type are required, no port
specification is required (USB bus is assumed), no target frequency is
required (TBDML can auto-detect it), but it can be overriden with -o
option, if auto-detection fails and TBDML is unable to connect the
target.
BDM12, PODEX - required are: interface type, target type, interface
connection port and target frequency.
Two examples of these options for TBDML and PODEX follows: first
example - interface is PODEX, serial port for PODEX attachment is
/dev/uart0, target is MC9S12A64 MCU operating at 16MHz; second example
- interface is TBDML (assumed connection via USB), target is MC9S12A64
MCU, operating frequency is auto-detected. hcs12mem call usually
requires some more action commands to do something specific, but such
call with these options only is convenient for verifying target
communication - it initializes the target, displays all the info and
quits:
hcs12mem -i podex -p /dev/uart0 -t mc9s12a64 -o 16MHz
hcs12mem -i tbdml -t mc9s12a64
Unsecure secured microcontroller:
hcs12mem [-ipto] --unsecure
Secure unsecured microcontroller:
hcs12mem [-ipto] --secure
Load some code into target RAM and execute:
hcs12mem [-ipto] --ram-run some_code.s19
Read EEPROM contents:
hcs12mem [-ipto] --eeprom-read eeprom_data.s19
Set EEPROM protection:
hcs12mem [-ipto] --eeprom-protect all
Read data from FLASH memory and write it to S-record file, use
Freescale banked linear addresses, write all erased 0xff's to output
file (default is to skip them):
hcs12mem [-ipto] -e --flash-address banked-linear --flash-read
flash_data.s19
Write data from S-record file to FLASH memory (non-banked flat
addressing, option -a non-banked assumed by default):
hcs12mem [-ipto] --flash-write flash_data.s19
Action options can be specified multiple times, they are executed in
specified order, for example - erase FLASH, write program into FLASH
and reset target, thus immediatelly starting program execution:
hcs12mem [-ipto] --flash-erase --flash-write program.s19 --reset
LRAE BOOTLOADER (AN2546)
Using LRAE serial bootloader, we specify following common options:
hcs12mem -i lrae -p /dev/uart0 -t mc9s12a64 -o 16MHz
Baud rate for serial connection is automatically calculated by
hcs12mem, using supplied oscillator frequency as reference. You can
override auto-selected baud rate with -b <baud> option, if some other
speed is preferred.
Load your program into target RAM, and execute it:
hcs12mem [-ipto] --ram-run program.s19
Write your program into target FLASH, keeping LRAE in FLASH:
hcs12mem [-ipto] --flash-erase --keep-lrae --flash-write
program.s19
Bulk erase FLASH memory, load LRAE and your program:
hcs12mem [-ipto] --flash-erase --flash-write lrae.s19 --flash-
write program.s19
NOTES: reloading FLASH program using LRAE is tricky, because when your
program is loaded into FLASH, LRAE is not running anymore. Thus, if you
want to reuse LRAE, your program must have a way to enter LRAE on
request, for example push button tested as very first thing in your
program or something like that. Also, every hcs12mem call using LRAE
requires preceding manual target reset.
Writing program destined to be loaded into FLASH memory in coexistence
with LRAE bootloader has special requirements (memory layout, MCU
initialization), see Application Note AN2546 for more details.
SERIAL MONITOR (AN2548)
Using serial monitor, we specify following common options (oscillator
frequency is not required):
hcs12mem -i sm -p /dev/uart0 -t mc9s12a64
Baud rate for serial connection is 115200bps by default. If you have
special version of serial monitor compiled with some other settings,
you can override auto-selected baud rate with -b <baud> option.
Using serial monitor, there's no way to erase it, except via BDM, and:
- erasing FLASH erases only parts of memory outside serial monitor
(--flash-erase and --flash-erase-unsecure do the same)
- erasing FLASH erases also EEPROM ! (this is how serial monitor
implements this)
- securing and unsecuring MCU is not supported
Erase EEPROM, write some initial data and protect upper 256 bytes of
EEPROM:
hcs12mem [-ipto] --eeprom-erase --eeprom-write eeprom.s19
--eeprom-protect 256B
Erase FLASH (EEPROM gets erased too), write your program and reset
target (thus starting your program):
hcs12mem [-ipt] --flash-erase --flash-write program.s19 --reset
Writing program destined to be loaded into FLASH memory in coexistence
with serial monitor has special requirements (memory layout, MCU
initialization), see Application Note AN2548 for more details.
BUGS, NOTES, TODO
FLASH write verify is not implemented yet.
MCUs with more that single FLASH block are barely tested.
SEE ALSO
http://www.freescale.com - Freescale's web page, all S12 MCU info
http://cml.mfk.net.pl/hcs12mem - hcs12mem web page
http://cml.mfk.net.pl/podex - improved PODEX web page
http://www.duch.cz/podex/ - original PODEX web page
http://www.kevinro.com - Kevin Ross's BDM12 POD web page
http://www.freegeeks.org - Daniel Malik's TBDML
http://cml.mfk.net.pl/an2548 - my port of Freescale's serial monitor
(AN2548) to GNU tools
COPYRIGHT
(C) 2005,2006,2007 Michal Konieczny <mk@cml.mfk.net.pl>
hcs12mem is free software, covered by the GNU General Public License.
You are welcome to change it and/or distribute copies of it under the
conditions of the GNU General Public License.
hcs12mem V1.4.1 HCS12MEM(1)