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