How to guides

10, /* 1. libflash device ID */

This value is returned by libflash on a call to the function fl_getFlashType so that
the application can identify the connected flash device.

10,                     /* 1.  libflash device ID */
256,                    /* 2.  Page size */

These values specify the size of each page in bytes and the total number
of pages across all available sectors. On the M25P10-A datasheet, these
can be found from the following paragraph on page 6:

The memory is organized as 4 sectors, each containing 128 pages.
Each page is 256 bytes wide. Thus, the whole memory can be viewed as
consisting of 512 pages, or 131,072 bytes.

3,                      /* 4.  Address size */

This value specifies the number of bytes used to represent an address.
the table below reproduces the part of the M25P10-A
datasheet that provides this information. In the table, all instructions
that require an address take three bytes.

4,                      /* 5.  Clock divider */

This value is used to determine the clock rate for interfacing with the
SPI device. For a value of n, the SPI clock rate used is 100/2*n MHz.
libflash supports a maximum of 12.5MHz.

The table below reproduces the part of the M25P10-A
datasheet that provides this information. The AC characteristics table
shows that all instructions used in the configuration file, as discussed
throughout this document, can operate at up to 25MHz. This is faster than
libflash can support, so the value 4 is provided to generate a 12.5MHz clock.

In general, if the SPI device supports different clock rates for
different commands used by libflash, the lowest value must be specified.

0x9f,                   /* 6.  RDID cmd */
0,                      /* 7.  RDID dummy bytes */
3,                      /* 8.  RDID data size in bytes */
0x202011,               /* 9.  RDID manufacturer ID */

Most flash devices have a hardware identifier that can be used to
identify the device. This is used by libflash when one or more flash
devices are supported by the application to determine which type of
device is connected. The sequence for reading a device ID is typically
to issue an RDID (read ID) command, wait for zero or more dummy bytes,
and then read one or more bytes of data.

Table 4 on page 17 of M25P10-A datasheet
reproduces the part of the
M25P10-A datasheet that provides this information. The row for the
instruction RDID shows that the command value is 0x9f, that there
are no dummy bytes, and one to three data bytes. As shown in
Table 5 on page 19 of M25P10-A datasheet
and Figure 9 on page 19 of M25P10-A datasheet
,
the amount of data read depends on whether just the manufacturer ID
(first byte) is required, or whether both the manufacturer ID and the
device ID (second and third bytes) are required. All three bytes are
needed to uniquely identify the device, so the manufacturer ID is
specified as the three-byte value 0x202011.

Figure 9 on page 19 of M25P10-A datasheet

In general, if there is a choice of RDID commands then the JEDEC
compliant one should be preferred. Otherwise, the one returning the
longest ID should be used.

0xD8,                   /* 10. SE cmd */
0,                      /* 11. SE full sector erase */

Most flash devices provide an instruction to erase all or part of a
sector.

Table 4 on page 17 of M25P10-A datasheet
reproduces the part of the
M25P10-A datasheet that provides this information. The row for the
instruction SE shows that the command value is 0xd8. On the M25P10-A
datasheet, the amount of data erased can be found from the first
paragraph on page 28:

The Sector Erase (SE) instruction sets to ‘1’ (FFh) all bits inside
the chosen sector.

In this example the SE command erases all of the sector, so the SE data
value is set to 0. If the number of bytes erased is less than a full
sector, this value should be set to the number of bytes erased.

0x06,                   /* 12. WREN cmd */
0x04,                   /* 13. WRDI cmd */

Most flash devices provide instructions to enable and disable writes to
memory. Table 4 on page 17 of M25P10-A datasheet
reproduces the part
of the M25P10-A datasheet that provides this information. The row for
the instruction WREN shows that the command value is 0x06, and the
row for the instruction WRDI shows that the command value is 0x04.

PROT_TYPE_SR,           /* 14. Protection type */
{{0x0c,0x0},{0,0}},     /* 15. SR protect and unprotect cmds */

