Home ·

- SAM-BA internalflash applet

# SAM-BA internalflash applet

The internalflash applet drives the flash controller to progam the internal flash memory of the SAM MCU device.

## Applet initialization

The internalflash applet accepts one optional parameter to select the flash controller when initialized:

    sam-ba -p <port> -d <device> -a internalflash:help

    $ sam-ba -p serial -d pic32cxmt -a internalflash:help
    Syntax: internalflash:[<instance>]
    Parameters:
        instance   Flash controller instance
    Examples:
        internalflash      use default board settings
        internalflash:1    select Flash Controller 1 (SEFC1)

When no board settings are available, the default flash controller instance is 0 (SEFC0).

## Supported commands

The list of commands supported by the internalflash applet can be displayed with the following command:

    sam-ba -p <port> -d <device> -a internalflash -c help

    $ sam-ba -p serial -d pic32cxmt -a internalflash -c help

### The erase command

The erase command resets to 0xFF a range of erase blocks. The size of those erase blocks is given in the product datasheet.

    $ sam-ba -p serial -d pic32cxmt -a internalflash -c erase:help
    * erase - erase all or part of the memory
    Syntax:
        erase:[<addr>]:[<length>]
    Examples:
        erase                 erase all
        erase:4096            erase from 4096 to end
        erase:0x1000:0x10000  erase from 0x1000 to 0x11000
        erase::0x1000         erase from 0 to 0x1000

### The write command

The write command programs data from a binary file into the internal flash pages. The blocks containing the pages to be programmed should be erased first with the erase command. Padding bytes are added to align programmed data to the page boundary. The page size is given by the product datasheet.

    $ sam-ba -p serial -d pic32cxmt -a internalflash -c write:help
    * write - write to memory from a file
    Syntax:
        write:<filename>:[<addr>]
    Examples:
        write:bootstrap.bin         write bootstrap.bin to start of memory
        write:u-boot.bin:0x10000    write u-boot.bin at offset 0x10000

### The read command

The read command loads data from the internal flash into a binary file.

    $ sam-ba -p serial -d pic32cxmt -a internalflash -c read:help
    * read - read from memory to a file
    Syntax:
        read:<filename>:[<addr>]:[<length>]
    Examples:
        read:firmware.bin              read all to firmware.bin
        read:firmware.bin:0x1000       read from 0x1000 to end into firmware.bin
        read:firmware.bin:0x1000:1024  read 1024 bytes from 0x1000 into firmware.bin
        read:firmware.bin::1024        read 1024 bytes from start of memory into firmware.bin

### The verify commands

The verify command compares the data programmed in the internal flash with the content of a given binary file.

    $ sam-ba -p serial -d pic32cxmt -a internalflash -c verify:help
    * verify - verify memory from a file
    Syntax:
        verify:<filename>:[<addr>]
    Examples:
        verify:firmware.bin         verify that start of memory matches firmware.bin
        verify:firmware.bin:0x1000  verify that memory at offset 0x1000 matches firmware.bin

### The eraseup, readup, writeup and verifyup commands

The eraseup, readup, writeup and verifyup commands are similar to the erase, read, write and verify commands; they takes the exact same parameters. The only difference is that the *up command set is dedicated to User Signature pages whereas the other command set only applies to regular pages within the internal flash.

### The getgpnvm and setgpnvm commands

