diff --git a/docs/docs/developing/asic_config_v3/broadcom_dnx.md b/docs/docs/developing/asic_config_v3/broadcom_dnx.md new file mode 100644 index 0000000000000..b36b94877711c --- /dev/null +++ b/docs/docs/developing/asic_config_v3/broadcom_dnx.md @@ -0,0 +1,90 @@ +--- +sidebar_position: 3 +--- + +# Broadcom DNX + +The DNX generator builds a single flat map of SOC properties, each with a +string key and a string value. All settings are +written to the `common` section of the output, which is described in +[Output structure](#output-structure). + +The shared design is described in the [Overview](./overview.md). + +## Generation pipeline + +| Order | Setting | Source | +|---|---|---| +| 1 | Base SDK settings | `asic_vendors/broadcom/dnx/asics/.json` (`base_sdk_settings`) | +| 2 | [Declarative tables](#declarative-tables) for port speeds, TM port headers, DTM flow regions, and flow remote cores | `asic_vendors/broadcom/dnx/asics/.json` (`declarative_tables`) | +| 3 | Platform SDK overrides | `platforms///asic_config/asic_config.json` (`platform_sdk_overrides`) | +| 4 | Lane and polarity keys | computed from `platform_mapping_v2` connections and the ASIC `core_types`, `key_formats`, and `num_lanes_per_core`, plus the ASIC `default_polarity_settings` | +| 5 | [Conditional settings](./overview.md#conditional-settings), ASIC entries then platform entries, each in array order | `asic_vendors/broadcom/dnx/asics/.json` (`conditional_settings`), then `platforms///asic_config/asic_config.json` (`conditional_settings`) | + +The lane and polarity keys in step 4 reproduce the wiring that +`asic_config_v2` computed in per-platform Python code. The generator iterates +the platform's `platform_mapping_v2` connections and keeps the connection +ends whose core type the ASIC declares in `core_types`. For each remaining +connection it computes the SOC lane number as +`core_id * num_lanes_per_core + core_lane` and renders each key through the +ASIC's `key_formats` strings. Core types that are not declared, for example +the Jericho 3 recycle and eventor ports, are skipped automatically. + +## Output structure + +The DNX output file is the JSON representation of the thrift `AsicConfig` +struct, which is defined in `fboss/agent/hw/config/asic_config_v2.thrift`. +The struct consists of a `common` entry holding a key/value `config` map, +together with an optional `npuEntries` map for platforms with more than one +NPU. The platform file declares which structure to produce through the +top-level `output_structure` field: + +```json +"output_structure": {"mode": "common_only"} +``` + +- The `common_only` mode is for single-NPU platforms such as meru800bia. + Every generated key is written to `common.config`. This is the only + supported mode. +- Support for multi-NPU platforms, which distribute the per-chip wiring + keys for lanes and polarity into per-NPU sections while the + chip-independent settings remain in `common.config`, is planned as a + further mode. + +The number of NPUs is a property of the board rather than of the ASIC, which +is why `output_structure` is declared in the platform file and not in the +per-ASIC file. + +## ASIC data + +The per-ASIC file, for example +`fboss/configs/asic_vendors/broadcom/dnx/asics/jericho3.json`, +declares the data intrinsic to the chip. It contains the following groups of +fields. + +- **Key formats and suffixes.** The `asic_suffix` value, for example + `BCM8889X`, is appended to generated SOC keys. The `key_formats` object + holds the format strings for the lane map and polarity keys, with + `{family}`, `{lane}`, and `{suffix}` placeholders. The `core_types` object + maps each `platform_mapping_v2` core type the chip exposes, for example + `J3_NIF` and `J3_FE`, to the key families used when rendering its wiring + keys. +- **Base SDK settings.** The `base_sdk_settings` map holds the SDK settings + emitted for every platform and variant of this chip. Keys carry their SOC + suffix inline. +- **Default polarity settings.** The `default_polarity_settings` map holds + the default polarity keys that carry no lane number. Jericho 3 emits + them. An ASIC without such keys omits the field. +- **Declarative tables.** These are described in the next section. + +### Declarative tables + +Declarative tables capture the fixed tables that `asic_config_v2` generated +in per-ASIC Python code: + +| Table | Emits | Notes | +|---|---|---| +| `port_speed_map` | `port_init_speed_*` keys | Interface-type-to-speed entries, emitted verbatim. | +| `tm_port_headers` | `tm_port_header_type_{in,out}_*` keys | Emitted verbatim for every variant. Topology-specific header sets are selected through conditional settings. | +| `dtm_flow_region_map` | `dtm_flow_mapping_mode_region_` keys | Expanded from `key_format`, `start_region`, `count`, and `value`. | +| `flow_remote_cores` | `dtm_flow_nof_remote_cores_region*` keys | Emitted verbatim. | diff --git a/docs/docs/developing/asic_config_v3/broadcom_xgs.md b/docs/docs/developing/asic_config_v3/broadcom_xgs.md new file mode 100644 index 0000000000000..b0fd5c3411819 --- /dev/null +++ b/docs/docs/developing/asic_config_v3/broadcom_xgs.md @@ -0,0 +1,52 @@ +--- +sidebar_position: 2 +--- + +# Broadcom XGS + +This page describes the Broadcom XGS specifics of `asic_config_v3`: the +generation pipeline and the pass-through settings mechanism. The shared +design is described in the [Overview](./overview.md). + +## Generation pipeline + +The XGS generator builds named YAML tables. Steps 1 through 6 all feed the +`global` table and form a single priority chain. The remaining steps mostly +write to their own tables. + +| Order | Setting | Source, in priority order | Output table | +|---|---|---|---| +| 1 | OCP SAI common | `asic_vendors/common/ocp_sai_common.json` (`global`) | `global` | +| 2 | ASIC global defaults | `asic_vendors/broadcom/xgs/asics/.json` (`global_defaults`) | `global` | +| 3 | Vendor SDK common | `asic_vendors/broadcom/xgs/sdk_common.json` (`global`) | `global` | +| 4 | Vendor SAI common, minus keys listed in an active `skip_from_sai_common` | `asic_vendors/broadcom/xgs/sai_common.json` (`global`) | `global` | +| 5 | ASIC SAI overrides | `asic_vendors/broadcom/xgs/asics/.json` (`sai_overrides`) | `global` | +| 6 | Platform SAI overrides | `platforms///asic_config/asic_config.json` (`platform_sai_overrides`) | `global` | +| 7 | [Pass-through settings](#pass-through-settings) | `asic_vendors/broadcom/xgs/asics/.json`, or `platforms///asic_config/asic_config.json` when the variant redefines a block | `PORT_CONFIG`, `FP_CONFIG`, `TM_THD_CONFIG`, `CTR_EFLEX_CONFIG`, `global` | +| 8 | [Conditional settings](./overview.md#conditional-settings), ASIC entries then platform entries, each in array order | `asic_vendors/broadcom/xgs/asics/.json` (`conditional_settings`), then `platforms///asic_config/asic_config.json` (`conditional_settings`) | tables named by each entry, for example `global`, `TM_THD_CONFIG`, `DEVICE_CONFIG` | +| 9 | Device configuration overrides | `platforms///asic_config/asic_config.json` (`device_config_overrides`) | `DEVICE_CONFIG` | +| 10 | Port mapping, port configuration, lane map, and polarity map | computed from `platform_mapping_v2`, the ASIC `port_architecture` and `mgmt_port_defaults`, and the platform `port_config`, `cpu_port`, `mgmt_port`, `mgmt_port_overrides`, and `port_mapping_overrides` | `PC_PM_CORE`, `PC_PORT_PHYS_MAP`, `PC_PORT`, `PORT` | + +## Pass-through settings + +Pass-through settings route a named data block from the ASIC file into an +output table declaratively, without any dedicated code: + +```json +"pass_through_settings": [ + {"source": "flex_counter_settings", "target_table": "global"}, + {"source": "ctr_eflex_config", "target_table": "CTR_EFLEX_CONFIG"} +] +``` + +A platform variant may declare a block under the same source key to replace +the ASIC-level block entirely, which lets a platform emit different values +than the chip-wide defaults. + +:::note + +The DNX family does not use pass-through settings. Its output has no named +tables, and unconditional data blocks are expressed directly as +`base_sdk_settings`, `declarative_tables`, or `platform_sdk_overrides`. + +::: diff --git a/docs/docs/developing/asic_config_v3/examples.md b/docs/docs/developing/asic_config_v3/examples.md new file mode 100644 index 0000000000000..8bde90a10f3f9 --- /dev/null +++ b/docs/docs/developing/asic_config_v3/examples.md @@ -0,0 +1,223 @@ +--- +sidebar_position: 4 +--- + +# Examples + +The walkthroughs on this page build on one another. The general design is +described in the [Overview](./overview.md), and the family specifics on +the [Broadcom XGS](./broadcom_xgs.md) and [Broadcom DNX](./broadcom_dnx.md) +pages. + +## Adding an XGS platform + +No Python changes are required to add a platform on an ASIC family that the +tool already supports. Suppose a new Tomahawk5 board named `newboard` is being +added. + +1. Ensure that `fboss/configs/platforms//newboard/platform_mapping/` exists and + contains the platform's static mapping and vendor data (see the + [platform mapping documentation](../platform_mapping.md)). +2. Create + `fboss/configs/platforms//newboard/asic_config/asic_config.json`. + The following is a complete example declaring a single variant; an existing + platform on the same ASIC is a good starting template: + +```json +{ + "platform_name": "newboard", + "vendor": "broadcom", + "asic": "tomahawk5", + "num_ports_per_core": 2, + "defaults": { + "asic_config_params": { + "config_type": "YAML_CONFIG", + "config_gen_type": "DEFAULT", + "exact_match": false, + "mmu_lossless": false + }, + "port_config": { + "default_speed": 400000, + "speed_to_fec": { + "100000": "PC_FEC_RS544", + "200000": "PC_FEC_RS544_2XN", + "400000": "PC_FEC_RS544_2XN", + "800000": "PC_FEC_RS544_2XN" + } + }, + "cpu_port": { + "speed": 10000, + "num_lanes": 1 + }, + "mgmt_port": { + "enabled": true, + "speed_variants": { + "100000": { "num_lanes": 4, "fec": "PC_FEC_RS528" } + } + }, + "features": { + "generate_dlb_config": true, + "generate_autoload_board_settings": true + } + }, + "variants": { + "newvariant": {} + } +} +``` + +3. Validate and generate: + +```shell +python3 -m fboss.lib.asic_config_v3.test.validate_asic_configs_schemas \ + --fboss-root "$PWD/fboss" +./fboss/lib/asic_config_v3/run-helper.sh +``` + +The output appears beside the input as +`generated/newboard_newvariant.yml`. + +If the platform needs a setting that no listed field covers, see +[Overriding a setting outside these fields](./overview.md#overriding-a-setting-outside-these-fields). + +## Adding a DNX platform + +Adding a platform on the DNX family follows the same pattern as on XGS. The +fields under the `defaults` section and in the variants are ASIC family +specific. The meru800bia platform file at +`fboss/configs/platforms/arista/meru800bia/asic_config/asic_config.json` +is a complete reference. The following example shows the overall structure: + +```json +{ + "platform_name": "newdnxboard", + "vendor": "broadcom", + "asic": "jericho3", + "output_structure": {"mode": "common_only"}, + "defaults": { + "asic_config_params": { + "config_type": "KEY_VALUE_CONFIG", + "config_gen_type": "DEFAULT", + "port_config": "default", + "multistage_role": "NONE" + }, + "platform_sdk_overrides": { + "appl_param_local_system_port_voq_connector_start": "93184" + }, + "conditional_settings": [ + { + "name": "port_profile_default", + "condition": {"param": "port_config", "equals": "default"}, + "apply": {"common": {"ucode_port_8.BCM8889X": "CDGE4_0:core_0.2"}} + }, + { + "name": "prod_sdk_settings", + "condition": {"param": "config_gen_type", "equals": "DEFAULT"}, + "apply": {"common": {"dpp_db_path": "/etc/packages/neteng-fboss-wedge_agent/current/db"}} + } + ] + }, + "variants": { + "default": {} + } +} +``` + +The following steps complete the platform. + +1. Ensure that `fboss/configs/platforms///platform_mapping/` + contains the platform's complete `platform_mapping_v2` data set: static + mapping, port profile mapping, profile settings, and SI settings. The + platform mapping parser loads them together, and the generator derives + every lane and polarity key from the static mapping. +2. Declare the SOC properties that are specific to this board and apply to + every variant in `platform_sdk_overrides`. +3. Declare the port-map profile entries, such as the `ucode_port_*` keys, in + a conditional setting keyed on `port_config`. Declare per-scenario + settings keyed on `config_gen_type`, and multistage-role settings keyed + on `multistage_role`, as applicable. +4. Validate, generate, and compare the output against the platform's + reference in `fboss/lib/asic_config_v2/synced_asic_configs/`. The output + appears beside the input as `generated/_.json`. + +## Adding a variant + +A variant is added by inserting one entry under `variants`; everything not +declared in it is inherited from `defaults`. The mechanism is the same for +both families. Continuing the XGS example from +[Adding an XGS platform](#adding-an-xgs-platform), +the following adds a `newvariant2` variant that enables MMU lossless mode +while the `newvariant` variant keeps the defaults: + +```json +"variants": { + "newvariant": {}, + "newvariant2": { + "asic_config_params": { + "mmu_lossless": true + } + } +} +``` + +The next generator run produces two output files, `newboard_newvariant.yml` +and `newboard_newvariant2.yml`. In the `newvariant2` output, `mmu_lossless` +satisfies the Tomahawk5 conditional setting of the same name, so the lossless MMU settings are +applied and the corresponding SAI common keys are suppressed; all other +settings are identical to `newvariant` because the merge with `defaults` fills +in every field the variant does not declare. + +Another common pattern is a variant per hardware configuration, where each +variant reads its platform mapping data from a different `platform_mapping` +directory: + +```json +"variants": { + "rack": { + "platform_mapping_name": "newboard_rack" + }, + "test_fixture": { + "platform_mapping_name": "newboard_test_fixture" + } +} +``` + +## Adding a new ASIC family + +Supporting a new ASIC family, such as a different vendor or a different +product line of an existing vendor, requires one new generator plus its data +files. The Broadcom DNX family was added following these steps, and its +files can be used as a reference. + +1. **Generator.** Add a generator module under `generators/` that subclasses + `BaseAsicConfigGenerator`. The subclass declares `SUPPORTED_EFFECTS` and + implements `generate()`, `output_extension`, and the conditional-setting + hooks `_apply_settings`, `_validate_apply_target`, and + `_validate_apply_value`. Reuse the shared patterns where possible. The + variant and defaults merge, the `asic_config_params` handling, and + condition evaluation come from the base class, platform mapping data comes + from the platform mapping parser, and feature toggles use conditional + settings. + Keep the behavior data-driven and avoid per-platform branches. +2. **Vendor data.** Add + `fboss/configs/asic_vendors///asics/.json` with + the chip-intrinsic data the generator needs. Add family-wide common files + only if several ASICs in the family share those settings. The DNX family + has no family-wide common files. +3. **Registration.** Add the new vendor and ASIC pair to + `_GENERATOR_REGISTRY` in `gen.py`. +4. **Schema.** Add a schema for the new ASIC file under `schemas/` and + register it in `test/validate_asic_configs_schemas.py`. Extend + `platform_config.schema.json` if the family introduces new platform-level + fields. The DNX family added `output_structure`, + `platform_sdk_overrides`, and new `asic_config_params` parameters. +5. **Build.** Add the new generator source to + `cmake/AsicConfigV3ConfigCli.cmake`, and add a `python_library` target + for it in `fboss/lib/asic_config_v3/BUCK`, wired into the `gen` binary's + dependencies. +6. **Platform.** Add + `fboss/configs/platforms///asic_config/asic_config.json` + selecting the new vendor and ASIC. +7. **Verification.** Compare the generated output against a known-good + reference configuration for that family. For ASIC families with synced + references, the match must be exact. diff --git a/docs/docs/developing/asic_config_v3/overview.md b/docs/docs/developing/asic_config_v3/overview.md index 5af353efac7c4..63365d4227381 100644 --- a/docs/docs/developing/asic_config_v3/overview.md +++ b/docs/docs/developing/asic_config_v3/overview.md @@ -6,14 +6,29 @@ sidebar_position: 1 The `asic_config_v3` tool, located at `fboss/lib/asic_config_v3/`, reads inputs from `fboss/configs/` and generates the per-platform ASIC configuration that a -switch ASIC needs at SDK and SAI initialization time (for example, the -Broadcom YAML configuration). It is the data-driven successor to the -code-driven `asic_config_v2` implementation. -Whereas `asic_config_v2` required a dedicated Python module for every -platform, `asic_config_v3` describes each platform in JSON data files that are -processed by a generic generator shared by all platforms of an ASIC family. As -a result, adding support for a new platform on an existing ASIC family -requires no code changes. +switch ASIC needs at SDK and SAI initialization time. It is the data-driven +successor to the code-driven `asic_config_v2` implementation. Whereas +`asic_config_v2` required a dedicated Python module for every platform, +`asic_config_v3` describes each platform in JSON data files that are processed +by a generic generator shared by all platforms of an ASIC family. As a result, +adding support for a new platform on an existing ASIC family requires no code +changes. + +Two ASIC families are currently supported, each with its own generator and +output format: + +| Family | Generator | Output format | Output file | +|---|---|---|---| +| [Broadcom XGS](./broadcom_xgs.md) | `BroadcomXgsGenerator` | Multi-document YAML with typed tables such as `PC_PM_CORE`, `PC_PORT`, and `global` | `_.yml` | +| [Broadcom DNX](./broadcom_dnx.md) | `BroadcomDnxGenerator` | Flat SOC property key/value pairs in the JSON representation of the thrift `AsicConfig` struct | `_.json` | + +The two ASIC families share the same framework. Platform discovery, variants, +schema validation, wiring data from `platform_mapping_v2`, and conditional +settings all work the same way in both. The ASIC families differ in how +settings are layered and in the structure of the output. The +[Broadcom XGS](./broadcom_xgs.md) and [Broadcom DNX](./broadcom_dnx.md) +pages describe these differences, and the [Examples](./examples.md) page +walks through adding platforms and variants. ## Design @@ -22,54 +37,60 @@ requires no code changes. The configuration input is split into layers according to who owns the data. Each layer is a JSON file: -| Layer | File | Contents | -|---|---|---| -| OCP SAI common | `fboss/configs/asic_vendors/common/ocp_sai_common.json` | Vendor-agnostic SAI defaults shared by all vendors | -| Vendor family common | `fboss/configs/asic_vendors///sdk_common.json` and `sai_common.json` | SDK and SAI settings shared by all ASICs in a family (for example, Broadcom XGS) | -| Per-ASIC | `fboss/configs/asic_vendors///asics/.json` | Data intrinsic to the chip, such as the port architecture, output table names, global defaults, SAI overrides, pass-through data blocks, and ASIC-wide conditional settings | -| Platform | `fboss/configs/platforms///asic_config/asic_config.json` | Board-specific data, such as the ASIC selection, port defaults, configuration variants, and platform-level SAI overrides | - -Port wiring information (the lane map, polarity map, and logical-to-physical -port mapping) is not duplicated in these files. The generator computes it from -the platform data already maintained under `fboss/lib/platform_mapping_v2`. +| Layer | Families | File | Contents | +|---|---|---|---| +| OCP SAI common | XGS | `fboss/configs/asic_vendors/common/ocp_sai_common.json` | Vendor-agnostic SAI defaults shared by all vendors | +| Vendor family common | XGS | `fboss/configs/asic_vendors///sdk_common.json` and `sai_common.json` | SDK and SAI settings shared by all ASICs in a family | +| Per-ASIC | XGS and DNX | `fboss/configs/asic_vendors///asics/.json` | Data intrinsic to the chip | +| Platform | XGS and DNX | `fboss/configs/platforms///asic_config/asic_config.json` | Board-specific data, such as the ASIC selection, configuration variants, and platform-level overrides | + +The DNX family has no family-wide common files; everything above the platform +layer lives in its per-ASIC file. + +Port wiring information is not duplicated in the files listed above. The +generator derives the lane and polarity maps for both families, as well as the +XGS-only logical-to-physical port mapping, from the platform mapping data +maintained under +`fboss/configs/platforms///platform_mapping/`. + +What the per-ASIC file contains differs by family. For XGS it declares the +port architecture, output table names, global defaults, SAI overrides, +pass-through data blocks, and ASIC-wide conditional settings. For DNX it +declares the SOC key suffix and key format strings, the core types to include +in wiring generation, always-emitted base SDK settings, and declarative +tables. Both schemas are documented in the +[Schema Field Reference](./schema_field_reference.md). ### Generation pipeline The entry point, `gen.py`, discovers every -`platforms/*/*/asic_config/asic_config.json` file under `fboss/configs/`, -looks up the appropriate generator in a registry keyed on the ASIC vendor and -ASIC names, and runs that generator once per -[variant](#platform-configuration-and-variants). For the Broadcom XGS family, -the generator applies the settings below in order. When two steps write the -same key of the same output table, the later step wins, so the list is also -the precedence order (lowest first). Steps 1 through 6 all build the `global` -table and therefore form a single priority chain; the remaining steps mostly -write to their own tables. - -| Order | Setting | Source, in priority order | Output table | -|---|---|---|---| -| 1 | OCP SAI common | `asic_vendors/common/ocp_sai_common.json` (`global`) | `global` | -| 2 | ASIC global defaults | `asic_vendors/broadcom/xgs/asics/.json` (`global_defaults`) | `global` | -| 3 | Vendor SDK common | `asic_vendors/broadcom/xgs/sdk_common.json` (`global`) | `global` | -| 4 | Vendor SAI common, minus keys listed in an active `skip_from_sai_common` | `asic_vendors/broadcom/xgs/sai_common.json` (`global`) | `global` | -| 5 | ASIC SAI overrides | `asic_vendors/broadcom/xgs/asics/.json` (`sai_overrides`) | `global` | -| 6 | Platform SAI overrides | `platforms///asic_config/asic_config.json` (`platform_sai_overrides`) | `global` | -| 7 | [Pass-through settings](#pass-through-settings) | `asic_vendors/broadcom/xgs/asics/.json`, or a platform's `asic_config.json` when the variant redefines a block | `PORT_CONFIG`, `FP_CONFIG`, `TM_THD_CONFIG`, `CTR_EFLEX_CONFIG`, `global` | -| 8 | [Conditional settings](#conditional-settings), ASIC entries then platform entries, each in array order | `asic_vendors/broadcom/xgs/asics/.json` (`conditional_settings`), then a platform's `asic_config.json` (`conditional_settings`) | tables named by each entry, for example `global`, `TM_THD_CONFIG`, `DEVICE_CONFIG` | -| 9 | Device configuration overrides | A platform's `asic_config.json` (`device_config_overrides`) | `DEVICE_CONFIG` | -| 10 | Port mapping, port configuration, lane map, and polarity map | computed from `platform_mapping_v2`, the ASIC `port_architecture` and `mgmt_port_defaults`, and the platform `port_config`, `cpu_port`, `mgmt_port`, `mgmt_port_overrides`, and `port_mapping_overrides` | `PC_PM_CORE`, `PC_PORT_PHYS_MAP`, `PC_PORT`, `PORT` | - -The ordering is the same for every platform and variant. Within steps 7 and -8, the entries of each list apply in array order. +`platforms/*/*/asic_config/asic_config.json` +file under `fboss/configs/`, looks up the appropriate generator in a registry +keyed on the ASIC vendor and ASIC names, and runs that generator once per +[variant](#platform-configuration-and-variants): + +```python +_GENERATOR_REGISTRY = { + ("broadcom", "tomahawk5"): BroadcomXgsGenerator, + ("broadcom", "tomahawk6"): BroadcomXgsGenerator, + ("broadcom", "jericho3"): BroadcomDnxGenerator, +} +``` + +Each family applies its input layers in a fixed order that is the same for +every platform and variant. When two steps write the same key, the later step +wins, so the step table on each family page is also in ascending +precedence order. ### Schema validation -The platform, per-ASIC, and vendor common configuration files are validated -against the JSON Schemas stored in the `schemas/` directory -(`platform_config.schema.json`, `broadcom_xgs_asic_config.schema.json`, and -`vendor_common.schema.json`). The schemas reject unknown keys in most places, -so a new configuration key must be added to the corresponding schema, with a -description, in the same change. Run the validator with: +The configuration files are validated against the JSON Schemas stored in the +`schemas/` directory (`platform_config.schema.json`, +`broadcom_xgs_asic_config.schema.json`, `broadcom_dnx_asic_config.schema.json`, +`conditional_setting.schema.json`, and `vendor_common.schema.json`). The +schemas reject unknown keys in most +places, so a new configuration key with a description must be added to the +corresponding schema in the same change. Run the validator with: ```shell python3 -m fboss.lib.asic_config_v3.test.validate_asic_configs_schemas \ @@ -91,39 +112,76 @@ Run the helper script from the root of the repository: ``` Output files are written beside each platform input under -`fboss/configs/platforms///asic_config/generated/`. -To generate a single platform, pass the `--platform ` argument. +`fboss/configs/platforms///asic_config/generated/`, +one per platform variant. +The file extension is determined by the family, `.yml` for XGS and `.json` +for DNX, matching the output formats in the family table at the top of this +[page](#overview). To generate a single platform, pass the `--platform ` +argument. + +### Verifying generated output + +Generated output is verified by comparing it against known-good reference +configurations. + +- The committed files under + `fboss/configs/platforms///asic_config/generated/` + are the permanent regression references. Regenerating with an unchanged + input configuration must reproduce them exactly. +- During the migration from `asic_config_v2`, a platform's output is + additionally compared against the v2 references. The output must match the + files under `fboss/lib/asic_config_v2/generated_asic_configs/` exactly, + and the synced references under + `fboss/lib/asic_config_v2/synced_asic_configs/` semantically. ## Configuration details -### Pass-through settings - -Pass-through settings route a named data block from the ASIC file into an -output table declaratively, without any dedicated code: - -```json -"pass_through_settings": [ - {"source": "flex_counter_settings", "target_table": "global"}, - {"source": "ctr_eflex_config", "target_table": "CTR_EFLEX_CONFIG"} -] -``` - -A platform variant may declare a block under the same source key to replace -the ASIC-level block entirely, which lets a platform emit different values -than the chip-wide defaults. - ### Conditional settings Conditional settings express feature toggles as data instead of code -branches. Each entry carries a name, a condition naming a parameter from the -variant's `asic_config_params` or `features` section together with the value -it must equal, and the settings to apply when the condition holds. Entries are -applied in array order, with later entries taking precedence, and ASIC-level -entries are evaluated before platform-level ones so that platform values win. -An ASIC-level entry may also list keys to suppress from the vendor SAI common -layer while its condition is active, which allows a feature to remove a -default setting rather than override it. The following entry from the -Tomahawk5 file illustrates the mechanism: +branches. The mechanism is shared by both ASIC families: the condition +grammar is defined once in `schemas/conditional_setting.schema.json` and +evaluated by the base generator class. Each family's generator declares the +effects it can execute. Each entry carries a name, a condition, and one or +more effects. Unconditional data does not belong here; it has dedicated +mechanisms instead (pass-through settings on XGS; `base_sdk_settings` and +`platform_sdk_overrides` on DNX). + +A condition names a parameter from the variant's `asic_config_params` or +`features` section and exactly one operator: `equals`, `not_equals`, `in`, +`not_in`, `starts_with`, or `not_starts_with`. A parameter the variant does +not declare evaluates as null, and each negative operator is the strict +complement of its positive counterpart, so an absent parameter satisfies +every negative operator. + +An effect names what the entry does when its condition holds. The `apply` +effect writes settings to a named output target, which is an output table +for XGS and an output section for DNX. The `apply_from` effect copies a +named settings block from the ASIC file into an output target. The +`skip_from_sai_common` effect omits keys from the vendor SAI common layer +and is meaningful only for XGS, which is the only family that layers that +block. Validation is split between the schema and the generator. The schema +validator checks the structure of every entry, including operator and +operand types. Each generator additionally declares the effects it supports +(all three for XGS, and `apply` and `apply_from` for DNX) and, when it is +constructed, +rejects an entry that declares any other effect, has a malformed effect +payload, targets an unknown output table or section, or applies a value of +the wrong type for its output format. The generator check covers every +entry, not only those whose condition currently holds, so an invalid entry +cannot remain latent until another variant activates it. Operand types are +checked only by the schema validator, so rerun it after editing conditions. + +Entries are evaluated once per variant. ASIC-level entries come before +platform-level entries, each in array order, so a platform value overrides +a chip-level one. Within an entry, `apply_from` executes before `apply`, so +an inline setting overrides the copied block. Each generator executes the +effects at the point in its pipeline where they belong: XGS collects +`skip_from_sai_common` before it layers the vendor SAI common block and +writes `apply` and `apply_from` settings in its conditional-settings step, +while DNX writes them in its final step. + +The following XGS entry from the Tomahawk5 file illustrates the mechanism: ```json { @@ -153,6 +211,68 @@ Tomahawk5 file illustrates the mechanism: } ``` +The `apply_from` effect serves the same purpose as `apply` but avoids +repeating a large settings block inside the entry: the entry names a +top-level block of the ASIC file and the output target to copy it into. The +following Tomahawk5 entry copies the chip's `dlb_defaults` block into the +`global` table when the variant enables the `generate_dlb_config` feature: + +```json +"dlb_defaults": { + "ecmp_dlb_port_speeds": 1, + "l3_ecmp_member_secondary_mem_size": 4096 +}, +"conditional_settings": [ + { + "name": "dlb_config", + "description": "Enables Dynamic Load Balancing settings for ECMP groups.", + "condition": { + "source": "features", + "param": "generate_dlb_config", + "equals": true + }, + "apply_from": { + "source": "dlb_defaults", + "target_table": "global" + } + } +] +``` + +Because `apply_from` executes before `apply` within an entry, an entry may +copy a block with `apply_from` and then override individual keys of that +block with an inline `apply`. + +The following DNX entry from the meru800bia platform file selects the +single-stage port map for every port configuration that is not a dual-stage +topology: + +```json +{ + "name": "single_stage_port_map", + "condition": { + "param": "port_config", + "not_starts_with": "dual_stage" + }, + "apply": { + "common": { + "fabric_connect_mode.BCM8889X": "FE", + "ucode_port_0.BCM8889X": "CPU.0:core_0.0" + } + } +} +``` + +On DNX, scenario selection is expressed entirely through conditional settings +on the `asic_config_params` values. The `config_gen_type` parameter selects +the generation profile, such as production or hardware test. The +`port_config` parameter selects the port-map profile by exact name and the +topology family by prefix. The `multistage_role` parameter selects the +multistage fabric role. Because scenario selection happens through these +conditional settings, the bucketed `vendor_config.json` files that +`asic_config_v2` consumed through `platform_mapping_v2` are unnecessary; +`asic_config_v3` does not read them. + ### Platform configuration and variants Each platform file declares the platform identity (`platform_name`, `vendor`, @@ -160,7 +280,7 @@ and `asic`), which selects both the per-ASIC data file and the generator to use. It then declares a `defaults` block together with one or more named `variants`. A variant represents one deliverable configuration for the platform, and the generator produces one output file per variant, named -`generated/_.yml`. +`generated/_.` beside the platform input. The effective configuration for a variant is formed by merging the variant's settings on top of the `defaults` block. The merge is recursive for nested @@ -184,9 +304,11 @@ platform, and adding a variant never requires a code change. A `defaults` block or a variant may declare any of the variant fields listed in the [Schema Field Reference](./schema_field_reference.md). Every field is optional, and a variant only needs to declare the fields that differ from the -platform defaults. A variant may also replace any data block that the ASIC -file routes through `pass_through_settings` by declaring a key of the same -name. +platform defaults. Most variant fields belong to a single family. For +example, the `port_config` object, `cpu_port`, and `platform_sai_overrides` +are XGS fields, while `platform_sdk_overrides` and the `port_config`, +`multistage_role`, and `hyper_port` parameters inside `asic_config_params` +belong to DNX. Because the generator does not act on the variant name, two variants produce different output only through these fields. The parameters that switch @@ -196,216 +318,41 @@ applies extra settings when it matches, as described in [Conditional settings](#conditional-settings). To give a variant new behavior, set the relevant parameter or feature flag and add the matching conditional setting; no new variant "type" or generator change is involved. -Note that of the `asic_config_params`, only `mmu_lossless` and `exact_match` -currently drive Broadcom XGS output; `config_gen_type` is accepted and -validated but is not yet consumed by any XGS conditional setting. +The `asic_config_params` that currently drive output through conditional +settings are `mmu_lossless`, `exact_match`, and `config_gen_type` on XGS, and +`config_gen_type`, `port_config`, and `multistage_role` on DNX. ### Overriding a setting outside these fields A setting that no variant field covers can usually still be overridden -without a code change: +without a code change. + +On XGS: - A key in the `global` output table can be set through `platform_sai_overrides`, which takes precedence over all the other layered - `global` sources (steps 1 through 6 of the pipeline table). + `global` sources (steps 1 through 6 of the [XGS pipeline](./broadcom_xgs.md) table). - A key in the `DEVICE_CONFIG` table can be set through `device_config_overrides`. - A table fed by a pass-through block can be replaced in its entirety by declaring the block at the variant level, as described in - [Pass-through settings](#pass-through-settings). + [Pass-through settings](./broadcom_xgs.md#pass-through-settings). - Any other output table the ASIC declares can be modified through a platform-level `conditional_settings` entry whose `apply` block names the - table. The condition must reference a parameter in `asic_config_params` or a - `features` flag; `asic_config_params` accepts platform-defined parameters, - so a platform can introduce its own parameter and condition on it. - -Two limitations apply. The generator emits only the tables named in the -ASIC's `table_names` list, so settings applied to any other table do not -appear in the output. In addition, a setting that requires computation or new -structure (for example, new port mapping logic) needs a generic, data-driven -extension of the generator and the schema rather than a platform-specific -branch in the code. - -## Example: adding a platform for an existing ASIC family - -No Python changes are required to add a platform on an ASIC family that the -tool already supports. Suppose a new Tomahawk5 board named `newboard` is being -added. - -1. Ensure that `fboss/configs/platforms//newboard/platform_mapping/` exists and - contains the platform's static mapping and vendor data (see the - [platform mapping documentation](../platform_mapping.md)). -2. Create - `fboss/configs/platforms//newboard/asic_config/asic_config.json`. - The following is a complete example declaring a single variant; an existing - platform on the same ASIC is a good starting template: - -```json -{ - "platform_name": "newboard", - "vendor": "broadcom", - "asic": "tomahawk5", - "num_ports_per_core": 2, - "defaults": { - "asic_config_params": { - "config_type": "YAML_CONFIG", - "exact_match": false, - "mmu_lossless": false, - "config_gen_type": "DEFAULT" - }, - "port_config": { - "default_speed": 400000, - "speed_to_fec": { - "100000": "PC_FEC_RS544", - "200000": "PC_FEC_RS544_2XN", - "400000": "PC_FEC_RS544_2XN", - "800000": "PC_FEC_RS544_2XN" - } - }, - "cpu_port": { - "speed": 10000, - "num_lanes": 1 - }, - "mgmt_port": { - "enabled": true, - "speed_variants": { - "100000": { "num_lanes": 4, "fec": "PC_FEC_RS528" } - } - }, - "features": { - "generate_dlb_config": true, - "generate_autoload_board_settings": true - } - }, - "variants": { - "newvariant": {} - } -} -``` - -3. Validate and generate: - -```shell -python3 -m fboss.lib.asic_config_v3.test.validate_asic_configs_schemas \ - --fboss-root "$PWD/fboss" -./fboss/lib/asic_config_v3/run-helper.sh -``` - -The output appears beside the input as -`generated/newboard_newvariant.yml`. - -If the platform needs a setting that no listed field covers, see -[Overriding a setting outside these fields](#overriding-a-setting-outside-these-fields). - -## Example: adding a variant - -A variant is added by inserting one entry under `variants`; everything not -declared in it is inherited from `defaults`. Continuing the example above, -the following adds a `newvariant2` variant that enables MMU lossless mode -while the `newvariant` variant keeps the defaults: - -```json -"variants": { - "newvariant": {}, - "newvariant2": { - "asic_config_params": { - "mmu_lossless": true - } - } -} -``` - -The next generator run produces two output files, `newboard_newvariant.yml` -and `newboard_newvariant2.yml`. In the `newvariant2` output, `mmu_lossless` -satisfies the Tomahawk5 conditional setting of the same name, so the lossless MMU settings are -applied and the corresponding SAI common keys are suppressed; all other -settings are identical to `newvariant` because the merge with `defaults` fills -in every field the variant does not declare. - -Another common pattern is a variant per hardware configuration, where each -variant reads its wiring data from a different `platform_mapping_v2` -directory: - -```json -"variants": { - "rack": { - "platform_mapping_name": "newboard_rack" - }, - "test_fixture": { - "platform_mapping_name": "newboard_test_fixture" - } -} -``` - -## Example: adding a new ASIC family and a platform for it - -Supporting a new ASIC family (for example, a different vendor or a different -Broadcom product line) requires one new generator plus its data files. -Suppose a hypothetical Broadcom DNX family with a `jericho3` ASIC is being -added. The new files are: - -``` -fboss/configs/ -├── asic_vendors/broadcom/dnx/ -│ ├── sdk_common.json # optional family-wide settings -│ └── asics/jericho3.json # chip-intrinsic data -└── platforms//newdnxboard/asic_config/asic_config.json - -fboss/lib/asic_config_v3/ -├── generators/broadcom_dnx_generator.py # the family generator -└── schemas/broadcom_dnx_asic_config.schema.json -``` - -1. **Vendor data.** - `fboss/configs/asic_vendors/broadcom/dnx/asics/jericho3.json` holds the - chip-intrinsic data the generator needs, such as the identity, port - architecture, output table names, base settings, and conditional settings. - Add family-wide common files only if several ASICs in the family will share - those settings. -2. **Generator.** The generator subclasses `BaseAsicConfigGenerator` and - implements two members: - -```python -from fboss.lib.asic_config_v3.base_generator import BaseAsicConfigGenerator - -class BroadcomDnxGenerator(BaseAsicConfigGenerator): - @property - def output_extension(self) -> str: - return ".yml" - - def generate(self) -> str: - # Load the vendor and ASIC JSON, layer the settings, compute - # port wiring from platform_mapping_v2, and return the complete - # output file as a string. - ... -``` - - Reuse the shared patterns where possible, such as layered settings, - pass-through settings, conditional settings, and the platform mapping - parser for wiring data. Keep the behavior data-driven and avoid - per-platform branches. - -3. **Registration.** Add the new vendor and ASIC pair to the registry in - `gen.py`: - -```python -_GENERATOR_REGISTRY = { - ("broadcom", "tomahawk5"): BroadcomXgsGenerator, - ("broadcom", "tomahawk6"): BroadcomXgsGenerator, - ("broadcom", "jericho3"): BroadcomDnxGenerator, # new entry -} -``` - -4. **Schema.** Add a schema for the new ASIC file under `schemas/` and - register it in `test/validate_asic_configs_schemas.py`. Extend - `platform_config.schema.json` if the family introduces new platform-level - fields. -5. **Build.** Add the new generator source files, and any new modules they - import, to `cmake/AsicConfigV3ConfigCli.cmake` so that the build target - includes them. -6. **Platform.** Add - `fboss/configs/platforms//newdnxboard/asic_config/asic_config.json` - exactly as in the first example, with `"vendor": "broadcom"` and - `"asic": "jericho3"` selecting the new generator. -7. **Verification.** Compare the generated output against a known-good - reference configuration for that family. + table. The generator rejects an entry that targets a table not listed in + the ASIC's `table_names` when it is constructed. + +On DNX: + +- An unconditional SOC property can be set through + `platform_sdk_overrides`, which overrides `base_sdk_settings` and the + declarative tables. +- A scenario-dependent SOC property belongs in a platform-level + `conditional_settings` entry applying to `common`. Conditional settings + are the highest-priority step of the DNX pipeline and therefore also + override generated wiring keys. + +In both ASIC families, a setting that requires computation or new structure (for +example, new port mapping logic) needs a generic, data-driven extension of +the generator and the schema rather than a platform-specific branch in the +code. diff --git a/docs/docs/developing/asic_config_v3/schema_field_reference.md b/docs/docs/developing/asic_config_v3/schema_field_reference.md index 1d0bcfc1989f6..12c6e7ece9e72 100644 --- a/docs/docs/developing/asic_config_v3/schema_field_reference.md +++ b/docs/docs/developing/asic_config_v3/schema_field_reference.md @@ -1,5 +1,5 @@ --- -sidebar_position: 2 +sidebar_position: 5 --- # Schema Field Reference @@ -15,8 +15,9 @@ The configuration files contain two kinds of keys. in the schemas and interpreted directly by the generator. Introducing a new framework field requires adding it to the corresponding schema. - **Setting maps** are sections such as `platform_sai_overrides`, - `device_config_overrides`, or the ASIC-level `global_defaults` and - `sai_overrides`, whose keys are vendor SDK and SAI setting names, port + `platform_sdk_overrides`, `device_config_overrides`, the XGS ASIC-level + `global_defaults` and `sai_overrides`, or the DNX ASIC-level + `base_sdk_settings`, whose keys are vendor SDK and SAI setting names, port speeds, or output table entries. The schemas deliberately accept any key inside a setting map, because the set of valid vendor settings cannot be enumerated, so adding a setting there requires no schema change. @@ -26,7 +27,8 @@ The configuration files contain two kinds of keys. Platform configuration, defined by `platform_config.schema.json`. This schema validates every `fboss/configs/platforms///asic_config/asic_config.json` -file. +file, for both the XGS and DNX families. Fields that apply to a single family are marked with +the family name. ### Top-level fields @@ -35,8 +37,9 @@ file. | `platform_name` | yes | Platform identifier. Must match the platform directory name. | | `vendor` | yes | ASIC vendor identifier. Must match a directory name under `fboss/configs/asic_vendors/`. | | `asic` | yes | ASIC chip identifier. Must match the basename of a JSON file under `fboss/configs/asic_vendors///asics/`. | -| `num_ports_per_core` | no | Number of front-panel ports per ASIC core. Combined with the ASIC's lanes-per-core value to derive the number of lanes per port. | -| `num_lanes_per_port` | no | Explicit override of the derived lanes-per-port value, for platforms that wire only a subset of the lanes. | +| `num_ports_per_core` | no | XGS. Number of front-panel ports per ASIC core. Combined with the ASIC's lanes-per-core value to derive the number of lanes per port. | +| `num_lanes_per_port` | no | XGS. Explicit override of the derived lanes-per-port value, for platforms that wire only a subset of the lanes. | +| `output_structure` | no | DNX. Declares how generated keys are distributed across the thrift `AsicConfig` struct. The only supported `mode` is `common_only`, for single-NPU platforms. | | `defaults` | no | Shared settings inherited by every variant. A variant's own settings take precedence over the corresponding defaults. | | `variants` | yes | Named configuration variants. Each variant produces a separate output file. | @@ -47,33 +50,46 @@ following fields. | Field | Description | |---|---| -| `asic_config_params` | Parameters controlling generator behavior: `config_type` (output format), `config_gen_type` (generation profile, for example `DEFAULT`), `exact_match` (enables exact-match forwarding table entries), and `mmu_lossless` (enables MMU lossless mode for PFC and RDMA workloads). | -| `port_config` | Front-panel port settings: `default_speed` (in Mbps), `speed_to_fec` (mapping from speed to FEC mode), `enable` (the value emitted for `PC_PORT.ENABLE`), and `pc_port_overrides` (extra `PC_PORT` key/value lines emitted verbatim, for example `LINK_TRAINING`). | -| `cpu_port` | CPU port settings: `speed` (in Mbps) and `num_lanes`. | -| `mgmt_port` | Management port settings: `enabled` (whether the port is emitted at all), `enable` (the `PC_PORT.ENABLE` value), `in_port_block` (include the port in the `PORT` MTU range), and `speed_variants` (per-speed settings keyed by speed). | -| `mgmt_port_overrides` | Platform overrides of the ASIC-level management port defaults: `logical_id`, `physical_id`, `speed`, `num_lanes`, and `fec`. | -| `port_mapping_overrides` | Adjustments to the logical-to-physical port mapping formula: `core_range` (which cores participate, for example `"0-15,48-63"`), `num_lp_ports_on_even_core`, `num_logical_ports_per_datapath`, `lp_start_step_offset`, `lp_offset_simple`, `special_core_offset_apply_all`, and `exclude_logical_ports` (logical port IDs omitted from `PC_PORT_PHYS_MAP`, `PC_PORT`, and `PORT`, for front-panel ports that are not populated on the platform). | -| `platform_sai_overrides` | Platform-level SAI settings. These take precedence within the layered `global` sources and override the ASIC-level SAI overrides. | -| `device_config_overrides` | Key/value pairs written to the `DEVICE_CONFIG` output table, for example clock frequencies. | +| `asic_config_params` | Parameters controlling generator behavior, listed in the next table. | +| `port_config` | XGS. Front-panel port settings: `default_speed` (in Mbps), `speed_to_fec` (mapping from speed to FEC mode), `enable` (the value emitted for `PC_PORT.ENABLE`), and `pc_port_overrides` (extra `PC_PORT` key/value lines emitted verbatim, for example `LINK_TRAINING`). This object is distinct from the DNX `port_config` string inside `asic_config_params`. | +| `cpu_port` | XGS. CPU port settings: `speed` (in Mbps) and `num_lanes`. | +| `mgmt_port` | XGS. Management port settings: `enabled` (whether the port is emitted at all), `enable` (the `PC_PORT.ENABLE` value), `in_port_block` (include the port in the `PORT` MTU range), and `speed_variants` (per-speed settings keyed by speed). | +| `mgmt_port_overrides` | XGS. Platform overrides of the ASIC-level management port defaults: `logical_id`, `physical_id`, `speed`, `num_lanes`, and `fec`. | +| `port_mapping_overrides` | XGS. Adjustments to the logical-to-physical port mapping formula: `core_range` (which cores participate, for example `"0-15,48-63"`), `num_lp_ports_on_even_core`, `num_logical_ports_per_datapath`, `lp_start_step_offset`, `lp_offset_simple`, `special_core_offset_apply_all`, and `exclude_logical_ports` (logical port IDs omitted from `PC_PORT_PHYS_MAP`, `PC_PORT`, and `PORT`, for front-panel ports that are not populated on the platform). | +| `platform_sai_overrides` | XGS. Platform-level SAI settings. These take precedence within the layered `global` sources and override the ASIC-level SAI overrides. | +| `platform_sdk_overrides` | DNX. Platform-level SOC properties applied on top of the ASIC `base_sdk_settings` and declarative tables. Keys carry their SOC suffix inline. | +| `device_config_overrides` | XGS. Key/value pairs written to the `DEVICE_CONFIG` output table, for example clock frequencies. | | `features` | Boolean toggles for optional configuration sections: `generate_dlb_config`, `generate_dlb_ecmp_config`, `generate_low_clock_freq_settings`, and `generate_autoload_board_settings`. Absent flags default to disabled. | | `conditional_settings` | Platform-level conditional settings, evaluated after the ASIC-level ones so that platform values take precedence. | -| `preamble_file` | Path, relative to the `asic_config_v3` directory, of a preamble file prepended to the generated YAML. Honored only when the ASIC declares `preamble_support: true`. | +| `preamble_file` | XGS. Path, relative to the `asic_config_v3` directory, of a preamble file prepended to the generated YAML. Honored only when the ASIC declares `preamble_support: true`. | | `platform_mapping_name` | Overrides the `platform_mapping_v2` directory consulted for lane-map and polarity data. Defaults to `platform_name`. Useful when several variants share one `asic_config.json` but consume sibling platform mapping directories. | -| `ctr_eflex_config` | Variant-level override of the ASIC's `ctr_eflex_config` (enhanced flex counter) pass-through block. When present, it replaces the ASIC-level value in its entirety. | +| `ctr_eflex_config` | XGS. Variant-level override of the ASIC's `ctr_eflex_config` (enhanced flex counter) pass-through block. When present, it replaces the ASIC-level value in its entirety. | -In addition to the fields above, the generator honors a variant-level override -of any data block routed by the ASIC's `pass_through_settings`. Declaring -`flex_counter_settings`, `port_config_defaults`, `fp_config_defaults`, or -`tm_thd_config_defaults` in a variant replaces the corresponding ASIC-level -block, in the same way as `ctr_eflex_config`. The schema currently declares -only `ctr_eflex_config` among these. +### `asic_config_params` + +| Parameter | Description | +|---|---| +| `config_type` | Output configuration format: `YAML_CONFIG` (XGS), `KEY_VALUE_CONFIG` (DNX), or `JSON_CONFIG`. | +| `config_gen_type` | Generation profile, `DEFAULT` or `HW_TEST`. Conditional settings in both ASIC families may select on it. | +| `exact_match` | XGS. Enables exact-match forwarding table entries. | +| `mmu_lossless` | XGS. Enables MMU lossless mode for PFC and RDMA workloads. | +| `port_config` | DNX. Port-map profile name, for example `default` or `18*400G-4`. Conditional settings select the profile by exact name and the topology family by prefix, for example `dual_stage`. | +| `multistage_role` | DNX. Multistage fabric role, for example `NONE`, `FAP`, `FE13`, or `FE2`. Conditional settings select the settings for the role. | +| `hyper_port` | DNX. Boolean gate for hyper-port conditional settings. | + +In addition to the fields above, the XGS generator honors a variant-level +override of any data block routed by the ASIC's `pass_through_settings`. +Declaring `flex_counter_settings`, `port_config_defaults`, +`fp_config_defaults`, or `tm_thd_config_defaults` in a variant replaces the +corresponding ASIC-level block, in the same way as `ctr_eflex_config`. The +schema currently declares only `ctr_eflex_config` among these. The platform schema accepts unknown keys at the top and variant levels, so a key that is not listed here does not fail validation; the generator ignores it without an error or warning. When a setting appears to have no effect, verify the field name against this reference. -## ASIC Configuration +## Broadcom XGS ASIC Configuration Broadcom XGS ASIC configuration, defined by `broadcom_xgs_asic_config.schema.json`. This schema validates the per-ASIC @@ -94,39 +110,74 @@ files under `fboss/configs/asic_vendors/broadcom/xgs/asics/`. | `pass_through_settings` | Declarative routing list. Each entry names a `source` data block in this file and the `target_table` it is copied into. | | `conditional_settings` | ASIC-wide conditional settings, described below. | -### Conditional setting entries +## Broadcom DNX ASIC Configuration + +Broadcom DNX ASIC configuration, defined by +`broadcom_dnx_asic_config.schema.json`. This schema validates the per-ASIC +files under `fboss/configs/asic_vendors/broadcom/dnx/asics/`. -Each entry in a `conditional_settings` array supports the following fields. -The entry structure is defined in the Broadcom XGS ASIC schema. -Platform-level entries follow the same structure, but the platform schema does -not currently validate their internal structure, so field names and the -`condition` format in platform-level entries should be reviewed carefully. +| Field | Required | Description | +|---|---|---| +| `vendor`, `asic` | yes | Chip identity, for example `broadcom` and `jericho3`. | +| `asic_family` | yes | Always `dnx`. | +| `config_type` | yes | Always `KEY_VALUE_CONFIG`. DNX output is the key/value SOC property map carried in `AsicConfigEntry.config`. | +| `asic_suffix` | yes | SOC key suffix appended to generated keys, for example `BCM8889X`. | +| `additional_asic_suffixes` | no | Further SOC key suffixes appearing in this ASIC's settings data, for example `BCM8889X_ADAPTER` for the adapter target. Listed for documentation. Settings data carries these suffixes inline. | +| `num_lanes_per_core` | yes | Serdes lanes per core. The generator flattens a core identifier and core lane pair into the SOC lane number as `core_id * num_lanes_per_core + core_lane`. | +| `core_types` | yes | The `platform_mapping_v2` core types whose connections are traversed for wiring keys. Each core type is mapped to a `lane_map_family` and a `polarity_family` token, which select the key families used when rendering its wiring keys. Connections with undeclared core types are skipped. | +| `key_formats` | yes | Format strings for the generated wiring keys: `lane_map`, `lane_map_value`, `polarity_rx`, and `polarity_tx`, with `{family}`, `{lane}`, `{suffix}`, `{rx}`, and `{tx}` placeholders. | +| `default_polarity_settings` | no | Default polarity keys that carry no lane number, emitted verbatim, for example `phy_rx_polarity_flip.BCM8889X`. Jericho 3 declares them. An ASIC without such keys omits the field. | +| `base_sdk_settings` | no | ASIC-wide SOC properties emitted for every platform and variant. | +| `declarative_tables` | no | Fixed ASIC tables: `port_speed_map`, `tm_port_headers`, `dtm_flow_region_map` (`key_format`, `start_region`, `count`, and `value`), and `flow_remote_cores`. | +| `conditional_settings` | no | ASIC-level conditional settings, evaluated before platform-level ones. | + +## Conditional Setting Entries + +Conditional setting entries are defined once, in +`conditional_setting.schema.json`, and referenced by the platform, Broadcom +XGS, and Broadcom DNX schemas. Every `conditional_settings` list therefore +validates against the same structure. Whether a generator can execute a +given effect is checked by the generator itself when it is constructed. | Field | Required | Description | |---|---|---| | `name` | yes | Identifier, unique within the surrounding list. | | `description` | no | Free-form explanation of the setting. | -| `condition` | yes | The test to evaluate against the variant configuration. Its keys are listed in the table below. | -| `apply` | no | Inline settings applied when the condition is satisfied, keyed by target output table name. | -| `apply_from` | no | Reference to a data block elsewhere in the ASIC file; the named `source` block is copied into the named `target_table` when the condition is satisfied. | -| `skip_from_sai_common` | no | Keys to omit from the vendor SAI common layer while the condition is satisfied. Honored only on ASIC-level entries. | - -The `condition` object contains exactly the following three keys, all of which -are required: +| `condition` | yes | The test evaluated against the variant configuration. Its keys are listed below. | +| `apply` | no | Settings written when the condition holds, keyed by output target: a table name for XGS, a section name (`common`) for DNX. Values are integers or strings for XGS and strings for DNX. | +| `apply_from` | no | Copies the named `source` settings block of the ASIC file into the named `target_table` when the condition holds. Executes before `apply` within the same entry. Supported by both families. | +| `skip_from_sai_common` | no | Keys omitted from the vendor SAI common layer while the condition holds. Supported by XGS only. | + +An entry must declare at least one effect. The schema enforces the structure +of an entry, including operator and operand types. In addition, a generator +rejects an entry that declares an effect it does not support, has a +malformed effect payload, targets an output table or section that does not +exist, applies an empty settings block, or applies a value of the wrong type +for its output format. + +The `condition` object names the parameter to test and exactly one operator. +A parameter the variant does not declare evaluates as null, and each negative +operator is the strict complement of its positive counterpart. | Key | Description | |---|---| -| `source` | The variant-config section holding the parameter to evaluate: either `asic_config_params` or `features`. | -| `param` | The name of the parameter to compare. | -| `equals` | The value the parameter must equal for the condition to be satisfied. | +| `source` | The variant-config section holding the parameter, either `asic_config_params` or `features`. Defaults to `asic_config_params` when omitted. | +| `param` | The name of the parameter to test. | +| `equals` | Satisfied when the parameter equals this string, number, or boolean. | +| `not_equals` | Satisfied when the parameter does not equal this value, including when the parameter is absent. | +| `in` | Satisfied when the parameter equals one of the values in this non-empty array. | +| `not_in` | Satisfied when the parameter equals none of the values in this non-empty array, including when the parameter is absent. | +| `starts_with` | Satisfied when the parameter is a string starting with this prefix. | +| `not_starts_with` | Satisfied when the parameter is not a string starting with this prefix, including when the parameter is absent or not a string. | ## Vendor Common Configuration Vendor common configuration, defined by `vendor_common.schema.json`. This schema validates the family-wide common files, such as `fboss/configs/asic_vendors/broadcom/xgs/sdk_common.json` and -`fboss/configs/asic_vendors/broadcom/xgs/sai_common.json`. +`fboss/configs/asic_vendors/broadcom/xgs/sai_common.json`. The DNX family has no family-wide +common files. | Field | Required | Description | |---|---|---| -| `global` | yes | SDK or SAI settings copied into the `global` output table according to the layering order described in the [Overview](./overview.md). | +| `global` | yes | SDK or SAI settings copied into the `global` output table according to the layering order described on the [Broadcom XGS](./broadcom_xgs.md) page. |