Target Security

The various targets provide security by programming a Security Region of the internal Flash with certain values that enable or disable security features on the device. The Flash contents of a secured device are inaccessible and only limited access to the chip is possible using the debug interface.

The target devices provide some mechanism for being unsecured. For security reasons, this involves totally erasing the device to maintain the privacy of the originally programmed information. The USBDM programmers refer to this as mass erasing and it is one of the options provided for erasing the device before programming.

The mass erase details vary from chip to chip and are summarised below:

RS08, Coldfire V1
The device provides a mass erase operation. This leaves the flash erased to 0xFF. The security region is part of this flash and is erased as well. A security value of 0xFF corresponds to a unsecured state so the device is left blank and in an unsecured state.
NOTE: Programming a memory image that does not contain values for the security region to a blank device will leave the device unsecured.
HCS08
The device provides a mass erase operation. This leaves the flash erased to 0xFF. The security region is part of this flash and is erased as well. A security value of 0xFF corresponds to a secured state so the device is left blank but in an secured state. To entirely unsecure the device it is necessary to re-program the security area to a particular, non-0xFF value and reset the device. The programmer does not do this
The programmer takes advantage of an additional feature of the HCS08 devices. A blank device may be temporarily unsecured by executing a blank check operation of the flash. This allows the programmer to re-program a blank device.

NOTE: Programming a memory image that does not contain values for the security region to a blank device will leave the device secured.
HCS12
The device provides a mass erase operation. This leaves the flash erased to 0xFF. The security region is part of this flash and is erased as well. A security value of 0xFF corresponds to a secured state so the device is left blank but in an partially secured state. To entirely unsecure the device to allow unfettered reprogramming it is necessary to re-program the security area to a non-0xFF value and reset the device. When mass-erase is selected the programmer carries out the above operations. If needed, it then uses a sector erase to restore the security area to a blank (secured) state but without a further reset. This leaves the device blank but temporarily unsecured (until the next reset).
NOTE: Programming a memory image that does not contain values for the security region to a blank device will leave the device secured.
NOTE: UF32 devices have a hardware errata that make programming them very error prone. Only use mass-erase and unsecured with these devices unless you really, really know what you are doing. It is very easy to permanenltly secure them - effectively bricking the device.
Coldfire V1+, Kinetis, MC56F8xxx(newer devices only)
The device provides an unsecure operation. This erases the flash to 0xFF and then re-programs the security region to an unsecured state. The device is unsecured but not blank.
The non-blank security area may conflict with programming a new security value to the device. To prevent this problem the programmer does a selective erase of the security area after the mass erase. This leaves the device blank and it will be become secured if reset in this state. The programmer does not reset the device until it has finished programming so this is not an issue.
It is also possible to permanently secure these devices by choosing particular security options to be programmed in the security region. Such a device cannot be erased or re-programmed ever.
The programmer does not allow programming of a device to permanently secure it in the above fashion.
NOTE: Programming a memory image that does not contain values for the security region to a mass erased device will leave the device secured due to the selective erase done following the mass erase.
NOTE: This outcome differs to that of earlier versions of the programmer.
Coldfire V2,3,4
These devices have a separate utility to unlock them so Mass erase is not available in the programmer.

Notes on Clock Trimming (RS08,HCS08 & CFV1 only)

The program uses measurements of the BDM interface speed to determine the speed of the target internal clock. As such it is limited in accuracy by the speed of the processor used in the BDM. USBDM BDMs are available using two different microprocessors. The earlier MC68HC908JB16 based BDMs operate at 6 MHz bus speed while the MC9S08JS16 or MC9S08JMxx BDMs operate at 24 MHz. It would be expected that trimming would be more accurate for the higher speed BDMs.
The following algorithm is used:
1. A binary search is done to locate a provisional trim value
2. Measurements of the clock frequency is done for a range of values either side of the above value. These measurements are repeated several times for each value.
3. A linear regression is done on the values obtained. This is a quite arbitrary approach that assumes frequency versus trim value is linear.
4. The required trim value is estimated from the linear curve obtained. This seems to result in a very consistent value for the trim that doesn't vary much due to individual measurement tolerances.
The software programs the target clock divider for a low bus speed before measurement. Since the BDM interface speed is directly related to the bus speed this improves the accuracy.
In practice, when using the JMxx BDMs, the trimming seems consistent to +/- 1 LSB of the trim value. I need to investigate this a bit further on the slower BDMs.
The trim frequency specified is that of the internal clock (either ~32.7kHz or ~243kHz depending on the clock type used in a particular target). It's up to you to relate this to an actual bus frequency for the target in your application as this will depend upon how your code programs the clock divider/multiplier registers or equivalent. The clocks may be trimmed over quite a range, +/-25% I believe. Please check the manual for the chip you are using to determine a suitable clock speed and detailed programming of the clock module.