Some flash devices provide additional protection of sectors when writes
are enabled. For devices that support this capability, libflash attempts
to protect the flash image from being accidentally corrupted by the
application. The supported values for protection type are:

PROT_TYPE_NONE

The device does not provide protection

PROT_TYPE_SR

The device provides protection by writing the status register

PROT_TYPE_SECS

The device provides commands to protect individual sectors

The protection details are specified as part of a construction of the
form:

{{a,b},{c,d}}

If the device does not provide protection, all values should be set to
0. If the device provides SR protection, a and b should be set to
the values to write to the SR to protect and unprotect the device, and
c and d to 0. Otherwise, c and d should be set to the values to
write to commands to protect and unprotect the device, and a and b
to 0.

Table 2 on page 13 of M25P10-A datasheet
and Table 6 on page 20 of M25P10-A datasheet

reproduce the parts of the M25P10-A datasheet that provide this information.
The first table shows that BP0 and BP1 of the status register should be set to
1 to protect all sectors, and both to 0 to disable protection. The second table
shows that these are bits 2 and 3 of the SR.

Table 6 on page 20 of M25P10-A datasheet

0x02,                   /* 16. PP cmd */

Devices are programmed either a page at a time or a small number of
bytes at a time. If page programming is available it should be used, as
it minimizes the amount of data transmitted over the SPI interface.

Table 4 on page 17 of M25P10-A datasheet
reproduces the part of the
M25P10-A datasheet that provides this information. In the table, a page
program command is provided and has the value 0x02.

If page programming is not supported, this value is a concatenation of
three separate values. Bits 0..7 must be set to 0. Bits 8..15 should
contain the program command. Bits 16..23 should contain the number of
bytes per command. The libflash library requires that the first program
command accepts a three byte address but subsequent program command use
auto address increment (AAI).

An example of a device without a PP command is the ESMT
F25L004A
.
the table below reproduces the part of the F25L004A
datasheet that provides this information. In the timing diagram, the AAI
command has a value 0xad, followed by a three-byte address and two
bytes of data.

The corresponding entry in the specification file is:

0x00|(0xad<<8)|(2<<16), /* No PP, have AAI for 2 bytes */

0x0b,                   /* 17. READ cmd */
1,                      /* 18. READ dummy bytes*/

The sequence for reading data from a device is typically to issue a READ
command, wait for zero or more dummy bytes, and then read one or more
bytes of data.

Table 4 on page 17 of M25P10-A datasheet
reproduces the part of the
M25P10-A datasheet that provides this information. There are two
commands that can be used to read data: READ and FAST_READ. The row for
the instruction FAST_READ shows that the command value is 0x0b,
followed by one dummy byte.

SECTOR_LAYOUT_REGULAR,  /* 19. Sector layout */
{32768,{0,{0}}},        /* 20. Sector sizes */

The first value specifies whether all sectors are the same size. The
supported values are:

SECTOR_LAYOUT_REGULAR

The sectors all have the same size

SECTOR_LAYOUT_IRREGULAR

The sectors have different sizes

On the M25P10-A datasheet, this can be found from the following
paragraph on page 15:

The memory is organized as:

• 131,072 bytes (8 bits each)
• 4 sectors (256 Kbits, 32768 bytes each)
• 512 pages (256 bytes each).

The sector sizes is specified as part of a construction:
{a, {b, {c}}}. For regular sector sizes, the size is specified in
a. The values of b and c should be 0.

For irregular sector sizes,
the size number of sectors is specified in b. The log base 2 of the
number of pages in each sector is specified in c. The value of a
should be 0. An example of a device with irregular sectors is the AMIC
A25L80P
.
Table 2 on page 7 of A25L80P datasheet
reproduces the part of this
datasheet that provides the sector information.

The corresponding entry in the specification file is:

SECTOR_LAYOUT_IRREGULAR,
    {0,{20,{4,4,5,6,7,8,8,8,8,8,8,8,8,8,8,8,8,8,8,8}}},

0x05,                   /* 21. RDSR cmd*/
0x01,                   /* 22. WRSR cmd */
0x01,                   /* 23. WIP bit mask */

