[Nexthop][NPI] "asic_config_v3" - Add Broadcom DNX documentation

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/<asic>.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/<asic>.json` (`declarative_tables`) |
+| 3 | Platform SDK overrides | `platforms/<system_vendor>/<platform>/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/<asic>.json` (`conditional_settings`), then `platforms/<system_vendor>/<platform>/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_<N>` keys | Expanded from `key_format`, `start_region`, `count`, and `value`. |
+| `flow_remote_cores` | `dtm_flow_nof_remote_cores_region*` keys | Emitted verbatim. |

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/<asic>.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/<asic>.json` (`sai_overrides`) | `global` |
+| 6 | Platform SAI overrides | `platforms/<system_vendor>/<platform>/asic_config/asic_config.json` (`platform_sai_overrides`) | `global` |
+| 7 | [Pass-through settings](#pass-through-settings) | `asic_vendors/broadcom/xgs/asics/<asic>.json`, or `platforms/<system_vendor>/<platform>/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/<asic>.json` (`conditional_settings`), then `platforms/<system_vendor>/<platform>/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/<system_vendor>/<platform>/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`.
+
+:::

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/<system_vendor>/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/<system_vendor>/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/<system_vendor>/<name>/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/<name>_<variant>.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/<vendor>/<family>/asics/<asic>.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/<system_vendor>/<name>/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.