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]\_", seperated 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 0x12 461 462Get the accel's VR setting value for the given chip and settings ID 463 464Currently 3 settings are supported. [0] IdleMode [1] PowerBreak [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 | 0x12 | Subcommand | 475| 0x01 | | Chip ID | 476| 0x02 | | SettingsID | 477 478Response (if applicable) 479 480| Byte(s) | Value | Data | 481| ---------- | ----- | -------------- | 482| 0x00 | 0x12 | Subcommand | 483| 0x01..0x02 | 0x12 | Settings Value | 484 485### SysSetAccelVrSettings - SubCommand 0x13 486 487Update the VR settings of a given accel device for a specific settings id. 488 489Currently 3 settings are supported. [0] IdleMode [1] PowerBreak [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 | 0x13 | Subcommand | 503| 0x01 | | Chip ID | 504| 0x02 | | Settings ID | 505| 0x03..0x04 | 0x13 | Settings Value | 506 507Response (if applicable) 508 509| Byte(s) | Value | Data | 510| ------- | ----- | ---------- | 511| 0x00 | 0x13 | Subcommand | 512