Notes on Target Programming & Time taken

The utility downloads a program to the target RAM to do the majority of the actual programming. The program is relocated (patched) to operate at whatever location it is loaded since the RAM boundaries vary with target type.
The above approach is only practical because the devices share a very common structure in respect of the clock types and Flash programming requirements. A single program with minor patches is re-usable on different targets. This approach would be impractical on other processor families which vary more.
The remainder of the target RAM is used as a buffer for the actual data to be programmed. The larger the buffer (up to a limit) the faster the programming will proceed since it reduces the number of USB transfers required and the overhead of polling the program executing on the target etc.
Some direct manipulation of the target Flash registers is necessary for the mass-erase and blank-check operations since these must be available even if the target is secured and the RAM inaccessible.
Some of the other target registers are also directly manipulated e.g. the clock trim registers, Flash protection and Flash timing. This may be slower than loading a program to the RAM to do this indirectly but these are infrequent operations that don't affect the overall time taken significantly.
The program has very little 'knowledge' of the target being programmed. Attempting to program the wrong device or an illegal Flash memory range tends to result in cryptic error messages e.g. loss of BDM communication due to the target doing a Illegal Address reset :)
The speed of programming is affected by the following:
- Speed of USB interface. The JS16 & JMxx BDM are full-speed while JB16 is low-speed. This has an obvious affect.
- Speed of transfer from the BDM to the target device. While programming, the software programs the target bus clock to a higher speed to improve the BDM interface speed.
- Time taken by the flash state machine to do the actual programming. This is fixed for a particular target. (Changing the bus speed does NOT affect this.) The software makes use of Burst-programming when available which is the fastest alternative.

Example Code for Setting Clock trim

An example of trimming a S08ICGVx clock.
This code will result in a bus clock of 16MHz if the internal clock is trimmed to 250 kHz.

typedef unsigned char U8;

// Clock Trim values in Flash - dummy value overwritten by flash programmer
static const volatile U8 NV_ICGTRM_INIT @0x0000FFBE = 0xFF;  // MSB

void initClock( void ) {

   SOPT          = SOPT_STOPE_MASK|SOPT_BKGDPE_MASK; // Watchdog off, STOP enabled
   
   if (NV_ICGTRM_INIT != 0xFF) {

     // Only trim & update clock if Trim values have been programmed to Flash.
     // Changing clock divider on untrimmed device may be out of bus clock spec.

     ICGTRM = NV_ICGTRM_INIT;

     // Set 16 MHz bus clock assuming internal clock trimmed to 250 kHz
     ICGC1 = (1<<ICGC1_CLKS_BITNUM);                       // CLKS=1
     ICGC2 = (5<<ICGC2_MFD_BITNUM)|(0<<ICGC2_RFD_BITNUM);  // MFD=5, RFD=0   
                                                           // N=4+2*MFD=14, R=2**RFD=1
                                                           // Fbus=(250kHz/7)*32*N/R=16MHz
   }
}

An example of trimming a S08ICSVx clock.
- Depending on the clock version (V1, V2 or V3) & DRS options, this code will result in a bus clock of 8, 16MHz or 24MHz if the internal clock is trimmed to 31.25 MHz.
- Alternatively, trimming the clock to 39.06 kHz will result in 10, 20 or 30 MHz bus speed if supported by the particular chip.

