Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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 memo-
       ries (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  se-
       rial 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 tar-
	      get (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	 boot-
       loader  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 boot-
       loader 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  con-
       nection.

       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, accord-
       ing 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 se-
       rial 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  op-
	      tional,  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  tar-
	      get description, and -t some_other_target	will look for /usr/lo-
	      cal/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 re-
	      quires it	and cannot auto-detect it.  freq can be	specified  di-
	      rectly  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 ad-
	      dress 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,  pro-
       cessing 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  EEP-
	      ROM  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 us-
	      ing -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 unse-
	      cured state.  This leaves	MCU in usecured	state with FLASH  mem-
	      ory 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 eras-
	      ing LRAE.

       -Y, --tbdml-bulk
	      Option applicable	for TBDML USB POD only - use bulk  USB	trans-
	      fers,  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 Win-
	      dows, linux unfortunatelly  rejects  bulk	 transfers,  but  Your
	      Mileage May Vary.

EXAMPLES
       There are some common options that must be specified in most cases: in-
       terface 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  ex-
       ample,  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 specifica-
       tion  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	 exam-
       ple  -  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  re-
       quires  some  more  action  commands to do something specific, but such
       call with these options only is convenient for verifying	target	commu-
       nication	- 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 address-
       ing, 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  pro-
	      gram.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  re-
       quest,  for example push	button tested as very first thing in your pro-
       gram or something like that.  Also, every hcs12mem call using LRAE  re-
       quires preceding	manual target reset.

       Writing	program	destined to be loaded into FLASH memory	in coexistence
       with LRAE bootloader has	special	requirements (memory layout, MCU  ini-
       tialization), 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	imple-
       ments 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	--eep-
	      rom-protect 256B

       Erase FLASH (EEPROM gets	erased too), write your	program	and reset tar-
       get (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  ini-
       tialization), 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)

NAME | SYNOPSIS | DESCRIPTION | SUPPORTED INTERFACES | SUPPORTED MCUs | OPTIONS | EXAMPLES | BUGS, NOTES, TODO | SEE ALSO | COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=hcs12mem&sektion=1&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help