hiomapd/Documentation/mboxd.md

5 Licensed under the Apache License, Version 2.0 (the "License"); you may not use
6 this file except in compliance with the License. You may obtain a copy of the
12 under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
13 CONDITIONS OF ANY KIND, either express or implied. See the License for the
14 specific language governing permissions and limitations under the License.
18 This document describes the reference mailbox daemon contained in this
23 The main mailbox daemon is implemented in mboxd.c. This file uses helper
24 functions from the various mboxd\_\*.c files.
27 dbus.c -    Contains the handlers for the D-Bus commands which the daemon can
29 flash.c -   Contains the functions for performing flash access including
31 lpc.c -     Contains the functions for controlling the LPC bus mapping
32                   including pointing the bus so it maps flash and memory.
33 transport_mbox.c -     Contains the handlers for the mbox commands which the daemon
35 windows.c - Contains the functions for managing the window cache.
40 The daemon is a state machine with 5 valid states:
43 UNINITIALISED -         The daemon is still in the initialisation phase and
45 ACTIVE_MAPS_FLASH -     The daemon is polling for incoming commands, is not
46                         currently suspended and the LPC bus maps the flash
48 SUSPEND_MAPS_FLASH -    The daemon is polling for incoming commands, is
49                         currently suspended and the LPC bus maps the flash
51 ACTIVE_MAPS_MEM -       The daemon is polling for incoming commands, is not
52                         currently suspended and the LPC bus maps the reserved
54 SUSPEND_MAPS_MEM -      The daemon is polling for incoming commands, is
55                         currently suspended and the LPC bus maps the reserved
59 As described in the protocol, the daemon can be suspended to allow the BMC to
60 access flash without the daemon interfering. The daemon will still respond to
61 commands while suspended but won't allow the host to, or itself, access the
67 UNINITIALISED -> ACTIVE_MAPS_FLASH -      Uninitiated: Occurs when the daemon is
79                                           don't let the host modify flash
80                                           while the daemon is suspended.
85 While the protocol describes that there is only one active window at a time, the
86 daemon keeps a cache of previously accessed windows to avoid the need to reload
87 them from flash should the host access them again in the future.
89 The reserved memory region is divided among a number of windows which make up
90 the window cache. When the host requests a flash offset the cache is searched
91 for one which contains that offset. If one is found we simply point the host to
92 it at the correct LPC offset for that windows location and the requested flash
95 If there is no window in the cache which contains the requested flash offset
96 then we have to find one to load with the requested flash contents. If there are
98 evict using a least recently used (LRU) scheme. The flash is then copied into
99 this window and the host pointed at its location on the LPC bus.
101 When ever the flash is changed we have to invalidate all windows in the window
102 cache as their contents may no longer accurately reflect those of the flash.
108 The daemon is invoked on the command line with a few parameters:
115 --flash *       - The size of the PNOR image on the flash device
116 --window-size # - The size to make each window in the cache
117 --window-num #  - The number of windows to have in the cache
118 --verbose ~     - Increase the verbosity with which the daemon runs
119 --sys-log ~     - Use the system log rather than outputting to the console
122 If any of the required parameters are missing or invalid an error will be
123 printed and the daemon will terminate. If window-size and window-num aren't
124 specified then the default is to have a single window which spans the entire
129 After the command line has been parsed the daemon will initalise its various
130 interfaces. If any of these initialisations fail it will print an error and the
133 After initilisation, the daemon points the LPC mapping to the actual flash
134 device, sets the BMC_READY BMC event and starts polling.
138 The daemon sits in a poll loop waiting for an event to happen on one or more of
139 the mbox, D-Bus or signal file descriptors.
143 When an event occurs on the mbox file descriptor the mbox request is read from
144 the mbox registers and processed.
146 The command is validated and then the appropriate handler called. The response
147 is then written back to the mbox registers to indicate the outcome of the
148 command and an interrupt is sent to the host.
152 When an event occurs on the D-Bus file descriptor the D-Bus request is read from
153 the D-Bus interface and processed.
155 The command is validated and then the appropriate handler called. The response
156 is then written back to the D-Bus interface to indicate the outcome of the
161 The daemon blocks SIGINTs, SIGTERMs, and SIGHUPs and instead polls for them on a
164 When an event occurs on this file descriptor the signal received is determined
168 SIGINT -  Terminate the daemon
169 SIGTERM - Terminate the daemon
170 SIGHUP -  Clear the window cache and point the LPC bus mapping back to
176 The daemon can be terminated for multiple reasons; invalid command line, unable
177 to initialise, received SIGINT or SIGTERM, or because it received the kill D-Bus
180 On termination, the daemon clears the window cache and notifies the host that
181 the active window has been closed, points the LPC bus mapping back to flash,
182 clears the BMC_READY BMC event bit and frees all of its allocated resources.