Clock Version	DRS	Clock Trim Freq	FLL Factor	DCO Freq	Bus Freq (BDIV=00)
S08ICSV1	-	31.25-39.0625 kHz	512	16 - 20 MHz	8 - 10 MHz
S08ICSV2	-	31.25-39.0625 kHz	1024	32 - 40 MHz	16 - 20 MHz
S08ICSV3	00	31.25-39.0625 kHz	512	16 - 20 MHz	8 - 10 MHz
S08ICSV3	01	31.25-39.0625 kHz	1024	32 - 40 MHz	16 - 20 MHz
S08ICSV3	10	31.25-39.0625 kHz	1536	48 - 60 MHz	24 - 30 MHz

typedef unsigned char U8;

// Clock FTRIM values in Flash - value _combined_ with FTRIM bit by programmer
static const volatile U8 NV_FTRIM_INIT  @0x0000FFAE = 0xFF; // may be ICSSC_DRST_DRS0 etc

// Clock TRIM values in Flash - dummy value overwritten by flash programmer
static const volatile U8 NV_ICSTRM_INIT @0x0000FFAF = 0xFF;

void initClock( void ) {

   SOPT1          = SOPT1_STOPE_MASK|SOPT1_BKGDPE_MASK;  // Watchdog off, STOP enabled, BKGD pin enabled,  
   
   if (NV_ICSTRM_INIT != 0xFF) {

     //  Only trim & update clock if Trim values have been programmed to Flash.
     //  Enabling x1 clock divider on untrimmed device may be out of bus clock spec.

     ICSSC       = NV_FTRIM_INIT;    // Trim the internal clock
     ICSTRM      = NV_ICSTRM_INIT;

     // Set 8/16 MHz bus clock assuming 31.25 MHz trim
     ICSC2 = (0<<ICSC2_BDIV_BITNUM);                   // BDIV=0,RANGE=0,HGO=0,LP=0,EREFS=0,ERCLKEN=0,EREFSTEN=0
     ICSC1 = (0<<ICSC1_CLKS_BITNUM)|ICSC1_IREFS_MASK;  // CLKS=0,RDIV=0,IREFS=1,IRCLKEN=0,IREFSTEN=0
   }
}

An example of trimming a S08MCGVx clock.
- This code will result in a bus clock of 16MHz if the internal clock is trimmed to 31.25 MHz.
- Depending on the clock version (V1 or V2) & DRS options, this code will result in a bus clock of 8 or 16MHz if the internal clock is trimmed to 31.25 MHz.
- Alternatively, trimming the clock to 39.06 kHz will result in 10 or 20 MHz bus speed if supported by the particular chip.

Clock Version	DRS	Clock Trim Freq	FLL Factor	DCO Freq	Bus Freq (BDIV=00)
S08MCGV1	-	31.25-39.0625 kHz	1024	32 - 40 MHz	16 - 20 MHz
S08MCGV2	0	31.25-39.0625 kHz	512	16 - 20 MHz	8 - 10 MHz
S08MCGV2	1	31.25-39.0625 kHz	1024	32 - 40 MHz	16 - 20 MHz
S08MCGV4	2	31.25-39.0625 kHz	1536	48 - 60 MHz	24 - 30 MHz

typedef unsigned char U8;

// Clock Trim values in Flash - dummy values overwritten by flash programmer
static const volatile U8 NV_MCGTRM_INIT @0x0000FFAF = 0xFF;  // MSB
static const volatile U8 NV_FTRIM_INIT  @0x0000FFAE = 0xFF;  // LSB

void initClock( void ) {

   SOPT1          = SOPT1_STOPE_MASK;  // Watchdog off, STOP enabled, BKGD pin enabled,  
   
   if (NV_MCGTRM_INIT != 0xFF) {

     //  Only trim & update clock if Trim values have been programmed to Flash.
     //  Enabling x1 clock divider on untrimmed device may be out of bus clock spec.

     MCGSC       = NV_FTRIM_INIT;    // Trim the internal clock
     MCGTRM      = NV_MCGTRM_INIT;

     // Set 16 MHz bus clock assuming 31.25 MHz trim
     MCGC2 = (0<<MCGC2_BDIV_BITNUM);                   // BDIV=0,RANGE=0,HGO=0,LP=0,EREFS=0,ERCLKEN=0,EREFSTEN=0
     MCGC1 = (0<<MCGC1_CLKS_BITNUM)|MCGC1_IREFS_MASK;  // CLKS=00,RDIV=0,IREFS=1,IRCLKEN=0,IREFSTEN=0
     // Following only applies for S08MCGV2 (and is default anyway!)
     //MCGT  = MCGT_DRST_DRS_MASK; // MCGT_DRST_DRS=1, MCGT_DMX32=0  
   }
}

