SW Tailoring

The VelocityDRIVE-SP SW packets offered by Microchip support a given Switch-SoC along with some selected peripherals (like PHYs and flash chips). But to build a functional switch, the SoC needs to be mounted on a board, and when this board is designed, certain decisions are made. This includes:

  1. Port map and configuration

    1. What ports are used, what PHYs and what speeds

    2. Physical port numbers vs serdes/rgmii numbering

    3. etc.

  2. GPIO mappings

    1. Board reset, status LED, etc.

  3. Factory default configuration

    1. Example: if the box has a label saying the default IP is 10.0.0.1, then this configuration needs to go into the factory defaults.

As the SW is designed to support a SoC, not a board/box, some tailoring layer is needed where the decisions made when designing a given board (schematic) can be augmented into the generalized SoC SW.

This is referred to as SW-tailoring and is covered in detail in this part of the documentation. VelocityDRIVE-SP is distributed as binaries, and all the tailoring options described here can be used on the binary packets of VelocityDRIVE-SP. The mechanisms described here are the same as what Microchip uses to support their own EVBs, and the EVB tailoring is included in the binary packets as a reference example.

The board tailoring features can be boiled down to the following categories:

  1. Board-config: also referred to as the Board-YANG because we use a YANG module to guard the schema on what can be put into the board-config.

    1. This file includes all the information from the schematic of the boards, which the SW needs to know about to be able to adjust its behavior on a given board.

  2. Factory defaults: This is the configuration applied if no user configuration has been saved on the board, or if a board is being reset to factory defaults.

    1. The factory defaults are stored in the board-config file along with the other settings.

  3. EXTMOD: This is specific functionality which optionally can be provided by the customer.

    1. The extmod is stored in the board-config file along with the other settings.

  4. Secure Boot: This is about signing the artifacts with keys controlled by the customer.

1. Build process overview

To understand how the SW Tailoring is working, it is a good idea to look at the build process, which show how artifacts are generated and what are the inputs, outputs and dependencies.

1.1. EXTMOD (optional)

extmod is a load-able C library capable of letting the customer implement certain function to extend or tailor the behavioral of the binary SW packet. extmod is an optional component and if not needed, it can be skipped entirely.

Build-wise, this is the first step as it has no dependencies. The input here is the C sources, which are compiled and linked using the GCC tool-chain to generate a ELF file. The ELF file is then processed by a script which take care of extracting only the object-code, and extract information on what region needs to be executable (the code) and what needs to to be RW (initialized data and BSS)

These steps are illustrated below:

doc tailor build extmod

In the end a "extmod" file is generated, which contain the text and region information. This file will be used as input in the next step.

1.2. Board configuration

The board configuration, a CBOR encoded data structure including all the tailoring configuration, data and code. The docs/sw_refs/yang/board.yang file in the binary packet, provide the YANG schema documenting the individual fields.

The board configuration contains the following major sections:

  • board:drivers

    • This list all the driver which needs to be instantiated at boot, and provide the needed parameters. This section conceptually similar to device trees.

  • board:capabilities

    • This is used to enable/disable certain features, and to control the scale and resource consumption for a given resource.

  • board:factory_default_config

    • This is the configuration to apply when the board is reset to factory defaults.

  • board:extmod

    • This is the loadable C library from previous section.

When creating the board CBOR file the following input is needed:

  • A YAML file containing the board:drivers, board:capabilities and board:factory_default_config.

  • Optionally the extmod file from previous section.

  • The YANG catalog with all the SID files. This is needed to convert all the string based identifier to ID. This YANG catalog is part of the binary packet.

The bc2cbor will take these inputs, and generate the board.cbor file.

This process is illustrated below:

doc tailor build board cbor

The resulting output is then used as input in the next step.

1.3. Image generation

The final step is the image generation. Here the board.cbor form the earlier step is appended to the binary, then it is signed for secure boot, and wrapped into a FIP image.

This process is illustrated below:

doc tailor build img

Beside form producing a FIP, an img file is also produced. The img file contains both the bootloader and the FIP provisioned in both FW partitions. This img file can be programmed directly into the flash.

The resulting image is now ready for use.