Custom Board Cloner Tool - Adding Support for a New Hardware Platform in DriveOS#

Overview#

The Custom Board Cloner tool helps the process of adding new platform support in DriveOS. Instead of manually copying and modifying numerous configuration files, makefiles, and device tree files, this tool performs all operations automatically.

For example, when adding support for a new custom hardware platform, a platform configuration can be created based on an existing reference platform (such as creating p3981-10-sw03 based on the reference platform p3960-10-sw03). This tool handles all the file copying, renaming, and configuration updates automatically.

Key Features#

Clones all necessary configuration files and directories
Automatically updates platform names throughout the codebase
SDK/SoC version support:
- SoC: Thor (T264)
- SDK: 7.2.2.0 and later

Limitations

The Custom Board Cloner tool has the following limitations:

Platform Name Format: Platform names (both for reference and new platforms) provided to this tool need to have the following format: <Platform name>-<Platform SKU>-<Version>. Example: p3960-10-sw03
Safety option (``–safety``): Only supported in QNX NSR SR SDK packages; requires the drive-foundation-safety directory. Not applicable in the Automotive Source Repository or standard SDK packages.

Tool Location#

The Custom Board Cloner tool location depends on the workspace:

In SDK Package:

${NV_WORKSPACE}/drive-foundation/tools/custom_board_cloner/custom_board_cloner.py

In Automotive Source Repository:

${NV_WORKSPACE}/foundation/tools/custom_board_cloner/custom_board_cloner.py

Usage#

Basic Syntax#

python3 ./custom_board_cloner.py --original <original-board> --new <new-board> -p <path>

Command Line Arguments#

Required Arguments#

Argument	Short	Description	Example
`--original`	`-o`	Name of the existing reference platform to clone from	`p3960-10-sw03`
`--new`	`-n`	Name for the new custom platform	`p3981-10-sw03`
`--path`	`-p`	Path to `/drive` directory in SDK package or `${TOP}` directory in Automotive Source Repository	`/home/user/drive`

Optional Arguments#

Argument	Short	Description	Default
`--force`	`-f`	Force modifications, even if the new platform is already present in the workspace, Overwrites any existing directories related to the new platform.	`False`
`--debug`	`-d`	Preserve backup directory for debugging	`False`
`--override_board_config`	N/A	Path to a JSON file containing board configuration overrides to apply to the cloned board’s JSON config files after cloning completes. If omitted, no overrides are applied.	None (no overrides)
`--safety`	`-sr`	When in a QNX NSR SR SDK package, run the cloner against the safety foundation (`drive-foundation-safety`) instead of `drive-foundation`. Only supported in QNX NSR SR SDK packages; not applicable in the Automotive Source Repository or standard SDK packages.	`False`
`--help`	`-h`	Show help message and exit	N/A

Board Configuration Override (`--override_board_config`)#

When --override_board_config is provided, the tool applies the given JSON overrides to the cloned board’s configuration files after cloning completes. This enables certain platform parameters to be customized without manual editing of the generated JSON files.

Override file format#

The override file must be valid JSON with the following structure:

{
  "global": {
    "parameter_key": "parameter_value"
  },
  "config_filename": {
    "parameter_key": "parameter_value"
  },
  "global_signed_customer_data": {
    "parameter_key": "parameter_value"
  },
  "signed_customer_data_filename": {
    "parameter_key": "parameter_value"
  }
}

Override sections#

Top-level keys identify which config files to update:

global — Parameters applied to all board configuration JSON files (excluding signed customer data files).
config_filename — Parameters applied to a specific board configuration file (e.g., <board_name>.json or <board_name>_thor_u.json).
global_signed_customer_data — Parameters applied to all signed customer data JSON files.
signed_customer_data_filename — Parameters applied to a specific signed customer data file.

Parameter key conventions#

Board configuration files use prefixed keys to indicate parameter types:

f_<key> — File path parameters; must point to an existing file (validated by the tool).
s_<key> — String parameters; should contain string values.
n_<key> — Boolean parameters; must be the strings "True" or "False".
board_specific_includes — Special key accepting a list of strings (no prefix).

For signed customer data files, keys do not follow the f_/s_/n_ convention.

Example override file#

A sample override configuration file is provided at foundation/tools/custom_board_cloner/inc/sample_override_complete.json (or drive-foundation/tools/custom_board_cloner/inc/sample_override_complete.json in SDK package). Example contents:

