xref: /openbmc/docs/designs/ncsi-coredump.md (revision 5a727b48) 
1# NC-SI core dump
2
3Author: DelphineCCChiu (<Delphine_CC_Chiu@wiwynn.com>)
4
5Created: 03/12/2024
6
7## Problem Description
8
9NIC core-dump is essential for NIC issue debugging, and it could be retrieved
10via both in-band and out of band method. The design here is providing the
11solution for NIC out of band dumping from BMC over NC-SI protocol.
12
13## Background and References
14
15NC-SI command for dump retrieval: Reference: NC-SI spec v1.2: section: 8.4.114
16<https://www.dmtf.org/sites/default/files/standards/documents/DSP0222_1.2.0.pdf>
17
18NC-SI over MCTP:
19<https://www.dmtf.org/sites/default/files/standards/documents/DSP0261_1.3.0.pdf>
20
21## Requirements
22
23This feature requires Linux kernel to support transferring new NC-SI command
24(0x4D) in net/ncsi module
25<https://github.com/torvalds/linux/commits/master/net/ncsi>
26
27## Proposed Design
28
29### Interface
30
31This design will reuse existing phosphor-debug-collector module:
32<https://github.com/openbmc/phosphor-debug-collector> and extent the dump
33creation interface with a new "NC-SICoreDump" dump type.
34
35The D-Bus interface for dump creation will be:"xyz.openbmc_project.Dump.Manager
36/xyz/openbmc_project/dump/bmc xyz.openbmc_project.Dump.Create"
37
38To indicate which NC-SI link to target, The CreateDump method need one
39additional input parameter: "NICTarget". An EID or network interface, such as
40eth0 could be a valid value.
41
42### Dump Retrieval
43
44Using standard NC-SI command: Retrieve Data From NC(0x4D) to get the dumps by
45NC-SI over RBT or NC-SI over MCTP protocol. All NC-SI dump procedure will be
46implemented in ncsi-netlink and ncsi-mctp utility in phosphor-networkd:
47<https://github.com/openbmc/phosphor-networkd/blob/master/src/ncsi_netlink_main.cpp>
48
49### Integrate with phosphor-debug-collector
50
51Since phosphor-debug-collector using shell scripts for data collection, a new
52collector script named "ncsicoredump" will be added. This script will help to
53call ncsi-netlink or ncsi-mctp by different NICTarget and generate dump file
54under specific folder.
55
56The following block diagram illustrate entire dump procedure and relationship
57between modules:
58
59```text
60
61                           +----------------+           +-----------+
62                           |                |           |           |
63              ------------->  Dump manager  +-----------> DumpEntry |
64               CreateDump  |                |           |           |
65                           +--------+-------+           +-----------+
66                                    |
67                                    |
68                                    |
69                           +--------v-------+
70                           |                |
71                           |    Dreport     |
72                           |                |
73                           +--------+-------+
74                                    |
75                                    |
76                                    |
77                           +--------v-------+
78                           |                |
79                           |  Plugin:       +------------------+
80                           |  ncsicoredump  |                  |
81                           |                |                  |
82                           +--------+-------+                  |
83                                    |                          |
84                                    |                          |
85                                    |                          |
86                                    |                          |
87      +------------+       +--------v-------+          +-------v------+        +------------+
88      |            |       |                |          |              |        |            |
89      |  DumpFile  <-------+  NCSI-NetLink  |          |  NCSI-MCTP   +-------->  DumpFile  |
90      |            |       |                |          |              |        |            |
91      +------------+       +--------^-------+          +-------^------+        +------------+
92                                    |                          |
93    --------------------------------+--------------------------+-----------------------------
94        Kernel                      |Netlink                   |MCTP
95                           +--------v-------+         +--------v-------+
96                           |                |         |                |
97                           |Net/NC-SI module|         |   I2C driver   |
98                           |                |         |                |
99                           +--------^-------+         +--------^-------+
100                                    |                          |
101                                    |NC-SI                     |SMBUS
102                                    |                          |
103                           +--------v--------------------------v-------+
104                           |                                           |
105                           |                     NIC                   |
106                           |                                           |
107                           +-------------------------------------------+
108
109```
110
111## Alternatives Considered
112
113We shall block duplicated dump procedure by the reception ordering of NC-SI
114command(0x4d) shall be maintained. Since the core dump will contain up to 2
115crash dump inside, we only support core dump now by it's sufficient for current
116usage.
117
118## Impacts
119
120None.
121
122## Testing
123
124Co-work with NIC vendor(Broadcom) for dump process/file validation.
125