Configuration and the Data Partition¶

When using flash to boot the XVF3610 processor, the Data Partition can be used to store commands which are executed immediately after boot-up to configure and define the functionality of the device. The following sections describe the definition of the Data Partition, how to generate, and the customisation for specific applications.

Partition file structure¶

The contents of a Data Partition are defined in a .json file which is passed to a generation script which forms the binary files used when flashing the device. The generation process is described below, after the definition .json file is described.

For the purpose of explanation consider the following example for a custom XVF3610-UA Data Partition:

{
  "comment": "Example data partition definition",
  "spispec_path": "16mbit_12.5mhz_sector_4kb.spispec",
  "regular_sector_size": "4096",
  "hardware_build": "0xFFFFFFFF",
  "item_files": [
      { "path": "input/usb_to_device_rate_48k.txt", "comment": "" },
      { "path": "input/device_to_usb_rate_48k.txt", "comment": "" },
      { "path": "input/usb_mclk_divider.txt", "comment": "" },
      { "path": "input/xmos_usb_params.txt", "comment": "" },
      { "path": "input/i2s_rate_16k.txt", "comment": "" },
      { "path": "input/led_after_boot.txt", "comment":"" }
  ]
}

Comment pairs are provided for the .json configuration, but also the individual item files:

{ "comment": "Example Comment" }

A running VocalFusion device needs to know size and geometry of its external QSPI flash in order to write firmware upgrades to it. This is added to a Data Partition in the form of a flash specification or SPI specification.

{ "spispec_path": "16mbit_12.5mhz_sector_4kb.spispec" }

The Data Partition generation process aligns various sections onto flash sectors, and needs to know the sector size (this can be found in the flash device datasheet):

{ "regular_sector_size": "4096" }

Hardware build is a custom-defined, 32bit identifier written to flash along with the application firmware. It can be used to define a unique identifier for the hardware revision or other information which cannot be overwritten by subsequent updates:

{ "hardware_build": "0xFFFFFFFF" }

Item files which contain the commands to execute (format of item files described below). An optional comment field is provided:

{ "path": "input/usb_to_device_rate_48k.txt", "comment": "" }

NOTE: Because the generator is a Python script, the paths use forward slashes irrespective of platform.

Item files¶

The item files contain the commands used to configure the system. The commands are simply added to the file in the same format as the command line control utility. For clarity, multiple item files can be included in the .json definition, each specifying a sub-set of commands relating to a particular function or aspect. Example item files for common configurations are provided in the data-partition/input directory of the release package. For example, the agc_bypass.txt item file bypasses the AGC for both output channels and contains the following commands:

SET_ADAPT_CH0_AGC 0
SET_ADAPT_CH1_AGC 0
SET_GAIN_CH0_AGC 1
SET_GAIN_CH1_AGC 1

Generating a Data Partition for custom applications¶

It is recommended that in order to create a custom Data Partition, an existing set of .json and item files is used as a template and modified as required. The release package contains example .json and item files for this purpose.

The required additional control commands should be stored in an appropriately named text file inside the data-partition/input subdirectory. For example, a file named aec_bypass.txt could be added containing the collected commands:

SET_BYPASS_AEC 1

NOTE: Only commands which are required to be set with non-default values need to be included in the item file list.

These text files are then included in the custom JSON description.

In the above example, the aec_bypass.txt is added to to a JSON description, bypass_AEC.json as shown below:

...
"item_files": [
  ...
  {
    "path": "input/aec_bypass.txt",
    "comment": ""
  }
  ...
]
...

Note

The execution order of the commands and input files can affect the behaviour of the device. Commands to configure USB and I²S should be added at the beginning of the data image.

Finally, to generate the custom data partition, the command below should be run from the data-partition directory:

python3 xvf3610_data_partition_generator.py <build_type>.json

The generator script produces two data image files; one for factory programming and one for device upgrade in a directory named output.

For the above example these files will be called:

data_partition_<build_type>_factory_v<release_version>.bin

and

data_partition_<build_type>_upgrade_v<release_version>.bin

These two binary files can be used to factory program or upgrade as described in Updating the firmware and Generation of Upgrade Image sections respectively.

A .JSON file is also produced for debugging purposes.