{
    "global": {
        "s_chipID": "0x300004",
        "s_GrCsvString": "P3981",
        "n_DramOverride": "False"
    },
    "p3981-10-sw03_thor_u": {
        "s_Skuname": "TA1090SA_NEW_SKU",
        "s_Int": "F8"
    },
    "p3981-10-sw03": {
        "s_Skuname": "TA1080SA_NEW_SKU",
        "s_Int": "F9",
        "s_ChainC_Kernel_Dtb_Variant": "p3981-0010-sw01"
    },
    "p3981-10-sw03_signed_customer_data": {
        "boardName": "p3981-10-sw03",
        "prodInfo": "940-63981-0010-new-prod-info"
    },
    "p3981-10-sw03_thor_u_signed_customer_data": {
        "boardName": "p3981-10-sw03",
        "prodInfo": "940-63981-0010-new-prod-info"
    }
}

Explanation of the example:

global — Applies chip ID, GR CSV string, and DRAM override flag to all board config files.
p3981-10-sw03_thor_u — Thor U variant-specific parameters (e.g., SKU name, interrupt).
p3981-10-sw03 — Board-specific overrides including SKU name, interrupt config, and ChainC kernel DTB variant for the base board.
p3981-10-sw03_signed_customer_data — Signed customer data for the base board configuration.
p3981-10-sw03_thor_u_signed_customer_data — Signed customer data for the Thor U variant.

Notes#

All keys specified in the override file must already exist in the target configuration file.
File paths specified with the f_ prefix are validated for existence by the tool.

Safety Build (`--safety` / `-sr`)#

Use --safety when you are working in a QNX NSR SR SDK package and need to clone a board within the safety foundation (drive-foundation-safety). In that case the tool uses drive-foundation-safety instead of drive-foundation, so the new board is created in the safety tree.

Without --safety, the tool always uses the standard foundation (drive-foundation). The cloned platform gets the same set of platform files as the reference in that tree. This option is only supported in QNX NSR SR SDK packages and is not applicable in the Automotive Source Repository or standard SDK packages. The drive-foundation-safety directory must be present. The safety flag can be combined with other options such as --override_board_config and --force.

Quick Start Example#

To clone an existing platform configuration:

For SDK Package:

cd ${NV_WORKSPACE}/drive-foundation/tools/custom_board_cloner

python3 ./custom_board_cloner.py \
    --original p3960-10-sw03 \
    --new p3981-10-sw03 \
    -p ${NV_WORKSPACE}

For Automotive Source Repository:

cd ${NV_WORKSPACE}/foundation/tools/custom_board_cloner

python3 ./custom_board_cloner.py \
    --original p3960-10-sw03 \
    --new p3981-10-sw03 \
    -p ${NV_WORKSPACE}

Expected output:

Backup directory created: /tmp/tmpABC123/
Successfully added p3981-10-sw03 to board-to-SoC mappings
Cloned PCT configuration for p3981-10-sw03
Copying configuration files...
Renaming directories and files...
Updating makefiles...
Copying DTB files...
Successfully cloned p3981-10-sw03 from p3960-10-sw03

Note

Follow NVIDIA platform naming conventions (e.g., pXXXX-XX-swXX) when choosing the new platform name.

Building After Cloning#

Once the platform cloning is complete, proceed with building and flashing the new platform configuration as usual.

Note

Since there is no customization yet, build/bind using the new platform name but flash it on the reference platform that was used for cloning. Once customization is performed, the new platform can be flashed.

Step 1: Bind Partitions

Use the bind_partitions command to bind the partitions for the new platform. The command syntax is:

cd ${NV_WORKSPACE}/drive-foundation/
./make/bind_partitions -b <new-board-name> <domain>.<os> -p <profile>

Where:

<new-board-name> is the newly cloned platform name
<domain>.<os> specifies the domain and OS (e.g., drive_av.linux for automotive domain with Linux)
<profile> specifies the PCT profile (e.g., dev_nsr)

Example:

cd /drive/drive-foundation/
./make/bind_partitions -b p3981-10-sw03 drive_av.linux -p dev_nsr

Step 2: Flash the Platform

After binding partitions, use bootburn to flash the new platform configuration:

cd ${NV_WORKSPACE}/drive-foundation/tools/flashtools/bootburn/
./bootburn.py -b <new-board-name> -D -board_config ${NV_WORKSPACE}/drive-foundation/platform-config/hardware/nvidia/platform/t264/automotive/automotive-platform-configs/<Platform name>/<Platform name-Platform SKU>/<new-board-name>/board_configs/<new-board-name><thor-variant>.json

Where:

<Platform name> is extracted from the platform name (e.g., p3981 from p3981-10-sw03)
<Platform name-Platform SKU> is the first two components (e.g., p3981-10 from p3981-10-sw03)
<thor-variant> is the Thor variant suffix (e.g., _thor_u)

Example:

cd /drive/drive-foundation/tools/flashtools/bootburn/
./bootburn.py -b p3981-10-sw03 -D -board_config /drive/drive-foundation/platform-config/hardware/nvidia/platform/t264/automotive/automotive-platform-configs/p3981/p3981-10/p3981-10-sw03/board_configs/p3981-10-sw03_thor_u.json

Note

Before flashing, ensure the target board is in recovery mode. Refer to the board’s documentation for instructions on entering recovery mode.

For detailed build and flashing procedures, refer to:

Bind Partitions - Detailed bind_partitions usage and options
Flash Steps for NVIDIA Thor System on Chip (SoC) - Bootburn flashing procedures and options

What the Tool Does#

The Custom Board Cloner automates the creation of custom platforms by performing the following operations:

1. Environment Detection

Automatically detects the environment (SDK package or Automotive Source Repository) and SDK version to apply appropriate configurations. The tool checks for the NV_WORKSPACE environment variable to determine if it’s running in an SDK package container or Automotive Source Repository. It then reads version-nv-sdk.txt to detect the SDK version (e.g., 7.2.2.0), which determines which configuration files and paths will be used during cloning.

2. Platform Configuration Setup

Copies platform-specific configuration files and directories from the reference platform to create the new platform configuration. The tool searches through multiple directory paths to find platform-specific files. For example, when cloning from p3960-10-sw03, the tool searches for any directory or file that has p3960 in its name and creates corresponding copies with the new platform name (e.g., p3981).

The tool walks through the following directory trees:

For SDK Package:

drive-foundation/platform-config/hardware/nvidia/platform/t264/
drive-foundation/platform-config/dce_dtsi/t264/
drive-foundation/firmware/bin/t264/

For Source Repository:

hardware/nvidia/platform/t264/
display/dce-config-public/t264/
ist/public/t26x/

In each of these paths, the tool identifies all files and subdirectories containing the old platform name (e.g., p3960) in their paths or filenames, and creates copies with the new platform name.

After copying the files, the tool performs text replacement within the newly copied configuration files, updating:

Board names: p3960-10-sw03 → p3981-10-sw03
Zero-padded variants: p3960-0010-sw03 → p3981-0020-sw04
Platform references: p3960 → p3981

3. Build System Integration

Updates makefiles and build scripts to integrate the new platform into the build system, including platform family entries and platform-specific configurations. The tool modifies several key build files:

Configuration Files:

PCT Configuration: Updates pct_configuration_v2.yaml to add the new platform.
Build Scripts: Modifies make/bind_partitions (SDK) or mk_blob.sh (source repository) to add the new platform to the t264_boards array

Makefiles:

make/Makefile.bind or boot_blob.mk
platform-config/hardware/nvidia/t264/nv-automotive/automotive/Makefile
platform-config/dce_dtsi/t264/Makefile and platforms_t264.mk - Updates DCE configuration makefiles
Version-specific makefiles (SDK 7.2.2+): automotive-platform-configs/driveos_customer_config/nv_platforms/platforms_t264.mk

4. Platform-Specific Code Duplication

Copies platform-specific conditional code blocks from the original platform and creates new ones for the new platform. The tool searches through .h, .dts, .dtsi, and Makefile files to find conditional blocks that are specific to the original platform. When it finds such blocks, it duplicates them and updates them for the new platform.

For example, if a header file contains:

#if defined(PLATFORM_P3960)
    /* p3960 specific configuration */
#endif

The tool adds:

#if defined(PLATFORM_P3960)
    /* p3960 specific configuration */
#endif
#if defined(PLATFORM_P3981)
    /* p3981 specific configuration */
#endif

Similarly, in makefiles with conditional logic:

ifeq ($(BOARD_FLAVOR), p3960)
    # p3960 build configuration
endif

becomes:

ifeq ($(BOARD_FLAVOR), p3960)
    # p3960 build configuration
endif
ifeq ($(BOARD_FLAVOR), p3981)
    # p3981 build configuration
endif

This ensures that all platform-specific code logic is automatically replicated for the new platform.

5. Device Tree Blob Handling

Copies and renames precompiled device tree binary files for the new platform. The tool searches DTB directories (such as drive-foundation/tools/flashtools/flashing_kernel/kernel/t264/ for SDK packages) and finds all DTB files containing the old platform family name. For example, kernel_tegra264-p3960-0000-a00-p3768-0000-a00.dtb would be copied and renamed to kernel_tegra264-p3981-0000-a00-p3768-0000-a00.dtb. All DTB files with the old platform name are cloned with the new platform name.