Most flash devices provide instructions to read and write a status
register, including a write-in-progress bit mask.

Table 4 on page 17 of M25P10-A datasheet
reproduces the part of the
M25P10-A datasheet that documents the RDSR and WRSR commands. The
diagram in Table 6 on page 20 of M25P10-A datasheet
shows that the WIP
bit is in bit position 0 of the SR, resulting in a bit mask of 0x01.

A configuration file can be used with libflash or xflash. The example
program below uses libflash to connect to a M25P10-A device, the
configuration parameters which are specified in m25p10a.

#include "platform.h"
#include "flash.h"
#include "flashlib.h"
#include "stdio.h"
#include "stdlib.h"

fl_PortHolderStruct SPI = {PORT_SPI_MISO,
                           PORT_SPI_SS,
                           PORT_SPI_CLK,
                           PORT_SPI_MOSI,
                           XS1_CLKBLK_1};

fl_DeviceSpec myFlashDevices[] = {
 {
   #include "m25p10a"
 }
};

int flash_access() {
  if (fl_connectToDevice(SPI, myFlashDevices,
      sizeof(myFlashDevices)/sizeof(fl_DeviceSpec)) != 0) {
    printf("No supported flash devices found.\n"); exit(1);
  } else {
  printf("Found custom flash device m25p10a.\n"); exit(0);
  }
  return 0;
}

int main() {
  // multicore main is required for xscope
  par {
    on stdcore[0] : flash_access();
  }
}

The custom flash device must be specified in the XN file as follows:

<ExternalDevices>
  <Device NodeId="0" Tile="0" Name="bootFlash"
          Class="SPIFlash" Type="M25P10A">
    <Attribute Name="PORT_SPI_MISO" Value="PORT_SPI_MISO" />
    <Attribute Name="PORT_SPI_SS" Value="PORT_SPI_SS" />
    <Attribute Name="PORT_SPI_CLK" Value="PORT_SPI_CLK" />
    <Attribute Name="PORT_SPI_MOSI" Value="PORT_SPI_MOSI" />
  </Device>
</ExternalDevices>

To compile an image file that links to the lib flash library,
start the command-line tools

and enter the following command:

xcc main.xc -o prog.xe -target=target_with_custom_flash.xn -lflash

To generate an image file in the xCORE flash format, which can be
subsequently programmed into the above flash device,
enter the following command:

xflash prog.xe -o imgfile –spi-spec m25p10a

XFLASH generates an image for the custom flash device, which it writes
to the specified image file.

When selecting a flash device for use with an xCORE device, the following
guidelines are recommended:

• If access to the data partition is required, select a device with
  fine-grained erase granularity, as this will minimize the gaps
  between the factory and upgrade images, and will also minimize the
  amount of data that libflash needs to buffer when writing data.
• Select a device with sector protection if possible, to ensure that
  the bootloader and factory image are protected from accidental
  corruption post-deployment.
• Select a flash speed grade suitable for the application. Boot times
  are minimal even at low speeds.

The xCORE AES Module authenticates and decrypts programs from SPI flash
devices. When programmed into a device, it enables the following secure
boot procedure, as illustrated in the figure below.

Secure boot procedure used with the AES Module

1. The device loads the primary bootloader from its ROM, which detects
   that the secure boot bit is set in the OTP and then loads and
   executes the AES Module from OTP.
2. The AES Module loads the flash loader into RAM over SPI.
3. The AES Module authenticates the flash loader using the CMAC-AES-128
   algorithm and the 128-bit authentication key. If authentication
   fails, boot is halted.
4. The AES Module places the authentication key and decryption key in
   registers and jumps to the flash loader.

The flash loader performs the following operations:

1. Selects the image with the highest number that validates against its
   CRC.
2. Authenticates the selected image header using its CMAC tag and
   authentication key. If the authentication fails, boot is halted.
3. Authenticates, decrypts and loads the table of program/data segments
   into memory. If any images fail authentication, the boot halts.
4. Starts executing the program.