Adding Devices

The programmers use several techniques to obtain their results. Where possible these have been made configurable to allow adding or changing devices without the need to re-compile the code. The programmers make use of the following:

XML files

These describe the various devices and indicate which programming algorithms are used. The details vary a bit between programmers but may include the following:
<sdid> Used to physically identify and confirm the device being programmed. An SDID of zero will match any device.

value

<clock> Used to describe one of the standard clocks. This is used to identify the correct clock trim algorithms Hard coded in the programmers.

type
registerAddress

<securityInfoRef ...> is used to refer to a shared description of the modifications to the Flash image required to secure or unsecure the device. This uses the <securityAddress> from the memory tag.

ref - A reference to security information declared in the <sharedInfo> area.

<note> A brief note about the device.

<memory> Description of memory for the device. A separate <memory> entry is used for each memory in the device. A memory is a region having a different memory type or memory controller. For example RAM and Flash would be described by separate entries as would two Flash memories that have different controllers or erase individually.

pageAddress - the location of the page register e.g. PPAGE or EPAGE
registerAddress - the location of the flash controller registers
type - the type of the memory
securityAddress - the location of the security region used to secure the device
<memoryRange> Each memory is made up of a collection of one or more <memoryRange> elements describing the non-contiguous ranges of memory.
pageNo - the page number to write to the EPAGE/PPAGE register for this region. If omitted a value is calculated from the memory region address (only HCS12, HCS08 use paged memory addresses).
start - start of the memory range. This will be a paged address if appropriate.

end or size - you may specify either the inclusive end address or size. Size may be given in K or MB e.g. 128K 1M

      <device family="HCS08" name="MC9S08DE60">
         <clock registerAddress="0x0048" type="S08MCGV1" />
         <memory type="ram">
            <memoryRange end="0x107F" start="0x0080" />
         </memory>
         <memory registerAddress="0x1820" type="flash" securityAddress="0xFFB0">
            <securityInfoRef ref="HCS08-default-security-off" />
            <securityInfoRef ref="HCS08-default-security-on" />
            <memoryRange end="0x13FF" start="0x1080" />
            <memoryRange end="0xFFFF" start="0x1900" />
         </memory>
         <memory pageAddress="0x1823" registerAddress="0x1820" type="eeprom">
            <memoryRange end="0x0017FF" start="0x001400"  pageNo="0x10" />
            <memoryRange end="0x0117FF" start="0x011400"  pageNo="0x50" />
         </memory>
         <sdid value="0x00E" />
         <note>EEPROM programming uses Page 0x00 and 0x01</note>
         <note>Flash ECC not supported</note>
      </device>

TCL scripts

Each device has a TCL script that provides basic functions necessary for the programmer. These are usually shared by multiple devices but if needed an individual script may be used.

The scripts provide the following operations:

Initialisation of the target. Done after each reset.
Initialisation of the flash. Done before flash programming.
Mass erase & unsecure. Used when the mass erase option is selected.
Security check. Determines if the device is secured.

Binary Files (Freescale S-records)

A program is down-loaded to the target to do the actually programming of a device. In the case of RS08 and HCS08 devices this program is incorporated into the programmers. For HCS12, Coldfire and Kinetis devices the program is kept in a separate file that is referenced by the XML files. This allows for individual algorithms to be used for each device if necessary. In practice, there is a shared program used for each Coldfire V1 family (Coldfile, Coldfire+), Coldfire V234 and Kinetis devices. There are several used to cover the range of flash or memory management used by the HCS12 devices.
The external programs provide the following capabilities:

Sector or page erase. Used for Erase-selective option.
Flash region mass erase i.e. erasing an entire flash memory as a single operation. Used for Erase-All option.
Blank checking. Used to check if a memory region is blank before programming.
Programming. Does the actual programming.
Verify. Verifies memory contents.

To improve performance multiple operations may be combined e.g. ERASE+BLANK_CHECK+PROGRAM+VERIFY