The getgpnvm and setgpnvm commands allow to read and modify GPNVM bits managed by the flash controller. Those commands accept an optional mask parameter to filter the GPNVM bits upon which the command applies. If no mask is provided, then the command applies to all GPNVM bits:

    $ sam-ba -p serial -d pic32cxmt -a internalflash -c getgpnvm:help
    * getgpnvm - get GPNVM bits
    Syntax:
        getgpnvm:[<mask>]
    Examples:
        getgpnvm               get all GPNVMs
        getgpnvm:0x1e0         get GPNVM[8:5] only
        getgpnvm:SBS_MASK      get GPNVM[8:5] only

    <mask> value can be either a number or a sequence of tokens separated by commas:
        SECURITY               (GPNVM[0]   = 1b)    : Security bit
        BMS                    (GPNVM[1]   = 1b)    : Bank Swap
        EFL_MASK               (GPNVM[4:2] = 111b)  : Erase Flash Lock mask
        EFL                    (GPNVM[4:2] != 0b)   : Erase Flash Lock set
        SBS_MASK               (GPNVM[8:5] = 1111b) : System Boot Selection
        SAMBA_MONITOR          (GPNVM[8:5] = 0000b) : SAM-BA monitor selected
        STANDARD_BOOT          (GPNVM[8:5] = 0011b) : Boot from internal flash in standard boot mode selected
        SECURE_SAMBA_MONITOR   (GPNVM[8:5] = 1001b) : secure SAM-BA monintor selected
        SECURE_BOOT            (GPNVM[8:5] = 1010b) : Boot from internal flash in secure boot mode (w/ monitor fall-back) selected
        SECURE_BOOT_NO_MONITOR (GPNVM[8:5] = 1100b) : Boot from internal flash in secure boot mode (w/o monitor fall-back) selected

    Please refer to the 'ROM Code and Boot Strategies' section of the PIC32CXMT datasheet.

The setgpnvm command also takes one mandatory parameter for the value to be set into the GPNVM bits:

    $ sam-ba -p serial -d pic32cxmt -a internalflash -c setgpnvm:help
    * setgpnvm - set GPNVM bits
    Syntax:
        setgpnvm:<value>:[<mask>]
    Examples:
        setgpnvm:0x1                     set GPNMV[0] to 1b, clear all other GPNVMs
        setgpnvm:0x0:0x1                 clear GPNVM[0]
        setgpnvm:0x060:0x1e0             set GPNVM[8:5] to 0011b
        setgpnvm:STANDARD_BOOT:SBS_MASK  set GPNVM[8:5] to 0011b

    <value> and <mask> values can be either numbers or sequences of tokens separated by commas:
        SECURITY               (GPNVM[0]   = 1b)    : Security bit
        BMS                    (GPNVM[1]   = 1b)    : Bank Swap
        EFL_MASK               (GPNVM[4:2] = 111b)  : Erase Flash Lock mask
        EFL                    (GPNVM[4:2] != 0b)   : Erase Flash Lock set
        SBS_MASK               (GPNVM[8:5] = 1111b) : System Boot Selection
        SAMBA_MONITOR          (GPNVM[8:5] = 0000b) : SAM-BA monitor selected
        STANDARD_BOOT          (GPNVM[8:5] = 0011b) : Boot from internal flash in standard boot mode selected
        SECURE_SAMBA_MONITOR   (GPNVM[8:5] = 1001b) : secure SAM-BA monintor selected
        SECURE_BOOT            (GPNVM[8:5] = 1010b) : Boot from internal flash in secure boot mode (w/ monitor fall-back) selected
        SECURE_BOOT_NO_MONITOR (GPNVM[8:5] = 1100b) : Boot from internal flash in secure boot mode (w/o monitor fall-back) selected

    Please refer to the 'ROM Code and Boot Strategies' section of the PIC32CXMT datasheet.

### The getwpmr and setwpmr commands

The getwpmr command reads whereas the setwpmr command updates the Write Protection Mode Register (EEFC_WPMR) of the selected flash controller (SEFCx). Both commands can take an optional mask parameter to filter the EEFC_WPMR bits upon which the command applies. If no mask is provided, then then command applies to the all register bits:

    $ sam-ba -p serial -d pic32cxmt -a internalflash -c getwpmr:help
    * getwpmr - get Write Protect Mode Register (EEFC_WPMR)
    Syntax:
        getwpmr:[<mask>]
    Examples:
        getwpmr                get EEFC_WPMR
        getwpmr:0x0000ff00     get bits 15:8 of EEFC_WPMR
        getwpmr:USRWP          get bit 4 of EEFC_WPMR

    <mask> value can be either a number or a sequence of tokens separated by commas:
        WPEN    : bit 0 of EEFC_WPMR
        GPNVMWP : bit 1 of EEFC_WPMR
        LOCKWP  : bit 2 of EEFC_WPMR
        ERASEWP : bit 3 of EEFC_WPMR
        USRWP   : bit 4 of EEFC_WPMR
        ERASEWL : bit 7 of EEFC_WPMR

    Please refer to the 'Secure Embedded Flash Controller (SEFC)' section of the PIC32CXMT datasheet.