For multi-node systems, the AES Module is written to the OTP of one
tile, and a secure boot-from-xConnect Link protocol is programmed into all
other tiles.

You can activate the AES Module at any time during development or device
manufacture. In a development environment, you can activate the module
but leave the security bits unset, enabling:

• XFLASH to use the device to load programs onto flash memory,
• XGDB to debug programs running on the device, and
• XBURN to later write additional OTP bits to protect the device.

In a production environment, you must protect the device to prevent the
keys from being read out of OTP by the end user.

To program the AES Module into the xCORE device on your development
board, start the command-line tools

and enter the following commands:

1. xburn –genkey keyfile

   XBURN writes two random 128-bit keys to keyfile. The first line is
   the authentication key, the second line the decryption key.

   The keys are generated using the open-source library crypto++. If you
   prefer, you can create this file and provide your own keys.

2. xburn -l

   XBURN prints an enumerated list of all JTAG adapters connected to
   your PC and the devices on each JTAG chain, in the form:

   ID - NAME (ADAPTER-SERIAL-NUMBER)

3. xburn –id ID –lock keyfile –target-file target.xn –enable-jtag –disable-master-lock

   XBURN writes the AES Module and security keys to the OTP memory of
   the target device and sets its secure boot bit. The SPI ports used
   for booting are taken from the XN file (see ExternalDevice
   ).

To encrypt your program and write it to flash memory, enter the command:

xflash –id ID bin.xe –key keyfile

To protect the xCORE device, preventing any further development, enter the command:

xburn –id ID –target-file target.xn –disable-jtag –lock keyfile

In production manufacturing environments, the same program is typically
programmed into multiple SPI devices.

To generate an encrypted image in the xCORE flash format,
start the command-line tools

and enter the following command:

xflash prog.xe -key keyfile -o image-file

This image can be programmed directly into flash memory using a
third-party flash programmer, or it can be programmed using XFLASH (via
an xCORE device). To program using XFLASH, enter the following commands:

1. xflash -l

   XFLASH prints an enumerated list of all JTAG adapters connected to
   your PC and the devices on each JTAG chain, in the form:

   ID - NAME (ADAPTER-SERIAL-NUMBER)

2. xflash –id ID –target-file platform.xn –write-all image-file

   XFLASH generates an image in the xCORE flash format that contains a
   first stage loader and factory image comprising the binary and data
   segments from your compiled program. It then writes this image to
   flash memory using the xCORE device.

The XN file must define an SPI flash device and specify the four ports
of the xCORE device to which it is connected (see ExternalDevice
).

In production manufacturing environments, the same keys are typically
programmed into multiple xCORE devices.

To generate an image that contains the AES Module and security keys to
be written to the OTP, start the command-line tools

and enter the following commands:

1. xburn –genkey keyfile

   XBURN writes two random 128-bit keys to keyfile. The first line is
   the authentication key, the second line the decryption key.

   The keys are generated using the open-source library crypto++. If you
   prefer, you can create this file and provide your own keys.

2. xburn –target-file target.xn –lock keyfile -o aes-image.otp

   XBURN generates an image that contains the AES Module, security keys
   and the values for the security bits.

The image contains the keys and must be kept secret.

To write the AES Module and security bits to a device in a production
environment, enter the following commands:

1. xburn -l

   XBURN prints an enumerated list of all JTAG adapters connected to the
   host and the devices on each JTAG chain, in the form:

   ID - NAME (ADAPTER-SERIAL-NUMBER)

2. xburn –id ID –target-file target.xn aes-image.otp

   XBURN loads a program onto the device that writes the AES Module
   and security keys to the OTP, and sets its secure boot bits. XBURN
   returns 0 for success or non-zero for failure.

The following options are used to specify the OTP image and security register contents.

• xe-file

  Specifies bootable images to be constructed from the loadable segments from
  xe-file and a default set of security bits
  .

• otp-file

  Specifies the OTP segments from otp-file which includes the security register value.

• –lock keyfile

  Specifies the XCORE AES boot module
  and a
  default set of security bits
  .

