1Copyright 2018 IBM 2 3Licensed under the Apache License, Version 2.0 (the "License"); you may not use 4this file except in compliance with the License. You may obtain a copy of the 5License at 6 7http://www.apache.org/licenses/LICENSE-2.0 8 9Unless required by applicable law or agreed to in writing, software distributed 10under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR 11CONDITIONS OF ANY KIND, either express or implied. See the License for the 12specific language governing permissions and limitations under the License. 13 14# Introduction 15 16This document defines a protocol and several transports for flash access 17mediation between the host and the Baseboard Management Controller (BMC). 18 19The driving motivation for the protocol is to expose flash devices owned by the 20BMC to the host. Usually, the flash device of interest is the host's firmware 21flash device - in some platform designs this is owned by the BMC to enable 22lights-out updates of the host firmware. 23 24As the flash is owned by the BMC, access by the host to its firmware must be 25abstracted and mediated. Abstraction and mediation alleviates several problems: 26 271. Proliferation of flash controller driver implementations throughout firmware 282. Conflict of access between the host and the BMC to the flash controller 293. In some circumstances, mitigates security concerns. 30 31The protocol introduced in this document addresses each of these issues. 32Specifically, the document addresses defining a control mechanism for exposing 33flash data in the LPC firmware space, communicated via functions in the LPC IO 34space. 35 36# Scope 37 38The scope of the document is limited to defining the protocol and its 39transports, and does not cover the content or structure of the data read or 40written to the flash by the host firmware. 41 42The definition of transport-specific parameters, for example selection of IPMI 43`(NetFn, Command)` pairs, is also beyond the scope of the document. 44 45# Background, Design and Constraints 46 47The protocol was developed to meet requirements on OpenPOWER systems based 48around the ASPEED BMC System-on-Chips such as the AST2400 and AST2500. The 49ASPEED BMCs have properties and features that need to be taken into account: 50 511. A read-only mapping of the SPI flash devices onto the ARM core's AHB 522. Remapping of LPC Firmware cycles onto the AHB (LPC2AHB bridge) 533. A reasonable but not significant amount of attached DRAM 54 55Prior to the development of the protocol described below flash reads were 56serviced by pointing the LPC2AHB bridge at the read-only flash mapping, and 57writes were serviced by a separate bridge that suffers significant performance 58and security issues. 59 60Point 3 serves to justify some of the design decisions embodied in the protocol, 61mainly the complexity required by the flexibility to absorb as much or as little 62reserved memory as desired via the concept of BMC-controlled windowing. 63 64The core concept of the protocol moves access away from the naive routing of LPC 65firmware cycles onto the host firmware SPI flash AHB mapping, and concentrates 66on servicing the LPC firmware cycles from reserved system memory. As the memory 67backing the LPC2AHB mapping is now writable the protocol meets the host's write 68requirements by defining commands to open, dirty and flush an in-memory window 69representing the state of the flash. The mechanism to read the flash becomes 70same as write, just that the dirty and flush commands are not legal on such 71windows. 72 73## Historic and Future Naming 74 75The original transport for the protocol was the ASPEED BMC LPC mailbox 76interface, and previous revisions of the protocol documentation referred to the 77protocol as the "mailbox" or "mbox" protocol. This naming is now deprecated, as 78the protocol has grown further transports and naming the protocol by its 79transport rather than its intent was, on reflection, misguided. 80 81The protocol has been tentatively renamed to the "Host I/O Mapping Protocol" or 82"hiomap". This is a reflection of its true purpose - to control the host's view 83of data exposed from the BMC. 84 85# Protocol Overview 86 87The primary flow of the protocol is for the host to send requests to the BMC, 88which adjusts the mapping of the LPC firmware space as requested and returns a 89status response to the host. These interactions are labelled "commands". 90However, as there is now an active software component on the BMC consuming 91access requests, the BMC must occasionally indicate state changes to the host. 92Such interactions are labelled "events". For example, if a user or other system 93software on the BMC suspends the host's access to its flash device, the BMC-side 94daemon implementing the protocol must notify the host that its requests will be 95denied until further notice. 96 97## Protocol Versioning 98 99To enable evolution of the command and event interfaces, incremental changes to 100the behaviour are defined in new versions of the protocol. The descriptions and 101tables that follow all identify the versions to which they are applicable. 102 103The highest currently specified protocol version is version 3. 104 105## Table of Commands 106 107| ID | Name | v1 | v2 | v3 | Description | 108| --- | ----------------------------------------------------- | --- | --- | --- | ------------------------------------------------------------------------ | 109| 1 | [`RESET`](#reset-command) | ✓ | ✓ | ✓ | Reset the state of the LPC firmware space, closing any active window | 110| 2 | [`GET_INFO`](#get_info-command) | ✓ | ✓ | ✓ | Perform protocol version negotiation and retrieve fundamental parameters | 111| 3 | [`GET_FLASH_INFO`](#get_flash_info-command) | ✓ | ✓ | ✓ | Retrieve flash-specific parameters | 112| 4 | [`CREATE_READ_WINDOW`](#create_read_window-command) | ✓ | ✓ | ✓ | Request mapping of a flash region for read | 113| 5 | [`CLOSE`](#close-command) | ✓ | ✓ | ✓ | Close the current window, flushing any dirty regions | 114| 6 | [`CREATE_WRITE_WINDOW`](#create_write_window-command) | ✓ | ✓ | ✓ | Request mapping of a flash region for write | 115| 7 | [`MARK_DIRTY`](#mark_dirty-command) | ✓ | ✓ | ✓ | Mark a region of a write window as modified | 116| 8 | [`FLUSH`](#flush-command) | ✓ | ✓ | ✓ | Flush dirty regions of the write window to flash | 117| 9 | [`ACK`](#ack-command) | ✓ | ✓ | ✓ | Acknowledge the receipt of an event from the BMC | 118| 10 | [`ERASE`](#erase-command) | | ✓ | ✓ | Mark a region of a write window as erased | 119| 11 | [`GET_FLASH_NAME`](#get_flash_name-command) | | | ✓ | Retrieve the name of an indexed flash device | 120| 12 | [`LOCK`](#lock-command) | | | ✓ | Mark a region of the current flash window as immutable | 121 122## Table of Events 123 124| ID | Name | v1 | v2 | v3 | Description | 125| --- | ------------------------------------------------- | --- | --- | --- | ------------------------------------------------------------------------------------------- | 126| 0 | [`PROTOCOL_RESET`](#protocol_reset-event) | ✓ | ✓ | ✓ | The host is required to perform version negotiation and re-establish its window of interest | 127| 1 | [`WINDOW_RESET`](#window_reset-event) | | ✓ | ✓ | The host must re-establish its window of interest | 128| 6 | [`FLASH_CONTROL_LOST`](#flash_control_lost-event) | | ✓ | ✓ | The host should suspend access requests | 129| 7 | [`DAEMON_READY`](#daemon_ready-event) | | ✓ | ✓ | The daemon is active and can accept commands | 130 131## List of Transports 132 133An essential feature of the protocol is that its behaviour is independent of the 134host-BMC transport. The command and event interfaces of each transport 135necessarily reflect the version of the protocol they are implementing, but the 136transport has no influence otherwise. 137 138There are three documented transports for the protocol: 139 1401. The [ASPEED BMC LPC Mailbox transport](#mailbox-transport) 1412. The [IPMI transport](#ipmi-transport) 1423. The [DBus transport](#dbus-transport) 143 144The command layout, routing and event mechanism for each transport all have 145different features and are detailed below. An important note is that command 146design is limited by the most constrained transport - the LPC mailbox 147transport - where only 11 bytes are available for encoding of command 148parameters. 149 150Implementations must choose to support one or more of the transports outlined in 151this document. 152 153Note that the DBus transport is intended for BMC-internal communications, and 154can be used to separate a host-interface transport from the protocol 155implementation. 156 157## Protocol Flow 158 159The high-level protocol flow is that the host first issues a `GET_INFO` command 160to negotiate the protocol version and acquire parameters fundamental to 161constructing arguments to and interpreting responses from the commands that 162follow. 163 164Once `GET_INFO` has successfully completed, the host should request the flash 165parameters with `GET_FLASH_INFO`. The response provides information on the flash 166capacity and the size of its erase granule. 167 168Following `GET_FLASH_INFO`, the next act is to establish an active flash window 169with either one of the `CREATE_READ_WINDOW` or `CREATE_WRITE_WINDOW` commands. 170 171In the event of creating a write window the host must inform the BMC of the 172regions to which it has written with `MARK_DIRTY`- the BMC receives no 173notification of accesses from the host, they are simply mapped by the LPC2AHB 174bridge as necessary. As the accesses are to system memory and not the flash the 175changes identified by the `MARK_DIRTY` commands are not permanent until a 176`FLUSH` command is received (implicit flushes are discussed below), at which 177point the dirty regions of the active window will be written to the flash 178device. 179 180As an optimisation the host may choose to use the `ERASE` command to indicate 181that large regions should be set to the erased state. This optimisation saves 182the associated LPC firmware cycles to write the regions into the erased state. 183 184## Version Negotiation 185 186When invoking `GET_INFO` the host must provide the BMC its highest supported 187version of the protocol. The BMC must respond with a protocol version less than 188or equal to that requested by the host, or in the event that there is no such 189value, an error code. In the event that an error is returned the host must not 190continue to communicate with the BMC. Otherwise, the protocol version returned 191by the BMC is the agreed protocol version for all further communication. The 192host may at a future point request a change in protocol version by issuing a 193subsequent `GET_INFO` command. 194 195### Unversioned Commands 196 197In some circumstances it is necessary for bootstrap or optimisation purposes to 198support unversioned commands. The protocol supports three unversioned commands: 199 2001. `RESET` 2012. `GET_INFO` 2023. `ACK` 203 204All remaining commands have their presence and behaviour specified with respect 205to the negotiated version of the protocol. 206 207The arguments to the `GET_INFO` command are considered unversioned and as a 208result are static in nature - the protocol implementation has no means to decode 209version-specific arguments as the version has not yet been negotiated. With 210respect to the response, the version field is unversioned, but all subsequent 211fields _may_ be versioned. 212 213`RESET` remaining unversioned is an optimisation catering to deeply embedded 214components on the host side that may need access to the command. Keeping `RESET` 215unversioned removes the complexity of implementing `GET_INFO` with its version 216negotiation and minimises the overhead required to get into the pre-boot state. 217 218Defining `ACK` as unversioned ensures host firmware that has minimal protocol 219support can silence interrupts from the BMC as required. 220 221## Sequence Numbers 222 223Sequence numbers are included in messages for correlation of commands and 224responses. v1, v2 and v3 of the protocol permit either zero or one commands to 225be in progress (yet to receive a response). 226 227For generality, the host must generate a sequence number that is unique with 228respect to the previous command (one that has received a response) and any 229in-progress commands. Sequence numbers meeting this requirement are considered 230valid. The BMC's response to a command must contain the same sequence number 231issued by the host as found in the relevant command. 232 233Sequence numbers may be reused in accordance with the constraints outlined 234above. However, it is not an error if the BMC receives a unversioned command 235(`RESET`, `GET_INFO` or `ACK`) with an invalid sequence number. For all other 236cases, the BMC must respond with an error if the constraints are violated. If 237the host receives a sequence-related error response it must consider any 238in-progress commands to have failed. The host may retry the affected command(s) 239after generating a suitable sequence number. 240 241## Window Management 242 243There is only ever one active window which is the window created by the most 244recent `CREATE_READ_WINDOW` or `CREATE_WRITE_WINDOW` call which succeeded. Even 245though there are two types of windows there can still only be one active window 246irrespective of type. The host must not write to a read window. The host may 247read from a write window and the BMC must guarantee that the window reflects 248what the host has written there. 249 250A window can be closed by issuing the `CLOSE` command, in which case there is no 251active window and the host must not access the LPC firmware space until a window 252is subsequently opened. If the host closes an active write window then the BMC 253must perform an implicit flush. If the host tries to open a new window with an 254already active window then the active window is closed (and implicitly flushed 255if it was a write window). If the new window is successfully opened then it is 256the new active window; if the command fails then there is no active window and 257the previously active window must no longer be accessed. 258 259The host must not access an LPC address other than that which is contained by 260the active window. The host must not use write management functions (see below) 261if the active window is a read window or if there is no active window. 262 263## Command Parameter Types 264 265It is common in the protocol definition for command parameters to be represented 266in terms of a block size. This block size may refer to e.g. the size of the 267erase granule of the flash, or it may be another value entirely. Regardless of 268what it represents, the argument values are scaled by the block size determined 269by version negotiation. Specifying arguments in terms of a block size allows 270transports to keep a compact representation in constrained implementations such 271as the LPC mailbox transport. 272 273Note that for simplicity block size must always be a power-of-2. The block size 274must also be greater than or equal to 4K regardless of the negotiated protocol 275version. 276 277Finally, conversion between blocks and bytes is achieved by respectively 278dividing or multiplying the quantity by the negotiated block-size. 279 280# Transport Overview 281 282Several transports are defined for the protocol and are outlined below. The key 283features of transport support are the wire-format, delivery mechanisms of 284commands and events, and the definition and delivery of response codes. 285 286The DBus transport is the most foreign of the three as it does not encode the 287command index or a sequence number; these two elements are handled by the 288properties of DBus itself. 289 290## Mailbox Transport 291 292- Multi-byte quantity endianness: Little-endian 293- Command length encoding: Assumed from negotiated protocol version 294- Parameter alignment: Packed (no padding) 295- Command status response: ABI-defined Response byte 296- Event Delivery: ABI-defined BMC Status byte 297 298The mailbox transport defines the ABI used over the mailbox registers. There are 29916 data registers and several status and control registers for managing 300interrupts between the host and the BMC. For the purpose of defining the 301transport ABI the status and control registers can mostly be disregarded, save 302for the necessity of issuing and responding to interrupts on each side. 303 304Assuming the registers are in a contiguous layout (this is not reflected in the 305hardware, but may be the abstraction presented by the associated kernel driver), 306the ABI is defined as follows, where the bytes in the range [2, 12] are 307available for command parameters and are defined on a per-command basis. 308 309``` 310 0 7 15 31 311 +----------+----------+---------------------+ 312 0 | Command | Sequence | | 313 +----------+----------+---------------------+ 314 4 | | 315 +-------------------------------------------+ 316 8 | | 317 +----------+----------+----------+----------+ 31812 | | Response | BMC Sts | Host Sts | 319 +----------+----------+----------+----------+ 320 0 7 15 23 31 321``` 322 323Command status response codes are as follows: 324 325### Status Codes 326 327| ID | Name | v1 | v2 | v3 | Description | 328| --- | -------------- | --- | --- | --- | ---------------------------------------------------- | 329| 1 | `SUCCESS` | ✓ | ✓ | ✓ | Command completed successfully | 330| 2 | `PARAM_ERROR` | ✓ | ✓ | ✓ | Error with parameters supplied or command invalid | 331| 3 | `WRITE_ERROR` | ✓ | ✓ | ✓ | Error writing to the backing file system | 332| 4 | `SYSTEM_ERROR` | ✓ | ✓ | ✓ | Error in BMC performing system action | 333| 5 | `TIMEOUT` | ✓ | ✓ | ✓ | Timeout in performing action | 334| 6 | `BUSY` | | ✓ | ✓ | Flash access suspended, retry later | 335| 7 | `WINDOW_ERROR` | | ✓ | ✓ | Invalid window state or command invalid for window | 336| 8 | `SEQ_ERROR` | | ✓ | ✓ | Invalid sequence number supplied with command | 337| 9 | `LOCKED_ERROR` | | | ✓ | Erased or dirtied region intersected a locked region | 338 339## IPMI Transport 340 341- Multi-byte quantity endianness: Little-endian 342- Command length encoding: Assumed from negotiated protocol version 343- Parameter alignment: Packed (no padding) 344- Command status response: Mapped to IPMI completion codes 345- Event Delivery: Status byte in SEL via `SMS_ATN` 346 347The IPMI transport must reserve one `(NetFn, Command)` pair for host-to-BMC 348communications and one SEL `(NetFn, Command)` pair for BMC-to-host 349communication, signaled by `SMS_ATN`. 350 351The wire command framing is as follows: 352 3531. The command identifier is the first value and is encoded in one byte 3542. The sequence number is the second value and is encoded in one byte 3553. Parameters required by the (version, command) pair follow 356 357``` 358 0 7 15 N 359 +----------+----------+--------- -------+ 360 0 | Command | Sequence | ... | 361 +----------+----------+--------- -------+ 362``` 363 364## DBus Transport 365 366- Multi-byte quantity endianness: Transport encoded 367- Command length encoding: Transport encoded 368- Parameter alignment: Transport encoded 369- Command status response: Mapped to Unix system error codes 370- Event Delivery: DBus signals and properties per event type 371 372DBus defines its own wire-format for messages, and so support for this transport 373concentrates on mapping commands and events onto DBus concepts. Specifically, 374commands are represented by DBus methods and events are represented by 375properties. DBus will automatically generate a `PropertiesChanged` signal for 376changes to properties allowing consumers to learn of updates as they happen. 377 378As the commands are represented by DBus methods there is no need to encode the 379command index in the request - this is represented by the appropriate method on 380the implementation object's interface. 381 382Similarly, there's no need to encode sequence numbers as DBus handles the 383correlation of messages over the bus. As there is no encoding of sequence 384numbers, there is no need to describe a command status response like 385`SEQ_ERROR`, which allows a clean mapping to Unix error codes. 386 387Finally, commands mapped to methods have the number of parameters and types 388described by the method's type signature, though these descriptions concern the 389basic wire types and not the semantic types relevant to the protocol. The method 390type signature and parameter ordering are described in the relevant command 391definition. 392 393# Command Definitions 394 395The command identifier values and command-response parameter formats are 396described in tables under headers for each command. The order of the parameters 397in the parameter tables reflects the order of the parameters in the commands and 398responses. The M, I, and D columns represent the Mailbox, IPMI and DBus 399transports respectively. For the command identifier table the value in these 400columns' cells represent the command index, or for DBus, its method name. For 401the parameter tables the value represent the parameter's offset in the message 402(disregarding the command and sequence bytes), or in the case of DBus the 403appropriate 404[type signature](https://dbus.freedesktop.org/doc/dbus-specification.html#basic-types). 405 406## `RESET` Command 407 408| v1 | v2 | v3 | M | I | D | 409| --- | --- | --- | --- | --- | ----- | 410| ✓ | ✓ | ✓ | 1 | 1 | Reset | 411 412### v1 Parameters 413 414<table> 415<tr> 416<th>Command</th><th>Response</th> 417</tr> 418<tr> 419<td valign="top"> 420 421| Parameter | Unit | Size | M | I | D | 422| --------- | ---- | ---- | --- | --- | --- | 423 424</td> 425<td valign="top"> 426 427| Parameter | Unit | Size | M | I | D | 428| --------- | ---- | ---- | --- | --- | --- | 429 430</td> 431</tr> 432</table> 433 434### v2 Parameters 435 436<table> 437<tr> 438<th>Command</th><th>Response</th> 439</tr> 440<tr> 441<td valign="top"> 442 443| Parameter | Unit | Size | M | I | D | 444| --------- | ---- | ---- | --- | --- | --- | 445 446</td> 447<td valign="top"> 448 449| Parameter | Unit | Size | M | I | D | 450| --------- | ---- | ---- | --- | --- | --- | 451 452</td> 453</tr> 454</table> 455 456### v3 Parameters 457 458<table> 459<tr> 460<th>Command</th><th>Response</th> 461</tr> 462<tr> 463<td valign="top"> 464 465| Parameter | Unit | Size | M | I | D | 466| --------- | ---- | ---- | --- | --- | --- | 467 468</td> 469<td valign="top"> 470 471| Parameter | Unit | Size | M | I | D | 472| --------- | ---- | ---- | --- | --- | --- | 473 474</td> 475</tr> 476</table> 477 478### Description 479 480Requests the BMC return the LPC firmware space to a state ready for host 481firmware bootstrap. 482 483## `GET_INFO` Command 484 485| v1 | v2 | v3 | M | I | D | 486| --- | --- | --- | --- | --- | ------- | 487| ✓ | ✓ | ✓ | 2 | 2 | GetInfo | 488 489### v1 Parameters 490 491<table> 492<tr> 493<th>Command</th><th>Response</th> 494</tr> 495<tr> 496<td valign="top"> 497 498| Parameter | Unit | Size | M | I | D | 499| --------- | ------- | ---- | --- | --- | --- | 500| Version | Version | 1 | 0 | 0 | y | 501 502</td> 503<td valign="top"> 504 505| Parameter | Unit | Size | M | I | D | 506| ----------------- | ------- | ---- | --- | --- | --- | 507| Version | Version | 1 | 0 | 0 | y | 508| Read Window Size | Blocks | 2 | 1 | 1 | q | 509| Write Window Size | Blocks | 2 | 3 | 3 | q | 510 511</td> 512</tr> 513</table> 514 515### v2 Parameters 516 517<table> 518<tr> 519<th>Command</th><th>Response</th> 520</tr> 521<tr> 522<td valign="top"> 523 524| Parameter | Unit | Size | M | I | D | 525| --------- | ------- | ---- | --- | --- | --- | 526| Version | Version | 1 | 0 | 0 | y | 527 528</td> 529<td valign="top"> 530 531| Parameter | Unit | Size | M | I | D | 532| ---------------- | ------- | ---- | --- | --- | --- | 533| Version | Version | 1 | 0 | 0 | y | 534| Block Size Shift | Count | 1 | 5 | 1 | y | 535| Timeout | Seconds | 2 | 6 | 2 | q | 536 537</td> 538</tr> 539</table> 540 541### v3 Parameters 542 543<table> 544<tr> 545<th>Command</th><th>Response</th> 546</tr> 547<tr> 548<td valign="top"> 549 550| Parameter | Unit | Size | M | I | D | 551| ---------------- | ------- | ---- | --- | --- | --- | 552| Version | Version | 1 | 0 | 0 | y | 553| Block Size Shift | Count | 1 | 1 | 1 | y | 554 555</td> 556<td valign="top"> 557 558| Parameter | Unit | Size | M | I | D | 559| ---------------- | ------- | ---- | --- | --- | --- | 560| Version | Version | 1 | 0 | 0 | y | 561| Block Size Shift | Count | 1 | 5 | 1 | y | 562| Timeout | Seconds | 2 | 6 | 2 | q | 563| Devices | Count | 1 | 8 | 4 | y | 564 565</td> 566</tr> 567</table> 568 569### Description 570 571The suggested timeout is a hint to the host as to how long it should wait after 572issuing a command to the BMC before it times out waiting for a response. This is 573the maximum time which the BMC thinks it could take to service any command which 574the host could issue. This may be set to zero to indicate that the BMC does not 575wish to provide a hint in which case the host must choose some reasonable value. 576 577From v3 the host may desire a specific block size and thus can request this by 578giving a hint to the daemon (may be zero). The daemon may use this to select the 579block size which it will use however is free to ignore it. The value in the 580response is the block size which must be used for all further requests until a 581new size is negotiated by another call to `GET_INFO`. 582 583## `GET_FLASH_INFO` Command 584 585| v1 | v2 | v3 | M | I | D | 586| --- | --- | --- | --- | --- | ------------ | 587| ✓ | ✓ | ✓ | 3 | 3 | GetFlashInfo | 588 589### v1 Parameters 590 591<table> 592<tr> 593<th>Command</th><th>Response</th> 594</tr> 595<tr> 596<td valign="top"> 597 598| Parameter | Unit | Size | M | I | D | 599| --------- | ---- | ---- | --- | --- | --- | 600 601</td> 602<td valign="top"> 603 604| Parameter | Unit | Size | M | I | D | 605| ------------- | ----- | ---- | --- | --- | --- | 606| Flash Size | Bytes | 4 | 0 | 0 | u | 607| Erase Granule | Bytes | 4 | 4 | 4 | u | 608 609</td> 610</tr> 611</table> 612 613### v2 Parameters 614 615<table> 616<tr> 617<th>Command</th><th>Response</th> 618</tr> 619<tr> 620<td valign="top"> 621 622| Parameter | Unit | Size | M | I | D | 623| --------- | ---- | ---- | --- | --- | --- | 624 625</td> 626<td valign="top"> 627 628| Parameter | Unit | Size | M | I | D | 629| ------------- | ------ | ---- | --- | --- | --- | 630| Flash Size | Blocks | 2 | 0 | 0 | q | 631| Erase Granule | Blocks | 2 | 2 | 2 | q | 632 633</td> 634</tr> 635</table> 636 637### v3 Parameters 638 639<table> 640<tr> 641<th>Command</th><th>Response</th> 642</tr> 643<tr> 644<td valign="top"> 645 646| Parameter | Unit | Size | M | I | D | 647| --------- | ----- | ---- | --- | --- | --- | 648| Device ID | Index | 1 | 0 | 0 | y | 649 650</td> 651<td valign="top"> 652 653| Parameter | Unit | Size | M | I | D | 654| ------------- | ------ | ---- | --- | --- | --- | 655| Flash Size | Blocks | 2 | 0 | 0 | q | 656| Erase Granule | Blocks | 2 | 2 | 2 | q | 657 658</td> 659</tr> 660</table> 661 662## `CREATE_READ_WINDOW` Command 663 664| v1 | v2 | v3 | M | I | D | 665| --- | --- | --- | --- | --- | ---------------- | 666| ✓ | ✓ | ✓ | 4 | 4 | CreateReadWindow | 667 668### v1 Parameters 669 670<table> 671<tr> 672<th>Command</th><th>Response</th> 673</tr> 674<tr> 675<td valign="top"> 676 677| Parameter | Unit | Size | M | I | D | 678| ------------ | ------ | ---- | --- | --- | --- | 679| Flash Offset | Blocks | 2 | 0 | 0 | q | 680 681</td> 682<td valign="top"> 683 684| Parameter | Unit | Size | M | I | D | 685| ------------- | ------ | ---- | --- | --- | --- | 686| LPC FW Offset | Blocks | 2 | 0 | 0 | q | 687 688</td> 689</tr> 690</table> 691 692### v2 Parameters 693 694<table> 695<tr> 696<th>Command</th><th>Response</th> 697</tr> 698<tr> 699<td valign="top"> 700 701| Parameter | Unit | Size | M | I | D | 702| ------------- | ------ | ---- | --- | --- | --- | 703| Flash Address | Blocks | 2 | 0 | 0 | q | 704| Length | Blocks | 2 | 2 | 2 | q | 705 706</td> 707<td valign="top"> 708 709| Parameter | Unit | Size | M | I | D | 710| -------------- | ------ | ---- | --- | --- | --- | 711| LPC FW Address | Blocks | 2 | 0 | 0 | q | 712| Length | Blocks | 2 | 2 | 2 | q | 713| Flash Address | blocks | 2 | 4 | 4 | q | 714 715</td> 716</tr> 717</table> 718 719### v3 Parameters 720 721<table> 722<tr> 723<th>Command</th><th>Response</th> 724</tr> 725<tr> 726<td valign="top"> 727 728| Parameter | Unit | Size | M | I | D | 729| ------------- | ------ | ---- | --- | --- | --- | 730| Flash Address | Blocks | 2 | 0 | 0 | q | 731| Length | Blocks | 2 | 2 | 2 | q | 732| Device ID | Index | 1 | 4 | 4 | y | 733 734</td> 735<td valign="top"> 736 737| Parameter | Unit | Size | M | I | D | 738| -------------- | ------ | ---- | --- | --- | --- | 739| LPC FW Address | Blocks | 2 | 0 | 0 | q | 740| Length | Blocks | 2 | 2 | 2 | q | 741| Flash Address | blocks | 2 | 4 | 4 | q | 742 743</td> 744</tr> 745</table> 746 747### Description 748 749The flash offset which the host requests access to is always taken from the 750start of flash - that is it is an absolute offset into flash. 751 752LPC bus address is always given from the start of the LPC address space - that 753is it is an absolute address. 754 755The requested access size is only a hint. The response indicates the actual size 756of the window. The BMC may want to use the requested size to pre-load the 757remainder of the request. The host must not access past the end of the active 758window. 759 760The flash offset mapped by the window is an absolute flash offset and must be 761less than or equal to the flash offset requested by the host. It is the 762responsibility of the host to use this information to access any offset which is 763required. 764 765The requested window size may be zero. In this case the BMC is free to create 766any sized window but it must contain at least the first block of data requested 767by the host. A large window is of course preferred and should correspond to the 768default size returned in the `GET_INFO` command. 769 770If this command returns successfully then the created window is the active 771window. If it fails then there is no active window. 772 773## `CLOSE` Command 774 775| v1 | v2 | v3 | M | I | D | 776| --- | --- | --- | --- | --- | ----- | 777| ✓ | ✓ | ✓ | 5 | 5 | Close | 778 779### v1 Parameters 780 781<table> 782<tr> 783<th>Command</th><th>Response</th> 784</tr> 785<tr> 786<td valign="top"> 787 788| Parameter | Unit | Size | M | I | D | 789| --------- | ---- | ---- | --- | --- | --- | 790 791</td> 792<td valign="top"> 793 794| Parameter | Unit | Size | M | I | D | 795| --------- | ---- | ---- | --- | --- | --- | 796 797</td> 798</tr> 799</table> 800 801### v2 Parameters 802 803<table> 804<tr> 805<th>Command</th><th>Response</th> 806</tr> 807<tr> 808<td valign="top"> 809 810| Parameter | Unit | Size | M | I | D | 811| --------- | ----- | ---- | --- | --- | --- | 812| Flags | Field | 1 | 0 | 0 | y | 813 814</td> 815<td valign="top"> 816 817| Parameter | Unit | Size | M | I | D | 818| --------- | ---- | ---- | --- | --- | --- | 819 820</td> 821</tr> 822</table> 823 824### v3 Parameters 825 826<table> 827<tr> 828<th>Command</th><th>Response</th> 829</tr> 830<tr> 831<td valign="top"> 832 833| Parameter | Unit | Size | M | I | D | 834| --------- | ----- | ---- | --- | --- | --- | 835| Flags | Field | 1 | 0 | 0 | y | 836 837</td> 838<td valign="top"> 839 840| Parameter | Unit | Size | M | I | D | 841| --------- | ---- | ---- | --- | --- | --- | 842 843</td> 844</tr> 845</table> 846 847### Description 848 849Closes the active window. Any further access to the LPC bus address specified to 850address the previously active window will have undefined effects. If the active 851window is a write window then the BMC must perform an implicit flush. 852 853The Flags argument allows the host to provide some hints to the BMC. Defined 854values are: 855 856``` 8570x01 - Short Lifetime: 858 The window is unlikely to be accessed anytime again in the near future. 859 The effect of this will depend on BMC implementation. In the event that 860 the BMC performs some caching the BMC daemon could mark data contained 861 in a window closed with this flag as first to be evicted from the cache. 862``` 863 864## `CREATE_WRITE_WINDOW` Command 865 866| v1 | v2 | v3 | M | I | D | 867| --- | --- | --- | --- | --- | ----------------- | 868| ✓ | ✓ | ✓ | 6 | 6 | CreateWriteWindow | 869 870### v1 Parameters 871 872<table> 873<tr> 874<th>Command</th><th>Response</th> 875</tr> 876<tr> 877<td valign="top"> 878 879| Parameter | Unit | Size | M | I | D | 880| ------------ | ------ | ---- | --- | --- | --- | 881| Flash Offset | Blocks | 2 | 0 | 0 | q | 882 883</td> 884<td valign="top"> 885 886| Parameter | Unit | Size | M | I | D | 887| ------------- | ------ | ---- | --- | --- | --- | 888| LPC FW Offset | Blocks | 2 | 0 | 0 | q | 889 890</td> 891</tr> 892</table> 893 894### v2 Parameters 895 896<table> 897<tr> 898<th>Command</th><th>Response</th> 899</tr> 900<tr> 901<td valign="top"> 902 903| Parameter | Unit | Size | M | I | D | 904| ------------- | ------ | ---- | --- | --- | --- | 905| Flash Address | Blocks | 2 | 0 | 0 | q | 906| Length | Blocks | 2 | 2 | 2 | q | 907 908</td> 909<td valign="top"> 910 911| Parameter | Unit | Size | M | I | D | 912| -------------- | ------ | ---- | --- | --- | --- | 913| LPC FW Address | Blocks | 2 | 0 | 0 | q | 914| Length | Blocks | 2 | 2 | 2 | q | 915| Flash Address | blocks | 2 | 4 | 4 | q | 916 917</td> 918</tr> 919</table> 920 921### v3 Parameters 922 923<table> 924<tr> 925<th>Command</th><th>Response</th> 926</tr> 927<tr> 928<td valign="top"> 929 930| Parameter | Unit | Size | M | I | D | 931| ------------- | ------ | ---- | --- | --- | --- | 932| Flash Address | Blocks | 2 | 0 | 0 | q | 933| Length | Blocks | 2 | 2 | 2 | q | 934| Device ID | Index | 1 | 4 | 4 | y | 935 936</td> 937<td valign="top"> 938 939| Parameter | Unit | Size | M | I | D | 940| -------------- | ------ | ---- | --- | --- | --- | 941| LPC FW Address | Blocks | 2 | 0 | 0 | q | 942| Length | Blocks | 2 | 2 | 2 | q | 943| Flash Address | blocks | 2 | 4 | 4 | q | 944 945</td> 946</tr> 947</table> 948 949### Description 950 951The flash offset which the host requests access to is always taken from the 952start of flash - that is it is an absolute offset into flash. 953 954LPC bus address is always given from the start of the LPC address space - that 955is it is an absolute address. 956 957The requested access size is only a hint. The response indicates the actual size 958of the window. The BMC may want to use the requested size to pre-load the 959remainder of the request. The host must not access past the end of the active 960window. 961 962The flash offset mapped by the window is an absolute flash offset and must be 963less than or equal to the flash offset requested by the host. It is the 964responsibility of the host to use this information to access any offset which is 965required. 966 967The requested window size may be zero. In this case the BMC is free to create 968any sized window but it must contain at least the first block of data requested 969by the host. A large window is of course preferred and should correspond to the 970default size returned in the `GET_INFO` command. 971 972If this command returns successfully then the created window is the active 973window. If it fails then there is no active window. 974 975## `MARK_DIRTY` Command 976 977| v1 | v2 | v3 | M | I | D | 978| --- | --- | --- | --- | --- | --------- | 979| ✓ | ✓ | ✓ | 7 | 7 | MarkDirty | 980 981### v1 Parameters 982 983<table> 984<tr> 985<th>Command</th><th>Response</th> 986</tr> 987<tr> 988<td valign="top"> 989 990| Parameter | Unit | Size | M | I | D | 991| ------------ | ------ | ---- | --- | --- | --- | 992| Flash Offset | Blocks | 2 | 0 | 0 | q | 993| Length | Bytes | 4 | 2 | 2 | u | 994 995</td> 996<td valign="top"> 997 998| Parameter | Unit | Size | M | I | D | 999| --------- | ---- | ---- | --- | --- | --- | 1000 1001</td> 1002</tr> 1003</table> 1004 1005### v2 Parameters 1006 1007<table> 1008<tr> 1009<th>Command</th><th>Response</th> 1010</tr> 1011<tr> 1012<td valign="top"> 1013 1014| Parameter | Unit | Size | M | I | D | 1015| ------------- | ------ | ---- | --- | --- | --- | 1016| Window Offset | Blocks | 2 | 0 | 0 | q | 1017| Length | Blocks | 2 | 2 | 2 | q | 1018 1019</td> 1020<td valign="top"> 1021 1022| Parameter | Unit | Size | M | I | D | 1023| --------- | ---- | ---- | --- | --- | --- | 1024 1025</td> 1026</tr> 1027</table> 1028 1029### v3 Parameters 1030 1031<table> 1032<tr> 1033<th>Command</th><th>Response</th> 1034</tr> 1035<tr> 1036<td valign="top"> 1037 1038| Parameter | Unit | Size | M | I | D | 1039| ------------- | ------ | ---- | --- | --- | --- | 1040| Window Offset | Blocks | 2 | 0 | 0 | q | 1041| Length | Blocks | 2 | 2 | 2 | q | 1042| Flags | Field | 1 | 4 | 4 | y | 1043 1044</td> 1045<td valign="top"> 1046 1047| Parameter | Unit | Size | M | I | D | 1048| --------- | ---- | ---- | --- | --- | --- | 1049 1050</td> 1051</tr> 1052</table> 1053 1054### Description 1055 1056The BMC has no method for intercepting writes that occur over the LPC bus. The 1057host must explicitly notify the daemon of where and when a write has occurred so 1058it can be flushed to backing storage. 1059 1060Offsets are given as an absolute (either into flash (V1) or the active window 1061(V2)) and a zero offset refers to the first block. If the offset + number 1062exceeds the size of the active window then the command must not succeed. 1063 1064The host can give a hint to the daemon that is doesn't have to erase a flash 1065area before writing to it by setting bit zero of the Flags parameter. This means 1066that the daemon will blindly perform a write to that area and will not try to 1067erase it before hand. This can be used if the host knows that a large area has 1068already been erased for example but then wants to perform many small writes. 1069 1070## `FLUSH` Command 1071 1072| v1 | v2 | v3 | M | I | D | 1073| --- | --- | --- | --- | --- | ----- | 1074| ✓ | ✓ | ✓ | 8 | 8 | Flush | 1075 1076### v1 Parameters 1077 1078<table> 1079<tr> 1080<th>Command</th><th>Response</th> 1081</tr> 1082<tr> 1083<td valign="top"> 1084 1085| Parameter | Unit | Size | M | I | D | 1086| ------------ | ------ | ---- | --- | --- | --- | 1087| Flash Offset | Blocks | 2 | 0 | 0 | q | 1088| Length | Bytes | 4 | 2 | 2 | u | 1089 1090</td> 1091<td valign="top"> 1092 1093| Parameter | Unit | Size | M | I | D | 1094| --------- | ---- | ---- | --- | --- | --- | 1095 1096</td> 1097</tr> 1098</table> 1099 1100### v2 Parameters 1101 1102<table> 1103<tr> 1104<th>Command</th><th>Response</th> 1105</tr> 1106<tr> 1107<td valign="top"> 1108 1109| Parameter | Unit | Size | M | I | D | 1110| --------- | ---- | ---- | --- | --- | --- | 1111 1112</td> 1113<td valign="top"> 1114 1115| Parameter | Unit | Size | M | I | D | 1116| --------- | ---- | ---- | --- | --- | --- | 1117 1118</td> 1119</tr> 1120</table> 1121 1122### v3 Parameters 1123 1124<table> 1125<tr> 1126<th>Command</th><th>Response</th> 1127</tr> 1128<tr> 1129<td valign="top"> 1130 1131| Parameter | Unit | Size | M | I | D | 1132| --------- | ---- | ---- | --- | --- | --- | 1133 1134</td> 1135<td valign="top"> 1136 1137| Parameter | Unit | Size | M | I | D | 1138| --------- | ---- | ---- | --- | --- | --- | 1139 1140</td> 1141</tr> 1142</table> 1143 1144### Description 1145 1146Flushes any dirty/erased blocks in the active window to the backing storage. 1147 1148In V1 this can also be used to mark parts of the flash dirty and flush in a 1149single command. In V2 the explicit mark dirty command must be used before a call 1150to flush since there are no longer any arguments. If the offset + length exceeds 1151the size of the active window then the command must not succeed. 1152 1153## `ACK` Command 1154 1155| v1 | v2 | v3 | M | I | D | 1156| --- | --- | --- | --- | --- | --- | 1157| ✓ | ✓ | ✓ | 9 | 9 | Ack | 1158 1159### v1 Parameters 1160 1161<table> 1162<tr> 1163<th>Command</th><th>Response</th> 1164</tr> 1165<tr> 1166<td valign="top"> 1167 1168| Parameter | Unit | Size | M | I | D | 1169| --------- | ----- | ---- | --- | --- | --- | 1170| Ack Mask | Field | 1 | 0 | 0 | y | 1171 1172</td> 1173<td valign="top"> 1174 1175| Parameter | Unit | Size | M | I | D | 1176| --------- | ---- | ---- | --- | --- | --- | 1177 1178</td> 1179</tr> 1180</table> 1181 1182### v2 Parameters 1183 1184<table> 1185<tr> 1186<th>Command</th><th>Response</th> 1187</tr> 1188<tr> 1189<td valign="top"> 1190 1191| Parameter | Unit | Size | M | I | D | 1192| --------- | ----- | ---- | --- | --- | --- | 1193| Ack Mask | Field | 1 | 0 | 0 | y | 1194 1195</td> 1196<td valign="top"> 1197 1198| Parameter | Unit | Size | M | I | D | 1199| --------- | ---- | ---- | --- | --- | --- | 1200 1201</td> 1202</tr> 1203</table> 1204 1205### v3 Parameters 1206 1207<table> 1208<tr> 1209<th>Command</th><th>Response</th> 1210</tr> 1211<tr> 1212<td valign="top"> 1213 1214| Parameter | Unit | Size | M | I | D | 1215| --------- | ----- | ---- | --- | --- | --- | 1216| Ack Mask | Field | 1 | 0 | 0 | y | 1217 1218</td> 1219<td valign="top"> 1220 1221| Parameter | Unit | Size | M | I | D | 1222| --------- | ---- | ---- | --- | --- | --- | 1223 1224</td> 1225</tr> 1226</table> 1227 1228### Description 1229 1230The host should use this command to acknowledge BMC events propagated to the 1231host. 1232 1233## `ERASE` Command 1234 1235| v1 | v2 | v3 | M | I | D | 1236| --- | --- | --- | --- | --- | ----- | 1237| | ✓ | ✓ | 10 | 10 | Erase | 1238 1239### v2 Parameters 1240 1241<table> 1242<tr> 1243<th>Command</th><th>Response</th> 1244</tr> 1245<tr> 1246<td valign="top"> 1247 1248| Parameter | Unit | Size | M | I | D | 1249| ------------- | ------ | ---- | --- | --- | --- | 1250| Window Offset | Blocks | 2 | 0 | 0 | q | 1251| Length | Blocks | 2 | 2 | 2 | q | 1252 1253</td> 1254<td valign="top"> 1255 1256| Parameter | Unit | Size | M | I | D | 1257| --------- | ---- | ---- | --- | --- | --- | 1258 1259</td> 1260</tr> 1261</table> 1262 1263### v3 Parameters 1264 1265<table> 1266<tr> 1267<th>Command</th><th>Response</th> 1268</tr> 1269<tr> 1270<td valign="top"> 1271 1272| Parameter | Unit | Size | M | I | D | 1273| ------------- | ------ | ---- | --- | --- | --- | 1274| Window Offset | Blocks | 2 | 0 | 0 | q | 1275| Length | Blocks | 2 | 2 | 2 | q | 1276 1277</td> 1278<td valign="top"> 1279 1280| Parameter | Unit | Size | M | I | D | 1281| --------- | ---- | ---- | --- | --- | --- | 1282 1283</td> 1284</tr> 1285</table> 1286 1287### Description 1288 1289This command allows the host to erase a large area without the need to 1290individually write 0xFF repetitively. 1291 1292Offset is the offset within the active window to start erasing from (zero refers 1293to the first block of the active window) and number is the number of blocks of 1294the active window to erase starting at offset. If the offset + number exceeds 1295the size of the active window then the command must not succeed. 1296 1297## `GET_FLASH_NAME` Command 1298 1299| v1 | v2 | v3 | M | I | D | 1300| --- | --- | --- | --- | --- | ------------ | 1301| | | ✓ | 11 | 11 | GetFlashName | 1302 1303### v3 Parameters 1304 1305<table> 1306<tr> 1307<th>Command</th><th>Response</th> 1308</tr> 1309<tr> 1310<td valign="top"> 1311 1312| Parameter | Unit | Size | M | I | D | 1313| --------- | ----- | ---- | --- | --- | --- | 1314| Device ID | Index | 1 | 0 | 0 | y | 1315 1316</td> 1317<td valign="top"> 1318 1319| Parameter | Unit | Size | M | I | D | 1320| ----------- | ------ | ---- | --- | --- | --- | 1321| Name length | Bytes | 1 | 0 | 0 | - | 1322| Name | String | 10 | 1 | 1 | s | 1323 1324</td> 1325</tr> 1326</table> 1327 1328### Description 1329 1330Describes a flash with some kind of identifier useful to the host system. 1331 1332The length in the response is the number of response arguments as part of the 1333flash name field which the host should expect to have been populated. 1334 1335Note that DBus encodes the string length in its string type, so the explicit 1336length is omitted from the DBus message. 1337 1338## `LOCK` Command 1339 1340| v1 | v2 | v3 | M | I | D | 1341| --- | --- | --- | --- | --- | ---- | 1342| | | ✓ | 12 | 12 | Lock | 1343 1344### v3 Parameters 1345 1346<table> 1347<tr> 1348<th>Command</th><th>Response</th> 1349</tr> 1350<tr> 1351<td valign="top"> 1352 1353| Parameter | Unit | Size | M | I | D | 1354| ------------ | ------ | ---- | --- | --- | --- | 1355| Flash Offset | Blocks | 2 | 0 | 0 | q | 1356| Length | Blocks | 2 | 2 | 2 | q | 1357| Device ID | Index | 1 | 4 | 4 | y | 1358 1359</td> 1360<td valign="top"> 1361 1362| Parameter | Unit | Size | M | I | D | 1363| --------- | ---- | ---- | --- | --- | --- | 1364 1365</td> 1366</tr> 1367</table> 1368 1369### Description 1370 1371Lock an area of flash so that the host can't mark it dirty or erased. If the 1372requested area is within the current window and that area is currently marked 1373dirty or erased then this command must fail. 1374 1375# Event Definitions 1376 1377The M, I, and D columns represent the Mailbox, IPMI and DBus transports 1378respectively. The values in the M, I or D columns represent the events' bit 1379index in the status byte, or in the case of the DBus transport the name of the 1380relevant property. 1381 1382For the DBus interface, properties are used for all event types regardless of 1383whether they should be acknowledged or not as part of the protocol. This ensures 1384that state changes can be published atomically. 1385 1386## `PROTOCOL_RESET` Event 1387 1388| v1 | v2 | v3 | M | I | D | 1389| --- | --- | --- | --- | --- | ------------- | 1390| ✓ | ✓ | ✓ | 0 | 0 | ProtocolReset | 1391 1392### Description 1393 1394Used to inform the host that a protocol reset has occurred, likely due to 1395restarting the daemon. The host must perform protocol version negotiation again 1396and must assume it has no active window. The host must also assume that any 1397in-flight commands have failed. 1398 1399## `WINDOW_RESET` Event 1400 1401| v1 | v2 | v3 | M | I | D | 1402| --- | --- | --- | --- | --- | ----------- | 1403| | ✓ | ✓ | 1 | 1 | WindowReset | 1404 1405### Description 1406 1407The host must assume that its active window has been closed and that it no 1408longer has an active window. The host is not required to perform protocol 1409version negotiation again. The host must assume that any in-flight commands have 1410failed. 1411 1412## `FLASH_CONTROL_LOST` Event 1413 1414| v1 | v2 | v3 | M | I | D | 1415| --- | --- | --- | --- | --- | ---------------- | 1416| | ✓ | ✓ | 6 | 6 | FlashControlLost | 1417 1418### Description 1419 1420The BMC daemon has been suspended and thus no longer controls access to the 1421flash (most likely because some other process on the BMC required direct access 1422to the flash and has suspended the BMC daemon to preclude concurrent access). 1423 1424The BMC daemon must clear this bit itself when it regains control of the flash 1425(the host isn't able to clear it through an acknowledge command). 1426 1427The host must not assume that the contents of the active window correctly 1428reflect the contents of flash while this bit is set. 1429 1430## `DAEMON_READY` Event 1431 1432| v1 | v2 | v3 | M | I | D | 1433| --- | --- | --- | --- | --- | ----------- | 1434| | ✓ | ✓ | 7 | 7 | DaemonReady | 1435 1436### Description 1437 1438Used to inform the host that the BMC daemon is ready to accept command requests. 1439The host isn't able to clear this bit through an acknowledge command, the BMC 1440daemon must clear it before it terminates (assuming it didn't terminate 1441unexpectedly). 1442 1443The host should not expect a response while this bit is not set. 1444 1445Note that this bit being set is not a guarantee that the BMC daemon will respond 1446as it or the BMC may have crashed without clearing it. 1447