xref: /openbmc/hiomapd/Documentation/protocol.md (revision d5f1d40f2ddf9234099b331e1d90c54ece0ee88b)
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