Please note as of Wednesday, August 15th, 2018 this wiki has been set to read only. If you are a TI Employee and require Edit ability please contact x0211426 from the company directory.

Custom MSP430 BSL

From Texas Instruments Wiki
Jump to: navigation, search

Custom MSP430 BSL for 1xx/2xx/4xx Devices

Refer to MSPBoot or OpenBSL implementation .

Custom MSP430 BSL for 5xx Devices

Implementing Custom BSL for 5xx devices is described in the following `Creating a Custom Flash-Based Bootstrap Loader (BSL)' (SLAA450) application note.

Implementing Custom BSL solution on 5xx devices means that it is possible to adapt the following points:

  • how the BSL code is invoked - (see the #Device Startup Sequence section)
  • the communication peripheral interface (e.g. UART, I2C, SPI, USB, etc.)
  • the protocol (set of commands) used between the BSL and the host processor
  • adapting the memory type

in order to suit the application requirements/limitations. However it is important to be noticed that the whole BSL code space is only 2 KB. Usually it is only necessary to adapt the invoke process and the communication peripheral interface only, while the BSL protocol and the memory type are used per default.

Device Startup Sequence

The device startup sequence plays an important role to show how flexible the custom BSL can be implemented to meet the application requirements. To make it easier on understanding the device startup sequence and the BSL code implementation, this following section will explain the device startup sequence along with the implementation of MSP430F5438A BSL implementation using CCS v4.2.0 which can be found in the BSL software source package under Custom_BSL_Zip_File\Example_BSL_Source\CCS_v4.2.0_BSL-5438A directory. The device startup sequence of 5xx/6xx MSP430 device can be illustrated as follows:

Msp430 5xx startup seq.PNG

(1) If a 5xx device is reset, the device will first of all execute the boot code which will check whether it is necessary to run the BSL code. The boot code will basically check two things before deciding whether to run the BSL code or the user application code: the BSL Signature and the return value of BSL Protect function. This will be explained further in the following steps.
NOTE: The boot code will be only executed on hardware reset (pulling down the /RST signal). Software reset such as using watchdog timer, setting the PMMSWBOR or PMMSWPOR of PMMCTL0 will not trigger the boot code.

(2) For the first verification step, the boot code will start to check whether a valid BSL Signature is available at the memory address 0x17F4 and 0x17F6. The BSL Signature indicates whether a valid BSL resides in the BSL Flash memory. The valid BSL signature values at memory address 0x17F4 and 0x17F6 are 0x3CA5 and 0xC35A respectively.

In the MSP430F5438A BSL implementation, the BSL signature can be found in the BSL430_Low_Level_Init.asm under the “BSLSIG” section as follows:

.sect "BSLSIG"
                 .word       0xFFFF
BslProtectVecLoc .word       BSL_Protect             ;adress of function
PBSLSigLoc       .word       03CA5h                  ;1st BSL signature
SBSLSigLoc       .word       0C35Ah                  ;2nd BSL signature
                 .word       0xFFFF
BslEntryLoc      .word       BSL_Entry_JMP           ;BSL_Entry_JMP
PJTAGLOCK_KEY    .word       0xFFFF                  ; Primary Key Location
SJTAGLOCK_KEY    .word       0xFFFF                  ; Secondary Key Location
                                                     ; set default unlock JTAG with option to lock with writting
                                                     ; a value <> 0x0000 or 0xFFFF

The “BSLSIG” section itself is defined in the linker command file lnk_msp430f5438a.cmd as the memory area starting at address 0x17F0 with the length of 16 bytes:

    . . . .
    BSLSIG                  : origin = 0x17F0, length = 0x0010
    . . . .

    . . . .
    BSLSIG     : {} > BSLSIG
    . . . .

(3) If a valid BSL Signature is found, the boot code will run the BSL Protect function which is pointed by the content of memory address 0x17F2. As can be seen in the implementation of “BSLSIG” section above, the pointer to BSL_Protect is stored in the second word of “BSLSIG” section which basically refers to the address 0x17F2.

The BSL Protect function has basically the following tasks:

  • Set the appropriate value of SYSBSLC register to protect the BSL flash memory which contains the BSL code.
  • Verify whether it is really necessary to run the BSL and report the result to the boot code by setting/resetting Bit 1 (value 0x02) of R12 (R12 is also used in interfacing C-Assembly code together with R12 if necessary to contain return value of a function).

The step in the BSL Protect function for verifying whether it is necessary to run the BSL code can be flexibly adapted to meet the application requirements/limitations.

Referring to the SLAU319A chapter 1.3, the default way to invoke the BSL for device without USB interface is to apply a specific BSL Entry sequence signals on the RST and TEST/TCK pins of the device. This seems to be a hardware dependent process, but actually for the 5xx family devices such as the MSP430F5438A, it is implemented in software. In the MSP430F5438A BSL code implementation, the BSL Protect function is implemented in BSL430_Low_Level_Init.asm file as follows:

              CLR      RET_low                  ;lock (keep JTAGLOCK_KEY state)
              ;BIC     #BSL_REQ_JTAG_OPEN, RET_low   ;lock (keep JTAGLOCK_KEY state)
              ;BIS     #BSL_REQ_JTAG_OPEN, RET_low   ;make sure it remains open for debugging
              bit     #SYSBSLIND,&SYSCTL      ;check for BSL start request
              jz      BCC2BSL
              BIS.W   #BSL_REQ_APP_CALL, RET_low

As can be seen above, the MSP430F5438A default BSL Protect function only checks the SYSBSLIND bit of the SYSCTL register (which will be set if the BSL Entry sequence signals are applied to the RST and TEST/TCK pins) and set the Bit 1 (BSL_REQ_APP_CALL) of R12 (RET_low) if necessary. This shows that the way to invoke the BSL can be adapted through software.

The following example shows how to invoke a custom BSL for MSP430F5438A using the MSP-EXP430F5438 experimenter board by pressing the S1 switch (connected to P2.6). LED1 which is connected to P1.0 will be also turned on as indication if the BSL code is executed. The implementation of BSL Protect function for this custom BSL is as follows:

              CLR      RET_low                  ;lock (keep JTAGLOCK_KEY state)
              ;BIC     #BSL_REQ_JTAG_OPEN, RET_low   ;lock (keep JTAGLOCK_KEY state)
              ;BIS     #BSL_REQ_JTAG_OPEN, RET_low   ;make sure it remains open for debugging
              BIC.B     #BIT0, &P1OUT     ; Clear LED0 by default
              BIS.B     #BIT0, &P1DIR     ; Set LED0 as output
              BIS.B     #BIT6, &P2REN     ; Enable pull resistor on S1
              BIS.B     #BIT6, &P2OUT     ; select pull-up
              BIT.B     #BIT6, &P2IN      ; Check S1
              jnz      BCC2BSL
              BIS.B     #BIT0, &P1OUT     ; Turn ON LED if staying in BSL
              BIS.W   #BSL_REQ_APP_CALL, RET_low

Another example is the implementation of BSL code for 5xx devices which has USB interface (e.g. MSP430F552x family). Referring to the SLAU319A document – chapter 1.3.3, the 5xx devices with USB can be invoked in two ways:

  • powering up the device with the PUR tied to VUSB.
  • powering up the device with USB and the reset vector is blank

Below is the implementation of BSL Protect function for the MSP430F552x devices:

              CLR.W    RET_low                  ; clears JTAG_OPEN, keeping KEY state
              BIS      #SYSBSLPE+SYSBSLSIZE0+SYSBSLSIZE1 , &SYSBSLC ; protects BSL
              ;BIC.W     #BSL_REQ_JTAG_OPEN, RET_low   ;lock (keep JTAGLOCK_KEY state)
              ;MOV.W      #BSL_REQ_JTAG_OPEN, RET_low   ;open
              mov.w   #0x9628,   &USBKEYPID
              bis.w   #PSEIEN,   &USBPHYCTL
              bit.w   #PUR_IN,   &USBCNF
              jnz     REQUEST_BSL               ; if PUR_IN set, request BSL
              cmp.w   #0xFFFF,   &0xFFFE        ; otherwise, test for blank RESET
              jne     JUST_RETA                ; if not blank, skip delay and start
              ; Delay for USB power-up
              mov.w   #300, R11
DELAY_LOOP    dec.w   R11
              jnz     DELAY_LOOP
              bit.w   #USBBGVBV, &USBPWRCTL     ; test for USB power
              jz      JUST_RETA                 ; no power, jump to just start
              mov.b   #0x00,     &USBKEY

As can be seen above, the BSL invocation for MSP430F552x is actually also purely implemented by software.

Therefore it is basically possible to adapt the BSL Protect function to invoke the BSL code on a way to meet the application requirements/limitations, e.g. BSL Protect function checks the checksum of flash content to verify if the user application code is valid: if checksum fails, BSL code shall be executed. However there are several things to be noticed when trying to implement custom BSL Protect function:

  • There is only 2 KB flash memory space allocated for the whole BSL code, so avoid complex and long BSL Protect function because the 2 KB should also hold the real BSL software code itself.
  • When the BSL Protect function requires a long processing time, the watchdog timer shall be halted otherwise the watchdog will fire during the BSL Protect function execution and reset the device. This will make the device to be no longer accessible because the device startup sequence can never finish (it will keep getting reset by the watchdog) and the JTAG access is available first after the device startup sequence finishes.

(4) When the BSL Protect returns, the boot code will check BIT1 and BIT0 of R12 register.

  • If BIT1 is set, the BSL code will be executed by jumping to the BSL Start Vector pointed by the address memory location 0x17FA, otherwise the boot code will execute the user application code by jumping to the memory area pointed by the System Reset interrupt at address 0xFFFE.
  • If BIT0 is set, the JTAG lock state will be determined based on JTAG key (only if JTAG Key is all 0x00 or all 0xFF, the device has open JTAG access). If BIT0 is cleared, the JTAG will be open, overriding the JTAG Key.

Invoking Custom BSL Example

In some cases, the connection interface to the MSP430 device in some system is very restricted. Imagine a small MSP430 sensor based sensor system which has only power line and serial communication interface to the outside world, in this case the most elegant way to run the BSL code is by sending a specific command to the MSP430 running the application code via the communication interface. The following custom BSL example tries to set an example on how this can be done.

The CUSTOM_BSL code contains the BSL code where the BSL Protect function is modified to check for a BSL Flag String (“RUNBSL”) at the beginning as verification to invoke BSL code or not. The CUSTOM_BSL_APP code contains an example code where the application receives several possible UART commands (9600 bps, 8N1), such as “LED ON”, “LED OFF”, and “RUN BSL”. If the application receives “RUN BSL” commands it will try to invoke the BSL using three possible ways:

  • Writing the BSL Flag String into the Info B memory and generating software reset (software BOR)
  • Writing the BSL Flag String into the Info B memory and requesting for hardware reset to trigger the boot code.
  • Jumping directly to the Z-AREA to run the BSL code directly.

There are several compile options in the appl.c file which are explained as follows:

  • INVOKE_BSL_WITHOUT_RESET: As explained above, there are three possible ways to invoke the BSL: using software reset, hard reset, or jumping directly to Z-AREA. Defining INVOKE_BSL_WITHOUT_RESET macro will use the latter.
  • USE_SW_RESET: This macro is used for test purpose only as the application code tries to do a self-software reset after writing the BSL Flag String into Info B memory. There are three implementations of software reset (WDT, software BOR, software POR), but only software BOR will cause boot code to run.
  • SW_RESET :This macro is defined to determine which software reset to be tested. There are three possible software reset to be tested: using watchdog timer, software POR, or software BOR.

BSL Software Overview

The supplied BSL software is basically designed and written to be as modular as possible by dividing the software into three main modules:

  • Peripheral Interface (PI) module:

The Peripheral Interface (PI) module implements the communication interface used by the BSL to communicate with the remote station which sends the BSL commands to the BSL. Usually the supplied BSL software uses a UART interface based on the Timer_A module, but it is possible to adapt other communication interfaces such as hardware UART, I2C, SPI, etc.

  • BSL API:

The BSL API module implements the interface to the memory which the MSP430 devices posses. It includes basic memory functionality such as locking/unlocking, erasing, writing, reading, and checksum calculations. This module is written to be modular to enable interfacing between different memory types e.g. Flash, FRAM, etc.

  • Command Interpreter:

The Command Interpreter module implements the BSL protocol which interprets the BSL Core Command bytes. It uses the PI module to send/retrieve the BSL command request/response, and the BSL API module to do the memory modification. The Command Interpreter module is also written in modular way to enable excluding some BSL core command using preprocessors and also defining new BSL command if necessary.

General Custom BSL FAQ

What happens with erasure of the vector table? Is it considered one separate 64-byte segment (for purposes of erasure) or is it considered a part of the upper-most 512 byte “segment” of the lower 64KB memory? Next, may individual vectors be re-written?

A: The vector table is not a separate segment. It is considered in the uppermost 512-byte segment and is not 'protected' from erasure during a mass-erase, for example. Individual vectors may be re-written, but only if the whole segment is erased first.

The segment boundaries can be counted from the 0xFFFF boundary and down and then from the 0x10000 boundary and up.

Yes, this causes a concern for a user-BSL in RAM, specifically the possibility that you lose power while the IVT is erased and you end up with a device that must be reprogrammed through the hardware BSL. You must either ensure power during the BSL transfer, or keep a backup image that will be restored in the case that the BSL update fails.

How can the robustness of the firmware update process be improved, to guard against possible power failures and other events?

A: One solution is to have a fixed boot loader that always is invoked directly after RESET. This custom boot loader should “own” the memory segment containing the RESET vector and the device’s interrupt vectors and not erase/program this region. But in this case, how to allow the end application to use interrupts? Solution: Re-route interrupt requests. Boot loader to contain small “stub functions” that transfer ISR execution to an address stored in the main application program's memory image. Custom linker command files should be used for the boot loader and the main application to establish the devices memory map and to relocate the interrupt vector table of the main application program, see below example. This will add an interrupt latency of 3-5 cycles depending on the device's CPU architecture. Other options would be to locate the ISRs at fixed addresses, or to directly use a RAM based interrupt vector table (see SYSRIVECT control bit on 5xx-based devices).

MSP430 Custom BSL Memory Map Example:

MSP430 Custom BSL Memory Map Example.png

MSP430 Interrupt Vector Re-Routing Example:

MSP430 Interrupt Vector Re-Routing Example.png

For practical examples of this techniques of re-routing the interrupt vector, please refer to the OpenBSL project.