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. 9The BMC presently only checks traffic on the interface specified. There are 10now ethernet statistics available over IPMI, which can be checked directly in 11lieu of 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 40 41Response 42 43|Byte(s) |Value |Data 44|--------|-------|---- 45|0x00|0x01|Subcommand 46|0x01|Major|Major version 47|0x02|Minor|Minor Version 48|0x03|Sub 1|Third version number 49|0x04|Sub 2|Fourth version number 50 51**Per the above, if the version number doesn't fit in a byte it'll be cast to 52size.** 53 54#### GetEthDevice - SubCommand 0x02 55 56The BMC itself must have hard-coded into the image, which ethernet device is 57connected to the host NIC. This is true also in the mapping of ethernet device 58to channel number. Alternatively, you can pass a specific interface 59name for channel lookup. The channel number is used to configure the ethernet device 60over IPMI, instead of the interface name. This is because we leverage the 61current IPMI command set to read and write the networking configuration. Sys 62can be programmed already to have this information in the board protobuf, 63however, this information -- can be read from the BMC over IPMI. 64 65Request 66 67|Byte(s) |Value |Data 68|--------|-------|---- 69|0x00|0x02|Subcommand 70|0x01... |if_name| (optional) The interface name, not null-terminated 71 72Response 73 74|Byte(s) |Value |Data 75|--------|-------|---- 76|0x00|0x02|Subcommand 77|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). 78|0x02|if_name length|The length of the if_name in bytes. 79|0x03... |if_name|The interface name, not null-terminated 80 81#### DelayedHardReset - SubCommand 0x03 82 83Sys needs to be able to tell the BMC to reset the host but given a delay in 84seconds. 85 86Request 87 88|Byte(s) |Value |Data 89|--------|-------|---- 90|0x00|0x03|Subcommand 91|0x01..0x04| |Seconds to delay (uint32) 92 93Response 94 95|Byte(s) |Value |Data 96|--------|-------|---- 97|0x00|0x03|Subcommand 98 99### GetPCIeSlotsCount - SubCommand 0x04 100 101Sys can get the total number of PCIe slots from BMC using this command. When 102BMC receives this command, BMC can enumerate over all the PCIe slots and create 103a hashmap with all the available PCIe slot name - I2C bus number mappings. BMC 104can then send the total number of PCIe slots as part of this command response. 105 106Request 107 108|Byte(s) |Value |Data 109|--------|-------|---- 110|0x00|0x04|Subcommand 111 112 113Response 114 115|Byte(s) |Value |Data 116|--------|-------|---- 117|0x00|0x04|Subcommand 118|0x01|Total number of PCIe slots|Total number of PCIe slots 119 120### GetPCIeSlotI2cBusMapping - SubCommand 0x05 121 122If Sys gets N total slots as part of the above command, then Sys can send this 123command N times with Entry IDs ranging from 0 to N - 1. Say, Sys sends this 124command with Entry ID as 1, BMC can go and fetch the first PCIe slot name - I2C 125bus number mapping from the hashmap created above and then send the PCIe slot 126name and I2C bus number as part of the command response. 127 128Request 129 130|Byte(s) |Value |Data 131|--------|-------|---- 132|0x00|0x05|Subcommand 133|0x01|Entry ID|Entry ID ranging from 0 to N - 1 134 135 136Response 137 138|Byte(s) |Value |Data 139|--------|-------|---- 140|0x00|0x05|Subcommand 141|0x01|I2C bus number|The I2C bus number which is input to the above PCIe slot 142|0x02|PCIe slot name length|The PCIe slot name length 143|0x03...|PCIe slot name|The PCIe slot name without null terminator 144 145### GetEntityName - SubCommand 0x06 146 147Gsys can get the "Entity ID:Entity Instance" to Entity name mapping from BMC 148using this command. When BMC receives this command, BMC can check the related 149JSON file and then send the name for that particular entity as this command 150response. 151 152Request 153 154|Byte(s) |Value |Data 155|--------|------|---- 156|0x00|0x06|Subcommand 157|0x01|Entity ID|Entity ID 158|0x02|Entity Instance|Entity Instance 159 160Response 161 162|Byte(s) |Value |Data 163|--------|------|---- 164|0x00|0x06|Subcommand 165|0x01|Entity name length (say N)|Entity name length 166|0x02...0x02 + N - 1|Entity name|Entity name without null terminator 167 168### GetMachineName - SubCommand 0x07 169 170The BMC parses /etc/os-release for the OPENBMC_TARGET_MACHINE field and returns 171its value. 172 173Request 174 175|Byte(s) |Value |Data 176|--------|------|---- 177|0x00|0x06|Subcommand 178 179Response 180 181|Byte(s) |Value |Data 182|--------|------|---- 183|0x00|0x06|Subcommand 184|0x01|Model name length (say N)|Model name length 185|0x02...0x02 + N - 1|Model name|Model name without null terminator 186 187### HardResetOnShutdown - SubCommand 0x08 188 189Tells the BMC to powercycle the next time the host shuts down. 190 191Request 192 193|Byte(s) |Value |Data 194|--------|------|---- 195|0x00|0x08|Subcommand 196 197Response 198 199|Byte(s) |Value |Data 200|--------|------|---- 201|0x00|0x08|Subcommand 202 203 204### GetFlashSize - SubCommand 0x09 205 206Request the physical size of the BMC flash. 207 208Request 209 210|Byte(s) |Value |Data 211|--------|------|---- 212|0x00|0x09|Subcommand 213 214Response 215 216|Byte(s) |Value |Data 217|--------|------|---- 218|0x00|0x09|Subcommand 219|0x01...0x04|Flash size|Flash size 220 221### HostPowerOff - SubCommand 0x0A 222Sys command needs to be able to let the BMC knows host attempt S5 shutdown, 223it need power-off the Host gracefully and disable the watchdog with given time 224delay. 225 226Request 227 228|Byte(s) |Value |Data 229|--------|-------|---- 230|0x00|0x0A|Subcommand 231|0x01..0x04| |Seconds to delay (uint32) 232 233Response 234 235|Byte(s) |Value |Data 236|--------|-------|---- 237|0x00|0x0A|Subcommand 238 239### AccelOobDeviceCount - SubCommand 0x0B 240 241Query the number of available devices from the google-accel-oob service. 242 243If not enough data is proveded, `IPMI_CC_REQ_DATA_LEN_INVALID` is returned. 244 245Request 246 247|Byte(s) |Value |Data 248|--------|-------|---- 249|0x00|0x0B|Subcommand 250 251Response 252 253|Byte(s) |Value |Data 254|--------|-------|---- 255|0x00|0x0B|Subcommand 256|0x01..0x04| |Number of devices available 257 258### AccelOobDeviceName - SubCommand 0x0C 259 260Query the name of a single device from the google-accel-oob service. 261 262This name is used as the identifier for the AccelOobRead and AccelOobWrite 263commands. 264 265Index values start at zero and go up to (but don't include) the device count. 266 267The name of the device is exactly as it appears in DBus, except for the common 268"/com/google/customAccel/" prefix. This prefix is removed to reduce the size of 269the IPMI packet. 270 271DBus requires all element names to be non-empty strings of ASCII characters 272"[A-Z][a-z][0-9]_", seperated by ASCII '/'. Therefore, all device names will be 273valid ASCII strings (1 byte/character). 274 275For convenience, the name string is followed by a single 0x00 (NULL terminator) 276byte which is not included as part of the length. 277 278The length field (byte 5) is the number of bytes in the name string (not 279including the trailing NULL terminator byte). 280 281The maximum length for any name is 43 bytes (not including the trailing NULL). 282 283If a name is longer than 43 bytes, `IPMI_CC_REQ_DATA_TRUNCATED` is returned. 284These names will not be usable in the rest of the API. Changing the name 285requires code changes to the `managed_acceld` service binary. 286 287If not enough data is proveded, `IPMI_CC_REQ_DATA_LEN_INVALID` is returned. 288 289If a name does not begin with the expected "/com/google/customAccel/" prefix, 290`IPMI_CC_INVALID` is returned. This indicates a change in the DBus API for the 291google-accel-oob service that requires a matching code change in the handler. 292 293Request 294 295|Byte(s) |Value |Data 296|--------|-------|---- 297|0x00|0x0C|Subcommand 298|0x05| |Length of the name 299|0x06..n| |Name of the device 300 301Response 302 303|Byte(s) |Value |Data 304|--------|-------|---- 305|0x00|0x0C|Subcommand 306|0x01..0x04| |Index of the device 307|0x05| |Length of the name 308|0x06..n| |Name of the device 309 310### AccelOobRead - SubCommand 0x0D 311 312Read a PCIe CSR from a device. 313 314Length is the length of the name, in bytes. 315 316The device name gets prepended with "/com/google/customAccel/" and sent to DBus. 317This string must **NOT** have a trailing NULL terminator. 318 319The token is an arbitrary byte that gets echoed back in the reply; it is not 320interpreted by the service at all. This is used to disambiguate identical 321requests so clients can check for lost transactions. 322 323Address is the 64b PCIe address to read from. 324 325Number of bytes is the size of the read, in bytes (max 8). The value is subject 326to hardware limitations (both PCIe and ASIC), so it will generally be 1, 2, 4, 327or 8. 328 329The register data is always returned in 8 bytes (uint64) in little Endian order. 330If fewer than than 8 bytes are read, the MSBs are padded with 0s. 331 332On success, the response ends with the data read as a single uint64. 333 334If the number of bytes requested would not fit in a single IPMI payload, 335`IPMI_CC_REQUESTED_TOO_MANY_BYTES` is returned. 336 337If not enough data is proveded, `IPMI_CC_REQ_DATA_LEN_INVALID` is returned. 338 339Request 340 341|Byte(s) |Value |Data 342|--------|-------|---- 343|0x00|0x0D|Subcommand 344|0x01| |Number of bytes in the device name 345|0x02..n| |Name of the device (from `AccelOobDeviceName`) 346|n+1| |Token 347|n+2..n+10| |Address 348|n+11| |Number of bytes 349 350Response 351 352|Byte(s) |Value |Data 353|--------|-------|---- 354|0x00|0x0D|Subcommand 355|0x01| |Number of bytes in the device name 356|0x02..n| |Name of the device (no trailing NULL) 357|n+1| |Token 358|n+2..n+10| |Address 359|n+11| |Number of bytes 360|n+12..n+20| |Data 361 362### AccelOobWrite - SubCommand 0x0E 363 364Write a PCIe CSR from a device. 365 366All parameters are identical to AccelOobRead (above). The only difference is 367the register data becomes an input parameter (in the Request) instead of an 368output value (in the Response). 369 370As with read, the register data must be 8 bytes (uint64) in little Endian order. 371If fewer than 8 bytes will be written, only the LSBs will be read and the the 372MSBs will be ignored. 373 374All fields returned in the Response are simply a copy of the Request. 375 376On success, `IPMI_CC_OK` is returned. 377 378If not enough data is proveded, `IPMI_CC_REQ_DATA_LEN_INVALID` is returned. 379 380Request 381 382|Byte(s) |Value |Data 383|--------|-------|---- 384|0x00|0x0D|Subcommand 385|0x01| |Number of bytes in the device name 386|0x02..n| |Name of the device (from `AccelOobDeviceName`) 387|n+1| |Token 388|n+2..n+10| |Address 389|n+11| |Number of bytes 390|n+12..n+20| |Data 391 392Response 393 394|Byte(s) |Value |Data 395|--------|-------|---- 396|0x00|0x0D|Subcommand 397|0x01| |Number of bytes in the device name 398|0x02..n| |Name of the device (no trailing NULL) 399|n+1| |Token 400|n+2..n+10| |Address 401|n+11| |Number of bytes 402|n+12..n+20| |Data 403 404### PCIe Bifurcation - SubCommand 0x0F 405Sys command to return the highest level of bifurcation for the 406target PCIe Slot. 407 408Request 409 410|Byte(s) |Value |Data 411|--------|-------|---- 412|0x00|0x0F|Subcommand 413|0x01|PE slot number|Index of the PE slot 414 415Response 416 417|Byte(s) |Value |Data 418|--------|-------|---- 419|0x00|0x0F|Subcommand 420|0x01|Config length (N)|Number of bytes needed for the bifurcation config 421|0x02..0x02 + N - 1|Lanes per device|Each byte represents the number of lanes bonded together for each endpoint device 422