Make silicon pcie_address optional

Summary:
`icecube800bc`'s spec carried a placeholder NPU PCIe address (`00:01.0`) that
its own `_review_notes` flagged as not-yet-known. A placeholder is worse than
nothing here: it passes pre-flight and then gets aggregated into the platform's
PCIe presence-check list as if it were real.

Drop it from the spec, and make `platform.silicon[].pcie_address` optional so
omission is the supported way to say "not known yet":

- `schemas/platform-spec.v1.json`: remove `pcie_address` from the `silicon`
  item `required` list. The `BB:DD.F` pattern is unchanged, so a present value
  is still validated exactly as before.
- `validator/spec_validator.py`: `_Silicon.pcie_address` becomes
  `str | None = None`, and the format check is skipped when absent.
- `configs/icecube800bc/spec.json`: `{ "name": "TH6" }`, with the review note
  reworded from "replace this placeholder" to "add it once confirmed".
- `references/vendor-spec-schema.md`: field marked optional, with a worked
  example and an explicit note that an empty string is not a valid stand-in.

An empty string is deliberately still rejected — the `BB:DD.F` pattern does not
match `""`, so there is exactly one way to express "unknown" and consumers do
not have to special-case a sentinel. Per-component `pcie_address` (in
`$defs/component`) was already optional and is untouched.

___

Differential Revision: D117156310

fbshipit-source-id: 6d61075f2c2dff2b4b40666a4616efea6d0939a9

Author: Joan Olguy Canéus

fboss/platform/firmware_onboarding/configs/icecube800bc/spec.json

@@ -4,7 +4,7 @@
   "platform": {
     "name": "icecube800bc",
     "silicon": [
-      { "name": "TH6", "pcie_address": "00:01.0" }
+      { "name": "TH6" }
     ]
   },
 
@@ -104,7 +104,7 @@
   ],
 
   "_review_notes": [
-    "platform.silicon[0].pcie_address — '00:01.0' is a placeholder; replace with the actual NPU PCIe BB:DD.F address from the platform reference design",
+    "platform.silicon[0].pcie_address — omitted because the NPU PCIe address is not yet known; add it (BB:DD.F, from the platform reference design) once confirmed",
     "components — mirrors the current fbcode/fboss/platform/configs/icecube/fw_util.json. If icecube800bc actually has additional firmware components (e.g. fan_cpld, smb_fpga, psu) that aren't yet in fw_util.json, add them to BOTH this spec AND the platform's fw_util.json. (Note: pre-flight does NOT cross-check fw_util.json — that gate was deferred; the spec is the source of truth for the orchestrator.)",
     "components[*].location and display_location — best-effort placeholders inferred from component name conventions; confirm against the actual icecube800bc reference design",
     "components[*].field_replaceable — confirm each setting matches the actual chassis design",

fboss/platform/firmware_onboarding/references/vendor-spec-schema.md

@@ -38,7 +38,7 @@ A worked example is in `configs/icecube800bc/spec.json`.
 
 ## `platform`
 
-Platform-wide identity. Both fields are required.
+Platform-wide identity. `name` and `silicon` are required.
 
 ```jsonc
 "platform": {
@@ -49,12 +49,24 @@ Platform-wide identity. Both fields are required.
 }
 ```
 
+If the NPU's PCIe address is not yet known, omit `pcie_address` entirely rather
+than supplying a placeholder — `{ "name": "TH6" }` is valid:
+
+```jsonc
+"platform": {
+  "name": "icecube800bc",
+  "silicon": [
+    { "name": "TH6" }
+  ]
+}
+```
+
 | Field | Type | Notes |
 |---|---|---|
 | `name` | string | Lowercase canonical name of the platform (e.g. `"icecube800bc"`). This is the name Meta uses to refer to your platform across all systems — it's the same name that is programmed in the eeprom. The name that was communicated to you by Meta. No spaces, no uppercase. |
 | `silicon` | list of objects | NPU silicon families on the platform. Always a list (even for a single NPU) so dual-NPU platforms can be expressed uniformly. |
 | `silicon[].name` | string | Canonical short token for the silicon family (e.g. `"TH6"`, `"TH5"`, `"J3"`, `"R3"`). |
-| `silicon[].pcie_address` | string | PCIe bus address of the NPU on this platform, format `BB:DD.F` (lowercase hex, e.g. `"00:01.0"`). Aggregated by Meta into the platform's PCIe presence-check list alongside per-component `pcie_address` entries. |
+| `silicon[].pcie_address` | string, optional | PCIe bus address of the NPU on this platform, format `BB:DD.F` (lowercase hex, e.g. `"00:01.0"`). Aggregated by Meta into the platform's PCIe presence-check list alongside per-component `pcie_address` entries. Omit the field if the address is not yet known — do not supply a placeholder or an empty string, both of which will fail pre-flight. |
 
 > **Component PCIe addresses** are declared per-component (see `pcie_address` in the components section), not here. Meta aggregates the silicon addresses with per-component addresses into the platform's PCIe presence-check list at onboarding time.
 

fboss/platform/firmware_onboarding/schemas/platform-spec.v1.json

@@ -24,7 +24,7 @@
           "minItems": 1,
           "items": {
             "type": "object",
-            "required": ["name", "pcie_address"],
+            "required": ["name"],
             "additionalProperties": false,
             "properties": {
               "name": {"type": "string", "minLength": 1},

fboss/platform/firmware_onboarding/validator/spec_validator.py

@@ -161,11 +161,15 @@ class _Silicon(BaseModel):
     model_config = ConfigDict(extra="forbid")
 
     name: str = Field(min_length=1)
-    pcie_address: str
+    # Optional: omit when the NPU's PCIe address is not yet known. Meta skips
+    # the entry when aggregating the platform's PCIe presence-check list.
+    pcie_address: str | None = None
 
     @model_validator(mode="after")
     def _check(self) -> _Silicon:  # noqa: B902 — pydantic mode="after" instance method
-        if not _PCIE_ADDRESS_RE.match(self.pcie_address):
+        if self.pcie_address is not None and not _PCIE_ADDRESS_RE.match(
+            self.pcie_address
+        ):
             raise ValueError(
                 f"silicon '{self.name}': pcie_address '{self.pcie_address}' "
                 "is not in BB:DD.F format (lowercase hex)"

fboss/platform/firmware_onboarding/validator/tests/test_spec_validator.py

@@ -136,9 +136,23 @@ def test_silicon_empty_list_fails(self) -> None:
         errors = validate_spec_dict(spec)
         self.assertTrue(any("silicon" in e for e in errors))
 
-    def test_silicon_missing_pcie_address_fails(self) -> None:
+    def test_silicon_omitted_pcie_address_validates(self) -> None:
+        # pcie_address is optional: omit it when the NPU address isn't known yet.
         spec = _spec_with()
         spec["platform"]["silicon"] = [{"name": "TH6"}]
+        self.assertEqual([], validate_spec_dict(spec))
+
+    def test_silicon_missing_name_fails(self) -> None:
+        spec = _spec_with()
+        spec["platform"]["silicon"] = [{"pcie_address": "00:01.0"}]
+        errors = validate_spec_dict(spec)
+        self.assertTrue(any("name" in e for e in errors))
+
+    def test_silicon_empty_pcie_address_fails(self) -> None:
+        # An empty string is not an accepted stand-in for "unknown" — omit the
+        # field instead.
+        spec = _spec_with()
+        spec["platform"]["silicon"] = [{"name": "TH6", "pcie_address": ""}]
         errors = validate_spec_dict(spec)
         self.assertTrue(any("pcie_address" in e for e in errors))