SW Tailoring Getting Started

The best way to get started with SW/Board tailoring is to look at the VelocityDRIVE-SP Binary packet and build the images for the supported Microchip EVBs.

This guide will walk you through the velocitydrivesp-lan969x-bin packet. The velocitydrivesp-lan966x-bin (notice lan966x instead of lan969x) is very similar, and users of this packet should use this guide as well.

The board tailoring is assumed to be done in a Linux environment capable of running Docker images. This can either be a native Linux environment, WSL, or a virtual machine. See the Prepare of PC environment for guidance on how to install dr and how to setup Docker.

1. Docker preparation

The Docker image used here is not available on any public Docker registry and needs to be manually downloaded and imported. The dr command will attempt to lazy download if the Docker image is not found locally. This lazy download will not work from outside the Microchip network.

Download the build-env-<VERSION>.docker.gz Docker image from here

Extract and load the image into your Docker daemon:

$ gunzip -c build-env-<VERSION>.docker.gz | docker load

At this point, the Docker image should be imported and ready to use by the dr command.

2. Extract and build EVBs

With the Docker image in place, we can download the binary packet, extract it, and enter the folder containing the files:

$ tar -xzf velocitydrivesp-lan969x-bin-<VERSION>.tar.gz
$ cd velocitydrivesp-lan969x-bin-<VERSION>

Test that the dr command is working and that the Docker image has been loaded correctly:

$ dr ls -lagG
total 408
drwxr-xr-x 10    340 Mar 11 15:29 .
drwxrwxrwt  3     60 Mar 11 15:29 ..
drwxr-xr-x  4    100 Mar 11 14:49 build-lan969x
drwxr-xr-x  2     60 Mar 11 14:45 .cmake
-rw-r--r--  1   1450 Mar 11 14:45 CMakeLists.txt
-rw-r--r--  1    969 Mar 11 14:45 CMakePresets.json
-rw-r--r--  1   1016 Mar 11 14:45 .deps.json
-rw-r--r--  1     64 Mar 11 15:29 .docker-container-id
-rw-r--r--  1   1271 Mar 11 14:45 .docker.env
drwxr-xr-x  3     60 Mar 11 14:45 docs
drwxr-xr-x  4     80 Mar 11 14:45 extmod
drwxr-xr-x  6    120 Mar 11 14:45 support
drwxr-xr-x  3     80 Mar 11 14:45 target
drwxr-xr-x  3     60 Mar 11 14:45 third-party
drwxr-xr-x  5    160 Mar 11 14:45 utils
-rw-r--r--  1 390994 Mar 11 14:46 .velocitysp-yang-mods-cache
-rw-r--r--  1    318 Mar 11 14:45 .version.yaml

Build the firmware image files for the EVBs supported in the given packet:

$ rm -rf build-lan969x
$ dr cmake --workflow --preset lan969x
Executing workflow step 1 of 2: configure preset "lan969x"

Preset CMake variables:

  CMAKE_BUILD_TYPE:STRING="RelWithDebInfo"
  CMAKE_TOOLCHAIN_FILE:FILEPATH="/tmp/velocitydrivesp-lan969x-bin-a40143b6b/target/lan969x/toolchainfile.cmake"
  LM_PRESET:STRING="lan969x"

-- The C compiler identification is GNU 11.4.0
-- The ASM compiler identification is GNU
-- Found assembler: /usr/bin/aarch64-linux-gnu-gcc
-- Detecting C compiler ABI info
-- Detecting C compiler ABI info - done
-- Check for working C compiler: /usr/bin/aarch64-linux-gnu-gcc - skipped
-- Detecting C compile features
-- Detecting C compile features - done
-- Target family: lan969x, Preset: lan969x
-- Configuring done (0.2s)
-- Generating done (0.0s)
-- Build files have been written to: /tmp/velocitydrivesp-lan969x-bin-a40143b6b/build-lan969x

Executing workflow step 2 of 2: build preset "lan969x"

[14/22] lan969x_extmod_gen
Generating module file from input: lan969x_extmod
[19/22] Generating lan969x_EV89P81A.img, lan969x_EV89P81A.fip
  VDSP_BIN_LAN969x_no_cbor.bin            764kb (limit: 800kb/95%)
  lan969x_EV89P81A.cbor                     1kb (limit: 16kb/9%)
  lan969x_EV89P81A-secure.fip              91kb (limit: 120kb/76%)
  lan969x_EV89P81A.fip                    887kb (limit: 896kb/99%)
[20/22] Generating lan969x_EV23X71A.img, lan969x_EV23X71A.fip
  VDSP_BIN_LAN969x_no_cbor.bin            764kb (limit: 800kb/95%)
  lan969x_EV23X71A.cbor                     1kb (limit: 16kb/11%)
  lan969x_EV23X71A-secure.fip              91kb (limit: 120kb/76%)
  lan969x_EV23X71A.fip                    887kb (limit: 896kb/99%)
[21/22] Generating lan969x_EV09P11A_AUTO.img, lan969x_EV09P11A_AUTO.fip
  VDSP_BIN_LAN969x_AUTO_no_cbor.bin       764kb (limit: 800kb/95%)
  lan969x_EV09P11A_auto.cbor                1kb (limit: 16kb/7%)
  lan969x_EV09P11A_AUTO-secure.fip         91kb (limit: 120kb/76%)
  lan969x_EV09P11A_AUTO.fip               887kb (limit: 896kb/99%)