• –genkey keyfile

  Outputs to keyfile two 128-bit keys used for authentication and decrpytion. The
  keys are generated using the open-source library crypto++.

  This option is not valid with --burn or --lock.

• –mac-address mac

  Writes a MAC address to the end of the OTP. The MAC address should be specified
  in the form 12:34:56:78:9A:BC. Multiple MAC addresses can be written by
  specifying the --mac-address option multiple times. MAC addresses are written
  to the OTP in the order the options appear.

• –serial-number serial

  Writes a 32-bit serial number to the end of the OTP.

• –read

  Prints the entire contents of the OTP.

• –help

  Prints a description of the supported command-line options.

• –version

  Displays the version number and copyrights.

The following options are used to specify the contents of the OTP security register,
overriding the default options for burning XE images, OTP images and the AES module,
as given in the table below.

• –enable-otp-boot

  Enables boot from OTP.

• –disable-jtag

  Disables JTAG access. Once disabled, it is not possible to gain debug access to the
  device or to read the OTP.

  This option does not disable boundary scan.

• –disable-plink-access

  Disables access to the plink registers from other tiles. Disabling plink access
  restricts all access of the registers of each plinks to the tile local to that plink.

• –disable-global-debug

  Prevents the device from participating in global debug. Disabling global debug
  prevents the tiles from entering debug using the global debug pin.

• –enable-master-lock

  Enables the OTP master lock. No further modification of the OTP is permitted.

The following options are used to specify the target hardware platform.

• –list-devices

  -l

  Prints an enumerated list of all JTAG adapters connected to the
  host and the devices on each JTAG chain, in the form:

  ID - NAME    (ADAPTER-SERIAL-NUMBER)

  The adapters are ordered by their serial numbers.

• –id ID

  Specifies the adapter connected to the target hardware.

• –adapter-id ADAPTER-SERIAL-NUMBER

  Specifies the serial number of the adapter connected to the target hardware.

• –jtag-speed n

  Sets the divider for the JTAG clock to n. The corresponding JTAG clock speed is
  6/(n+1)MHz. The default value is 0 (6MHz).

• –spi-div n

  Sets the divider used in the AES Module for the SPI clock to n. The corresponding
  SPI clock speed is set to 100/(2n) MHz. The deafult value is 20 (2.5MHz).

  This option is only valid with --lock.

• –target-file xn-file

  Specifies xn-file as the target platform.

• –target platform

  Specifies a target platform. The platform configuration must be specified in the file
  platform.xn, which is searched for in the paths specified by the XCC_DEVICE_PATH
  environment variable (see XCC_DEVICE_PATH
  ).

By default, XBURN writes the specified OTP images to the target platform.

• -o otp-file

  Place output in otp-file, disabling programming.

• –make-exec xe-file

  Place an executable in xe-file that when run on an xCORE device performs the
  specified OTP burning operation; disables programming.

  The XE file can be run later using XRUN.

• –force

  -f

  Do not prompt before writing the OTP. This is not default.

• –size-limit n

  Limits the amounts of OTP memory written to the first n bytes of the OTP.
  If the image doesn’t fit within the specified limit an error will be given.

• xe-file

  Specifies an XE file to simulate.

• --max-cycles n

  Exits when n system cycles is reached.

• --plugin name args

  Loads a plugin DLL. The format of args is determined by the plugin;
  if args contains any spaces, it must be enclosed in quotes.

• --stats

  On exit, prints the following:

  • A breakdown of the instruction counts for each logical core.
  • The number of data and control tokens sent through the switches.

• --help

  Prints a description of the supported command line options.

• --version

  Displays the version number and copyrights.

• --warn-resources

  Prints (on standard error) warning messages for the following:

  • A timed input or output operation specifies a time in the past.
  • The data in a buffered port’s transfer register is overwritten
    before it is input by the processor.

• --warn-stack

  Turns on warnings about possible stack corruption.

  XSIM prints a warning if one XC task attempts to read
  or write to another task’s workspace. This can happen if the stack
  space for a task is specified using either #pragma stackfunction

  or #pragma stackcalls
  .

