README.md
1### Sys Commands (0x32)
2
3There are and will be a variety of sys specific commands.
4
5#### Cablecheck - SubCommand 0x00
6
7The cablecheck command checks whether the BMC is seeing traffic between itself
8and the host's NIC. Sys specifies which if_name is expected to be connected. The
9BMC presently only checks traffic on the interface specified. There are now
10ethernet statistics available over IPMI, which can be checked directly in lieu
11of this.
12
13Request
14
15| Byte(s) | Value | Data |
16| -------- | -------------- | --------------------------------------------- |
17| 0x00 | 0x00 | Subcommand |
18| 0x01 | If_name length | Where you expect the cable, eth0 or eth1, etc |
19| 0x02 ... | The name | The string, not null-terminated |
20
21Response
22
23| Byte(s) | Value | Data |
24| ------- | --------- | ----------------------- |
25| 0x00 | 0x00 | Subcommand |
26| 0x01 | 0x00/0x01 | 0 for false, 1 for true |
27
28#### CpldVersion - SubCommand 0x01
29
30Any CPLD on the system that can only be read directly via the BMC can have its
31version exported to Sys via the cpld version command.
32
33Request
34
35| Byte(s) | Value | Data |
36| ------- | ------- | --------------------------------------------------------------- |
37| 0x00 | 0x01 | Subcommand |
38| 0x01 | CPLD ID | A one-byte identifier for the CPLD file to read, unsigned byte. |
39
40Response
41
42| Byte(s) | Value | Data |
43| ------- | ----- | --------------------- |
44| 0x00 | 0x01 | Subcommand |
45| 0x01 | Major | Major version |
46| 0x02 | Minor | Minor Version |
47| 0x03 | Sub 1 | Third version number |
48| 0x04 | Sub 2 | Fourth version number |
49
50**Per the above, if the version number doesn't fit in a byte it'll be cast to
51size.**
52
53#### GetEthDevice - SubCommand 0x02
54
55The BMC itself must have hard-coded into the image, which ethernet device is
56connected to the host NIC. This is true also in the mapping of ethernet device
57to channel number. Alternatively, you can pass a specific interface name for
58channel lookup. The channel number is used to configure the ethernet device over
59IPMI, instead of the interface name. This is because we leverage the current
60IPMI command set to read and write the networking configuration. Sys can be
61programmed already to have this information in the board protobuf, however, this
62information -- can be read from the BMC over IPMI.
63
64Request
65
66| Byte(s) | Value | Data |
67| ------- | ------- | -------------------------------------------------- |
68| 0x00 | 0x02 | Subcommand |
69| 0x01... | if_name | (optional) The interface name, not null-terminated |
70
71Response
72
73| Byte(s) | Value | Data |
74| ------- | -------------- | --------------------------------------------------------------------------------------------------------------------------- |
75| 0x00 | 0x02 | Subcommand |
76| 0x01 | Channel number | The IPMI channel number for use with the network configuration commands (such as reading the MAC or IP address of the BMC). |
77| 0x02 | if_name length | The length of the if_name in bytes. |
78| 0x03... | if_name | The interface name, not null-terminated |
79
80#### DelayedHardReset - SubCommand 0x03
81
82Sys needs to be able to tell the BMC to reset the host but given a delay in
83seconds.
84
85Request
86
87| Byte(s) | Value | Data |
88| ---------- | ----- | ------------------------- |
89| 0x00 | 0x03 | Subcommand |
90| 0x01..0x04 | | Seconds to delay (uint32) |
91
92Response
93
94| Byte(s) | Value | Data |
95| ------- | ----- | ---------- |
96| 0x00 | 0x03 | Subcommand |
97
98### GetPCIeSlotsCount - SubCommand 0x04
99
100Sys can get the total number of PCIe slots from BMC using this command. When BMC
101receives this command, BMC can enumerate over all the PCIe slots and create a
102hashmap with all the available PCIe slot name - I2C bus number mappings. BMC can
103then send the total number of PCIe slots as part of this command response.
104
105Request
106
107| Byte(s) | Value | Data |
108| ------- | ----- | ---------- |
109| 0x00 | 0x04 | Subcommand |
110
111Response
112
113| Byte(s) | Value | Data |
114| ------- | -------------------------- | -------------------------- |
115| 0x00 | 0x04 | Subcommand |
116| 0x01 | Total number of PCIe slots | Total number of PCIe slots |
117
118### GetPCIeSlotI2cBusMapping - SubCommand 0x05
119
120If Sys gets N total slots as part of the above command, then Sys can send this
121command N times with Entry IDs ranging from 0 to N - 1. Say, Sys sends this
122command with Entry ID as 1, BMC can go and fetch the first PCIe slot name - I2C
123bus number mapping from the hashmap created above and then send the PCIe slot
124name and I2C bus number as part of the command response.
125
126Request
127
128| Byte(s) | Value | Data |
129| ------- | -------- | -------------------------------- |
130| 0x00 | 0x05 | Subcommand |
131| 0x01 | Entry ID | Entry ID ranging from 0 to N - 1 |
132
133Response
134
135| Byte(s) | Value | Data |
136| ------- | --------------------- | -------------------------------------------------------- |
137| 0x00 | 0x05 | Subcommand |
138| 0x01 | I2C bus number | The I2C bus number which is input to the above PCIe slot |
139| 0x02 | PCIe slot name length | The PCIe slot name length |
140| 0x03... | PCIe slot name | The PCIe slot name without null terminator |
141
142### GetEntityName - SubCommand 0x06
143
144Gsys can get the "Entity ID:Entity Instance" to Entity name mapping from BMC
145using this command. When BMC receives this command, BMC can check the related
146JSON file and then send the name for that particular entity as this command
147response.
148
149Request
150
151| Byte(s) | Value | Data |
152| ------- | --------------- | --------------- |
153| 0x00 | 0x06 | Subcommand |
154| 0x01 | Entity ID | Entity ID |
155| 0x02 | Entity Instance | Entity Instance |
156
157Response
158
159| Byte(s) | Value | Data |
160| ------------------- | -------------------------- | ----------------------------------- |
161| 0x00 | 0x06 | Subcommand |
162| 0x01 | Entity name length (say N) | Entity name length |
163| 0x02...0x02 + N - 1 | Entity name | Entity name without null terminator |
164
165### GetMachineName - SubCommand 0x07
166
167The BMC parses /etc/os-release for the OPENBMC_TARGET_MACHINE field and returns
168its value.
169
170Request
171
172| Byte(s) | Value | Data |
173| ------- | ----- | ---------- |
174| 0x00 | 0x06 | Subcommand |
175
176Response
177
178| Byte(s) | Value | Data |
179| ------------------- | ------------------------- | ---------------------------------- |
180| 0x00 | 0x06 | Subcommand |
181| 0x01 | Model name length (say N) | Model name length |
182| 0x02...0x02 + N - 1 | Model name | Model name without null terminator |
183
184### HardResetOnShutdown - SubCommand 0x08
185
186Tells the BMC to powercycle the next time the host shuts down.
187
188Request
189
190| Byte(s) | Value | Data |
191| ------- | ----- | ---------- |
192| 0x00 | 0x08 | Subcommand |
193
194Response
195
196| Byte(s) | Value | Data |
197| ------- | ----- | ---------- |
198| 0x00 | 0x08 | Subcommand |
199
200### GetFlashSize - SubCommand 0x09
201
202Request the physical size of the BMC flash.
203
204Request
205
206| Byte(s) | Value | Data |
207| ------- | ----- | ---------- |
208| 0x00 | 0x09 | Subcommand |
209
210Response
211
212| Byte(s) | Value | Data |
213| ----------- | ---------- | ---------- |
214| 0x00 | 0x09 | Subcommand |
215| 0x01...0x04 | Flash size | Flash size |
216
217### HostPowerOff - SubCommand 0x0A
218
219Sys command needs to be able to let the BMC knows host attempt S5 shutdown, it
220need power-off the Host gracefully and disable the watchdog with given time
221delay.
222
223Request
224
225| Byte(s) | Value | Data |
226| ---------- | ----- | ------------------------- |
227| 0x00 | 0x0A | Subcommand |
228| 0x01..0x04 | | Seconds to delay (uint32) |
229
230Response
231
232| Byte(s) | Value | Data |
233| ------- | ----- | ---------- |
234| 0x00 | 0x0A | Subcommand |
235
236### AccelOobDeviceCount - SubCommand 0x0B
237
238Query the number of available devices from the google-accel-oob service.
239
240If not enough data is proveded, `IPMI_CC_REQ_DATA_LEN_INVALID` is returned.
241
242Request
243
244| Byte(s) | Value | Data |
245| ------- | ----- | ---------- |
246| 0x00 | 0x0B | Subcommand |
247
248Response
249
250| Byte(s) | Value | Data |
251| ---------- | ----- | --------------------------- |
252| 0x00 | 0x0B | Subcommand |
253| 0x01..0x04 | | Number of devices available |
254
255### AccelOobDeviceName - SubCommand 0x0C
256
257Query the name of a single device from the google-accel-oob service.
258
259This name is used as the identifier for the AccelOobRead and AccelOobWrite
260commands.
261
262Index values start at zero and go up to (but don't include) the device count.
263
264The name of the device is exactly as it appears in DBus, except for the common
265"/com/google/customAccel/" prefix. This prefix is removed to reduce the size of
266the IPMI packet.
267
268DBus requires all element names to be non-empty strings of ASCII characters
269"[A-Z][a-z][0-9]\_", separated by ASCII '/'. Therefore, all device names will be
270valid ASCII strings (1 byte/character).
271
272For convenience, the name string is followed by a single 0x00 (NULL terminator)
273byte which is not included as part of the length.
274
275The length field (byte 5) is the number of bytes in the name string (not
276including the trailing NULL terminator byte).
277
278The maximum length for any name is 43 bytes (not including the trailing NULL).
279
280If a name is longer than 43 bytes, `IPMI_CC_REQ_DATA_TRUNCATED` is returned.
281These names will not be usable in the rest of the API. Changing the name
282requires code changes to the `managed_acceld` service binary.
283
284If not enough data is proveded, `IPMI_CC_REQ_DATA_LEN_INVALID` is returned.
285
286If a name does not begin with the expected "/com/google/customAccel/" prefix,
287`IPMI_CC_INVALID` is returned. This indicates a change in the DBus API for the
288google-accel-oob service that requires a matching code change in the handler.
289
290Request
291
292| Byte(s) | Value | Data |
293| ------- | ----- | ------------------ |
294| 0x00 | 0x0C | Subcommand |
295| 0x05 | | Length of the name |
296| 0x06..n | | Name of the device |
297
298Response
299
300| Byte(s) | Value | Data |
301| ---------- | ----- | ------------------- |
302| 0x00 | 0x0C | Subcommand |
303| 0x01..0x04 | | Index of the device |
304| 0x05 | | Length of the name |
305| 0x06..n | | Name of the device |
306
307### AccelOobRead - SubCommand 0x0D
308
309Read a PCIe CSR from a device.
310
311Length is the length of the name, in bytes.
312
313The device name gets prepended with "/com/google/customAccel/" and sent to DBus.
314This string must **NOT** have a trailing NULL terminator.
315
316The token is an arbitrary byte that gets echoed back in the reply; it is not
317interpreted by the service at all. This is used to disambiguate identical
318requests so clients can check for lost transactions.
319
320Address is the 64b PCIe address to read from.
321
322Number of bytes is the size of the read, in bytes (max 8). The value is subject
323to hardware limitations (both PCIe and ASIC), so it will generally be 1, 2, 4,
324or 8.
325
326The register data is always returned in 8 bytes (uint64) in little Endian order.
327If fewer than than 8 bytes are read, the MSBs are padded with 0s.
328
329On success, the response ends with the data read as a single uint64.
330
331If the number of bytes requested would not fit in a single IPMI payload,
332`IPMI_CC_REQUESTED_TOO_MANY_BYTES` is returned.
333
334If not enough data is proveded, `IPMI_CC_REQ_DATA_LEN_INVALID` is returned.
335
336Request
337
338| Byte(s) | Value | Data |
339| --------- | ----- | ---------------------------------------------- |
340| 0x00 | 0x0D | Subcommand |
341| 0x01 | | Number of bytes in the device name |
342| 0x02..n | | Name of the device (from `AccelOobDeviceName`) |
343| n+1 | | Token |
344| n+2..n+10 | | Address |
345| n+11 | | Number of bytes |
346
347Response
348
349| Byte(s) | Value | Data |
350| ---------- | ----- | ------------------------------------- |
351| 0x00 | 0x0D | Subcommand |
352| 0x01 | | Number of bytes in the device name |
353| 0x02..n | | Name of the device (no trailing NULL) |
354| n+1 | | Token |
355| n+2..n+10 | | Address |
356| n+11 | | Number of bytes |
357| n+12..n+20 | | Data |
358
359### AccelOobWrite - SubCommand 0x0E
360
361Write a PCIe CSR from a device.
362
363All parameters are identical to AccelOobRead (above). The only difference is the
364register data becomes an input parameter (in the Request) instead of an output
365value (in the Response).
366
367As with read, the register data must be 8 bytes (uint64) in little Endian order.
368If fewer than 8 bytes will be written, only the LSBs will be read and the the
369MSBs will be ignored.
370
371All fields returned in the Response are simply a copy of the Request.
372
373On success, `IPMI_CC_OK` is returned.
374
375If not enough data is proveded, `IPMI_CC_REQ_DATA_LEN_INVALID` is returned.
376
377Request
378
379| Byte(s) | Value | Data |
380| ---------- | ----- | ---------------------------------------------- |
381| 0x00 | 0x0D | Subcommand |
382| 0x01 | | Number of bytes in the device name |
383| 0x02..n | | Name of the device (from `AccelOobDeviceName`) |
384| n+1 | | Token |
385| n+2..n+10 | | Address |
386| n+11 | | Number of bytes |
387| n+12..n+20 | | Data |
388
389Response
390
391| Byte(s) | Value | Data |
392| ---------- | ----- | ------------------------------------- |
393| 0x00 | 0x0D | Subcommand |
394| 0x01 | | Number of bytes in the device name |
395| 0x02..n | | Name of the device (no trailing NULL) |
396| n+1 | | Token |
397| n+2..n+10 | | Address |
398| n+11 | | Number of bytes |
399| n+12..n+20 | | Data |
400
401### PCIe Bifurcation - SubCommand 0x0F
402
403Sys command to return the highest level of bifurcation for the target PCIe Slot.
404
405Request
406
407| Byte(s) | Value | Data |
408| ------- | -------------- | -------------------- |
409| 0x00 | 0x0F | Subcommand |
410| 0x01 | PE slot number | Index of the PE slot |
411
412Response
413
414| Byte(s) | Value | Data |
415| ------------------ | ----------------- | --------------------------------------------------------------------------------- |
416| 0x00 | 0x0F | Subcommand |
417| 0x01 | Config length (N) | Number of bytes needed for the bifurcation config |
418| 0x02..0x02 + N - 1 | Lanes per device | Each byte represents the number of lanes bonded together for each endpoint device |
419
420### GetBmcMode - SubCommand 0x10
421
422Request the operational mode of the BMC.
423
424Request
425
426| Byte(s) | Value | Data |
427| ------- | ----- | ---------- |
428| 0x00 | 0x10 | Subcommand |
429
430Response
431
432| Byte(s) | Value | Data |
433| ------- | ---------------- | ------------------------------------------------------------------------------------------------------------- |
434| 0x00 | 0x10 | Subcommand |
435| 0x01 | Current BMC MODE | <ul><li>0 -> Non Bare Metal Mode</li><li>1 -> Bare Metal Mode</li><li>2 -> Bare Metal Cleaning Mode</li></ul> |
436
437### LinuxBootDone - SubCommand 0x11
438
439Notify the BMC that LinuxBoot is finished and will kexec into the OS
440momentarily.
441
442If in bare metal mode, the BMC will disable IPMI upon receiving this command, to
443protect against a malicious OS. For this reason, the BMC may not respond to this
444command.
445
446If not in bare metal mode, this command has no effect.
447
448Request
449
450| Byte(s) | Value | Data |
451| ------- | ----- | ---------- |
452| 0x00 | 0x11 | Subcommand |
453
454Response (if applicable)
455
456| Byte(s) | Value | Data |
457| ------- | ----- | ---------- |
458| 0x00 | 0x11 | Subcommand |
459
460### SysGetAccelVrSettings - SubCommand 0x15
461
462Get the accel's VR setting value for the given chip and settings ID
463
464Currently 3 settings are supported. [0] IdleMode [1] PowerBrake [2] Loadline
465
466On success, the response contains 2 bytes containing the setting value.
467
468If not enough data is proveded, `IPMI_CC_REQ_DATA_LEN_INVALID` is returned.
469
470Request
471
472| Byte(s) | Value | Data |
473| ------- | ----- | ---------- |
474| 0x00 | 0x15 | Subcommand |
475| 0x01 | | Chip ID |
476| 0x02 | | SettingsID |
477
478Response (if applicable)
479
480| Byte(s) | Value | Data |
481| ---------- | ----- | -------------- |
482| 0x00 | 0x15 | Subcommand |
483| 0x01..0x02 | 0x15 | Settings Value |
484
485### SysSetAccelVrSettings - SubCommand 0x16
486
487Update the VR settings of a given accel device for a specific settings id.
488
489Currently 3 settings are supported. [0] IdleMode [1] PowerBrake [2] Loadline
490
491The settings value parameter is a 2 byte value and is expected in little endian
492format
493
494On success, `IPMI_CC_OK` is returned.
495
496If not enough data is proveded, `IPMI_CC_REQ_DATA_LEN_INVALID` is returned.
497
498Request
499
500| Byte(s) | Value | Data |
501| ---------- | ----- | -------------- |
502| 0x00 | 0x16 | Subcommand |
503| 0x01 | | Chip ID |
504| 0x02 | | Settings ID |
505| 0x03..0x04 | 0x16 | Settings Value |
506
507Response (if applicable)
508
509| Byte(s) | Value | Data |
510| ------- | ----- | ---------- |
511| 0x00 | 0x16 | Subcommand |
512
513### GetBMInstanceProperty - SubCommand 0x17
514
515Read a BM instance property, specify the property to read following the enum.
516
517The response contains the length of the property string to read in bytes
518followed by the property string which does **NOT** have a NULL terminator.
519
520Request
521
522| Byte(s) | Value | Data |
523| ------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------ |
524| 0x00 | 0x17 | Subcommand |
525| 0x01 | | 0x0: AssetTag <br>0x1: BoardSerialNumber <br>0x2: Family <br>0x3: ProductName <br>0x4: SKU <br>0x5: SystemSerialNumber <br>0x6: UUID |
526
527Response
528
529| Byte(s) | Value | Data |
530| ----------------- | ------------------ | ---------------------------------------------------------------- |
531| 0x00 | 0x17 | Subcommand |
532| 0x01 | String Length (N) | Number of bytes to read for property string - Size limited to 64 |
533| 0x2..0x02 + N - 1 | String of property | String, not null-terminated |
534
535### ReadBiosSetting - SubCommand 0x18
536
537Read a BIOS setting, set at `/run/oem_bios_setting`.
538
539The response contains the length of the BIOS setting followed by the BIOS
540setting bytes read.
541
542Request
543
544| Byte(s) | Value | Data |
545| ------- | ----- | ---------- |
546| 0x00 | 0x18 | Subcommand |
547
548Response
549
550| Byte(s) | Value | Data |
551| ----------------- | ------------- | -------------------------------------------- |
552| 0x00 | 0x18 | Subcommand |
553| 0x01 | Length (N) | Number of payload bytes - Size limited to 64 |
554| 0x2..0x02 + N - 1 | Payload bytes | Payload bytes |
555
556### WriteBiosSetting - SubCommand 0x19
557
558Write a BIOS setting, set at `/run/oem_bios_setting`.
559
560The response contains the length of the BIOS setting followed by the BIOS
561setting bytes read.
562
563Request
564
565| Byte(s) | Value | Data |
566| ----------------- | ------------- | -------------------------------------------- |
567| 0x00 | 0x19 | Subcommand |
568| 0x01 | Length (N) | Number of payload bytes - Size limited to 64 |
569| 0x2..0x02 + N - 1 | Payload bytes | Payload bytes |
570
571Response
572
573| Byte(s) | Value | Data |
574| ------- | ---------- | ------------------------------------ |
575| 0x00 | 0x19 | Subcommand |
576| 0x01 | Length (N) | Number of bytes successfully written |
577