6. Safety and Error Handling

Creates automatic backups before modifications and performs automatic rollback if any error occurs. Before making any modifications, the tool creates a temporary backup directory (e.g., /tmp/tmpABC123/) and copies all files there before modification. If an error occurs during cloning (such as a file conflict or invalid platform name), the tool automatically restores all backed-up files to their original state, ensuring the workspace remains unchanged. When using --debug mode, the backup directory is preserved for inspection after completion.

7. Board Config Overrides (Optional)

If --override_board_config was specified, the tool applies the override JSON to the cloned board’s configuration files after all cloning steps. See Board Configuration Override under Optional Arguments for the override file format and key conventions.

Examples#

Example 1: Basic Platform Clone (SDK)#

Clone p3960-10-sw03 to create p3981-10-sw03 in SDK environment:

python3 ./custom_board_cloner.py \
    --original p3960-10-sw03 \
    --new p3981-10-sw03 \
    --path ${NV_WORKSPACE}

Example 2: Clone with Force Overwrite#

Re-clone and overwrite existing configuration:

python3 ./custom_board_cloner.py \
    -o p3960-10-sw03 \
    -n p3981-10-sw03 \
    -p ${NV_WORKSPACE} \
    -f

Warning

Using the -f flag will overwrite existing files. Use with caution.

Example 3: Clone with Debug Mode#

Clone and preserve backup for inspection:

python3 ./custom_board_cloner.py \
    -o p3960-10-sw03 \
    -n p3981-10-sw03 \
    -p ${NV_WORKSPACE} \
    -d

Result: Backup directory in /tmp/ is preserved after completion.

Example 4: SDK Package Environment#

Running in SDK container:

cd ${NV_WORKSPACE}/drive-foundation/tools/custom_board_cloner
python3 ./custom_board_cloner.py \
    -o p3960-10-sw03 \
    -n p3981-10-sw03 \
    -p ${NV_WORKSPACE}

Example 5: Automotive Source Repository Environment#

Running in Automotive Source Repository:

cd ${NV_WORKSPACE}/foundation/tools/custom_board_cloner
python3 ./custom_board_cloner.py \
    -o p3960-10-sw03 \
    -n p3981-10-sw03 \
    -p ${NV_WORKSPACE}

Example 6: Clone with Board Config Overrides#

Apply a JSON override file to customize the cloned board’s parameters after cloning:

python3 ./custom_board_cloner.py \
    -o p3960-10-sw03 \
    -n p3981-10-sw03 \
    -p ${NV_WORKSPACE} \
    --override_board_config /path/to/override_config.json

Example 7: Safety Build (QNX NSR SR SDK package only)#

Clone a board within the safety foundation in a QNX NSR SR SDK package:

python3 ./custom_board_cloner.py \
    -o p3960-10-sw03 \
    -n p3981-10-sw03 \
    -p ${NV_WORKSPACE} \
    -sr

Note

The --safety option requires a PDK with drive-foundation-safety and is not supported in the Automotive Source Repository or standard SDK packages.

Additional Resources#

For more information about platform customization, refer to:

Customizing DriveOS for a Different Board - Pin muxing and hardware configuration
Device Tree - Device tree configuration details
Configuring DriveOS PCT - PCT configuration details
Build - Build system and compilation instructions

Note

The Custom Board Cloner tool only creates the initial platform configuration and sets up the build system. Additional customization of hardware-specific settings, device trees, and driver configurations is still required for specific platform requirements.

Custom Board Cloner Tool - Adding Support for a New Hardware Platform in DriveOS#

Overview#

Key Features#

Tool Location#

Usage#

Basic Syntax#

Command Line Arguments#

Required Arguments#

Optional Arguments#

Board Configuration Override (--override_board_config)#

Override file format#

Override sections#

Parameter key conventions#

Example override file#

Notes#

Safety Build (--safety / -sr)#

Quick Start Example#

Building After Cloning#

What the Tool Does#

Examples#

Example 1: Basic Platform Clone (SDK)#

Example 2: Clone with Force Overwrite#

Example 3: Clone with Debug Mode#

Example 4: SDK Package Environment#

Example 5: Automotive Source Repository Environment#

Example 6: Clone with Board Config Overrides#

Example 7: Safety Build (QNX NSR SR SDK package only)#

Additional Resources#

Board Configuration Override (`--override_board_config`)#

Safety Build (`--safety` / `-sr`)#