• --no-warn-registers

  Don’t warn when a register is read before being written.

• --trace

  -t

  Turns on instruction tracing for all tiles (see Trace output for XS1 processors
  ).

• --trace-to file

  Turns on instruction tracing for all tiles. The trace is output to
  file.

• --disable-rom-tracing

  Turns off tracing for all instructions executed from ROM.

• --enable-fnop-tracing

  Turns on tracing of FNOP instructions.

• --vcd-tracing args

  Enables signal tracing. The trace data is output in the standard VCD
  file format.

  If args contains any spaces, it must be enclosed in quotes. Its
  format is:

  global-options_opt < -tile name <trace-options^*>^*>

  The global options are:

  • -pads

    Turns on pad tracing.

  • -o file

    Places output in file.

  The trace options are specific to the tile associated with the XN
  core declaration name, for example tile[0].

  The trace options are:

  • -ports

    Turns on port tracing.

  • -ports-detailed

    Turns on more detailed port tracing.

  • -cycles

    Turns on clock cycle tracing.

  • -clock-blocks

    Turns on clock block tracing.

  • -cores

    Turns on logical core tracing.

  • -instructions

    Turns on instruction tracing.

  To output traces from different nodes, tiles or logical cores to different
  files, this option can be specified multiple times.

  For example, the following command configures the simulator to trace
  the ports on tile[0] to the file trace.vcd.

  xsim a.xe –vcd-tracing “-o trace.vcd -start-disabled -tile tile[0] -ports”

  Tracing by the VCD plugin can be enabled and disabled using the
  _traceStart() and _traceStop() syscalls. The -start-disabled argument disables
  the vcd tracing from the start, allowing the user to enable/disable only those sections
  of code where tracing is desired. For example:

  #include <xs1.h>
  #include <syscall.h>
  
  port p1 = XS1_PORT_1A;
  
  int main() {
     p1 <: 1;
     p1 <: 0;
  
     _traceStart();
     p1 <: 1;
     p1 <: 0;
     _traceStop();
  
     p1 <: 1;
     p1 <: 0;
  
     return 0;
  }
  

The XMOS Loopback plugin configures any two ports on the target platform
to be connected together. The format of the arguments to the plugin are:

• -pin package pin

  Specifies the pin by its name on a package datasheet. The value of
  package must match the Id attribute of a Package node

  in the XN file used to compile the program.

• -port name n offset

  Specifies n pins that correspond to a named port.

  The value of name must match the Name attribute of a
  Port node

  in the XN file used to compile the program.

  Setting offset to a non-zero value specifies a subset of the
  available pins.

• -port tile p n offset

  Specifies n pins that are connected to the port p on a tile.

  The value of tile must match the Reference attribute of a
  Tile node
  in the XN file used to compile the program.

  p can be any of the port identifiers defined in <xs1.h>. Setting
  offset to a non-zero value specifies a subset of the available pins.

The plugin options are specified in pairs, one for each end of the
connection. For example, the following command configures the simulator
to loopback the pin connected to port XS1_PORT_1A on tile[0]
to the pin defined by the port UART_TX in the program.

xsim uart.xe –plugin LoopbackPort.dll ‘-port tile[0] XS1_PORT_1A 1 0 -port UART_TX 1 0’

• --xscope args

  Enables xSCOPE.
  file format.

  If args contains any spaces, it must be enclosed in quotes.
  One of the following 2 options is mandatory:

  • -offline <filename>

    Runs with xSCOPE in offline mode, placing the xSCOPE output in the given file.

  • -realtime <URL:port>

    Runs with xSCOPE in realtime mode, sending the xSCOPE output in the given URL:port.

  The following argument is optional:

  • -limit <num records>

    Limts the xSCOPE output records to the given number.

For example, the following will run xsim with xSCOPE enabled in offline mode:

xsim app.xe –xscope “-offline xscope.xmt”

For example, the following will run xsim with xSCOPE enabled in reatime mode:

xsim app.xe –xscope “-realtime localhost:12345”