diff --git a/bible-local/docs/reanimator-contract-request-pcie-part-number.md b/bible-local/docs/reanimator-contract-request-pcie-part-number.md new file mode 100644 index 0000000..cf90021 --- /dev/null +++ b/bible-local/docs/reanimator-contract-request-pcie-part-number.md @@ -0,0 +1,101 @@ +--- +title: "Запрос на правку контракта: part_number у pcie_devices" +target: Reanimator Core — Hardware Ingest JSON Contract (текущая версия 2.13) +requested_by: LOGPile, BEE-SP +date: "2026-09-29" +status: proposed +--- + +# Запрос на правку контракта: `part_number` у `pcie_devices` + +## Проблема + +`part_number` есть в контракте у `memory` (используется как модель), `storage` +и `power_supplies`, но не у `pcie_devices`. Для PCIe-устройств передаётся только +`model`, а это название чипа из PCI IDs, общее для разных изделий на одном чипе. + +В результате Reanimator не различает изделия с одинаковым чипом: + +- они попадают в одну группу модели; +- их прошивки сравниваются между собой, и на расхождение появляется ложное + предупреждение; +- в реестре компонентов нельзя отличить сетевую карту от mezz-модуля или + встроенного контроллера. + +## Пример из реального источника + +Gigabyte G894 (HGX B300 NVL8), BEE-SP v14.15, 2026-09-29. VPD из `lspci -vvv`: + +| BDF | `model` (PCI IDs) | `[PN]` из VPD | Изделие | Прошивка | +|---|---|---|---|---| +| `6c:00.0/.1`, `e9:00.0/.1` | MT2910 Family [ConnectX-7] | `MCX755106AS-HEAT` | Сетевая карта ConnectX-7, 200GbE/NDR | 28.44.1036 | +| `d3:00.0`–`d3:00.3` | MT2910 Family [ConnectX-7] | `V000S4N03X` | ConnectX-7 mezz на модуле HGX B300 | 28.47.2526 | +| `17`, `5a`, `73`, `7a`, `97`, `d7`, `f0`, `f7` | CX8 Family [ConnectX-8] | `MLX000647` | ConnectX-8 на модуле HGX B300 | 40.47.2526 | + +Сейчас Reanimator помечает `28.47.2526` у CX7 mezz как расхождение с +`28.44.1036` у CX7-адаптеров. Это разные изделия с разными линейками прошивки, +расхождения нет. + +Партномер из VPD у PCIe-устройств встречается часто: сетевые карты Mellanox, +Intel, Broadcom, RAID/HBA-контроллеры, часть GPU. Redfish отдаёт его как +`PCIeDevice.PartNumber` и `NetworkAdapter.PartNumber`. + +## Предложение + +Добавить в `pcie_devices[]` необязательное поле: + +| Поле | Тип | Обязательно | Описание | +|------|-----|-------------|----------| +| `part_number` | string | нет | Партномер изделия по данным источника (VPD `[PN]`, Redfish `PartNumber`, FRU). Передаётся как есть, без пробелов по краям | + +### Семантика на стороне Reanimator + +1. **Идентичность изделия.** При наличии `part_number` использовать его при + разрешении канонической модели наравне с `vendor_id`/`device_id` (как в + 2.13 для `storage`), чтобы изделия на одном чипе не сливались в одну запись + реестра. +2. **Сравнение прошивок.** Сравнивать прошивки только внутри одного + `part_number`. Если `part_number` нет, оставить текущее поведение. +3. **Отображение.** `model` остаётся названием чипа, `part_number` показывается + отдельно, как у `storage` и `power_supplies`. +4. **Изменение `part_number`** у устройства в том же слоте с тем же серийником + считать коррекцией атрибута, а не заменой компонента: партномер может + появиться, когда сборщик начнёт его читать. + +### Правила для интеграторов + +- Не синтезировать: не подставлять `model`, название из PCI IDs или Product + Name из VPD вместо партномера. +- Заглушки источника не передавать. Пример: у Intel X710 на Gigabyte VPD + содержит `Product Name: Example VPD` и не содержит `[PN]`, поле не заполняется. +- У многофункционального устройства (несколько PCI functions одного изделия) + передавать один и тот же `part_number` у каждой функции. + +### Пример + +```json +"pcie_devices": [ + { + "slot": "0000:d3:00.2", + "vendor_id": 5555, + "device_class": "NetworkController", + "manufacturer": "Mellanox Technologies", + "model": "MT2910 Family [ConnectX-7]", + "part_number": "V000S4N03X", + "serial_number": "1951326573849", + "firmware": "28.47.2526" + } +] +``` + +## Changelog-строка (предлагаемая) + +| 2.14 | — | Для `pcie_devices[]` добавлено необязательное поле `part_number` (партномер изделия из VPD/Redfish/FRU); используется при разрешении канонической модели и для сравнения прошивок внутри одного изделия | + +## Что сделают интеграторы после принятия + +- **BEE-SP** уже будет собирать `[PN]` из VPD в снимок (задание по прошивке и + партномеру Mellanox) и начнёт передавать `part_number` в `reanimator.json`. +- **LOGPile** добавит `part_number` в `ReanimatorPCIe` + (`internal/exporter/reanimator_models.go`), заполнит его из внутренней модели + PCIe-устройств и обновит зеркало `docs/hardware-ingest-contract.md`.