[22/22] Generating lan969x_EV89P81A_AUTO.img, lan969x_EV89P81A_AUTO.fip
  VDSP_BIN_LAN969x_AUTO_no_cbor.bin       764kb (limit: 800kb/95%)
  lan969x_EV89P81A_auto.cbor                1kb (limit: 16kb/9%)
  lan969x_EV89P81A_AUTO-secure.fip         91kb (limit: 120kb/76%)
  lan969x_EV89P81A_AUTO.fip               887kb (limit: 896kb/99%)
$

See the generated output files:

$ ls -1 build-lan969x/target/lan969x/*.img
build-lan969x/target/lan969x/lan969x_EV09P11A_AUTO.img
build-lan969x/target/lan969x/lan969x_EV23X71A.img
build-lan969x/target/lan969x/lan969x_EV89P81A_AUTO.img
build-lan969x/target/lan969x/lan969x_EV89P81A.img

3. Add a custom board

Adding a new board is a matter of creating a configuration file describing the board, and then adding a build target compiling this configuration file.

The recommended way to do this is to copy the configuration file from one of the EVBs (the one being most similar) and then edit it to reflect the changes from the EVB to the custom board.

cp target/lan969x/board-config/lan9698TSN-ev89p81a.yaml \
   target/lan969x/board-config/lan9698TSN-custom.yaml

Add the board in target/lan969x/CMakeLists.txt by doing the following:

Add another call of the lm_board_config_to_cbor macro to convert the YAML file (the one we just copied) to CBOR.
Add another call of the LAN969X_IMAGE macro to combine the executable and the CBOR file from above, and generate image files.
1. In this step, VelocityDRIVE-SP variant is also selected. In the case of LAN969x, the choice is between the automotive and the non-automotive variant.

The changes needed to be done are shown in the diff below:

diff --git a/target/lan969x/CMakeLists.txt b/target/lan969x/CMakeLists.txt
index 6469f33..a95c179 100644
--- a/target/lan969x/CMakeLists.txt
+++ b/target/lan969x/CMakeLists.txt
@@ -35,6 +35,10 @@ lm_board_config_to_cbor(TARGET   board_config_lan9698TSN_ev89p81a
                         CBOR_OUT ${CMAKE_CURRENT_BINARY_DIR}/lan969x_EV89P81A.cbor
                         YAML_IN  ${CMAKE_CURRENT_SOURCE_DIR}/board-config/lan9698TSN-ev89p81a.yaml)

+lm_board_config_to_cbor(TARGET   board_config_lan9698TSN_custom
+                        CBOR_OUT ${CMAKE_CURRENT_BINARY_DIR}/lan969x_custom.cbor
+                        YAML_IN  ${CMAKE_CURRENT_SOURCE_DIR}/board-config/lan9698TSN-custom.yaml)
+
 lm_board_config_to_cbor(TARGET   board_config_lan9698TSN_ev89p81a_auto
                         CBOR_OUT ${CMAKE_CURRENT_BINARY_DIR}/lan969x_EV89P81A_auto.cbor
                         YAML_IN  ${CMAKE_CURRENT_SOURCE_DIR}/board-config/lan9698TSN-ev89p81a.yaml
@@ -70,3 +74,4 @@ LAN969X_IMAGE(TARGET EV23X71A          BIN VDSP_BIN_LAN969x          CBOR board_
 LAN969X_IMAGE(TARGET EV09P11A_AUTO     BIN VDSP_BIN_LAN969x_AUTO     CBOR board_config_lan9692VAO_ev09p11a_auto)
 LAN969X_IMAGE(TARGET EV89P81A          BIN VDSP_BIN_LAN969x          CBOR board_config_lan9698TSN_ev89p81a)
 LAN969X_IMAGE(TARGET EV89P81A_AUTO     BIN VDSP_BIN_LAN969x_AUTO     CBOR board_config_lan9698TSN_ev89p81a_auto)
+LAN969X_IMAGE(TARGET custom-board      BIN VDSP_BIN_LAN969x_AUTO     CBOR board_config_lan9698TSN_custom)

Build again, and confirm the new image is being built:

$ dr cmake --workflow --preset lan969x
Executing workflow step 1 of 2: configure preset "lan969x"

Preset CMake variables:

  CMAKE_BUILD_TYPE:STRING="RelWithDebInfo"
  CMAKE_TOOLCHAIN_FILE:FILEPATH="/tmp/velocitydrivesp-lan969x-bin-a40143b6b/target/lan969x/toolchainfile.cmake"
  LM_PRESET:STRING="lan969x"

-- Target family: lan969x, Preset: lan969x
-- Configuring done (0.0s)
-- Generating done (0.0s)
-- Build files have been written to: /tmp/velocitydrivesp-lan969x-bin-a40143b6b/build-lan969x

Executing workflow step 2 of 2: build preset "lan969x"

[2/2] Generating lan969x_custom-board.img, lan969x_custom-board.fip
  VDSP_BIN_LAN969x_AUTO_no_cbor.bin       764kb (limit: 800kb/95%)
  lan969x_custom.cbor                       1kb (limit: 16kb/9%)
  lan969x_custom-board-secure.fip          91kb (limit: 120kb/76%)
  lan969x_custom-board.fip                887kb (limit: 896kb/99%)

$ ls -1 build-lan969x/target/lan969x/*custom*
build-lan969x/target/lan969x/lan969x_custom-board.bin
build-lan969x/target/lan969x/lan969x_custom-board.crt
build-lan969x/target/lan969x/lan969x_custom-board.fip
build-lan969x/target/lan969x/lan969x_custom-board.img
build-lan969x/target/lan969x/lan969x_custom-board-secure.fip
build-lan969x/target/lan969x/lan969x_custom.cbor