The setgpnvm command also takes one mandatory parameter for the value to be set into the EEFC_WPMR register:

    $ sam-ba -p serial -d pic32cxmt -a internalflash -c setwpmr:help
    * setwpmr - set Write Protect Mode Register (EEFC_WPMR)
    Syntax:
        setwpmr:<value>:[<mask>]
    Examples:
        setwpmr:0x00000101:0x01000101 set bits 0 and 8, clear bit 24 of EEFC_WPMR
        setwpmr:0:USRWP               clear bit 4 of EEFC_WPMR

    <value> and <mask> values can be either numbers or sequences of tokens separated by commas:
        WPEN    : bit 0 of EEFC_WPMR
        GPNVMWP : bit 1 of EEFC_WPMR
        LOCKWP  : bit 2 of EEFC_WPMR
        ERASEWP : bit 3 of EEFC_WPMR
        USRWP   : bit 4 of EEFC_WPMR
        ERASEWL : bit 7 of EEFC_WPMR

    Please refer to the 'Secure Embedded Flash Controller (SEFC)' section of the PIC32CXMT datasheet.

### The getusr and setusr commands

The getusr command is used to read while the setusr command writes the User Signature Rights Register (EEFC_USR) of the selected flash controller (SEFCx). Both commands can take an optional mask parameter to filter the EEFC_USR bits upon which the command applies. If no mask is provided, then then command applies to the all register bits:

    $ sam-ba -p serial -d pic32cxmt -a internalflash -c getusr:help
    * getusr - get User Signature Rights Register (EEFC_USR)
    Syntax:
        getusr:[<mask>]
    Examples:
        getusr                 get EEFC_USR
        getusr:0x0000ff00      get bits 15:8 of EEFC_USR
        getuser:RDENUSB_MASK   get bits 7:0 of EEFC_USR

    <mask> value can be either a number or a sequence of tokens seperated by commas:
        RDENUSB_MASK  : (0xff << 0)
        RDENUSBx      : (0x01 << (x + 0)) with x in [0..7]
        WRENUSB_MASK  : (0xff << 8)
        WRENUSBx      : (0x01 << (x + 8)) with x in [0..7]
        PRIVUSB_MASK  : (0xff << 16)
        PRIVUSBx      : (0x01 << (x + 16) with x in [0..7]
        LOCKUSRB_MASK : (0xff << 24)
        LOCKUSRBx     : (0x01 << (x + 24)) with x in [0..7]

    Please refer to the 'Secure Embedded Flash Controller (SEFC)' section of the PIC32CXMT datasheet.

The setusr command also takes one mandatory parameter for the value to be set into the EEFC_USR register:

    $ sam-ba -p serial -d pic32cxmt -a internalflash -c setusr:help
    * setusr - set User Signature Rights Register (EEFC_USR)
    Syntax:
        setsur:<value>:[<mask>]
    Examples:
        setwp:0x00000101:0x01000101 set bits 0 and 8, clear bit 24 of EEFC_USR
        setwp:RDENUSB0,RDENUSB_MASK set bits 7:0 of EEFC_USR to 00000001b

    <value> and <mask> values can be either numbers or sequences of tokens seperated by commas:
        RDENUSB_MASK  : (0xff << 0)
        RDENUSBx      : (0x01 << (x + 0)) with x in [0..7]
        WRENUSB_MASK  : (0xff << 8)
        WRENUSBx      : (0x01 << (x + 8)) with x in [0..7]
        PRIVUSB_MASK  : (0xff << 16)
        PRIVUSBx      : (0x01 << (x + 16) with x in [0..7]
        LOCKUSRB_MASK : (0xff << 24)
        LOCKUSRBx     : (0x01 << (x + 24)) with x in [0..7]

    Please refer to the 'Secure Embedded Flash Controller (SEFC)' section of the PIC32CXMT datasheet.