docs(contract): request part_number for pcie_devices in the Reanimator contract

Proposal to Reanimator Core (Hardware Ingest JSON Contract 2.13): pcie_devices
carry only the chip-level model from PCI IDs, so different products on the
same chip fall into one model group. Requested by LOGPile and BEE-SP.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Mikhail ChusavitinandClaude Opus 5.5 committed 2026-10-02 15:01:19 +03:00
1 parent 1cc2faa567
commit 28badfc90c
1 file changed
+101
@@ -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`.