1Copyright 2017,2018 IBM 2 3Licensed under the Apache License, Version 2.0 (the "License"); you may not use 4this file except in compliance with the License. You may obtain a copy of the 5License at 6 7http://www.apache.org/licenses/LICENSE-2.0 8 9Unless required by applicable law or agreed to in writing, software distributed 10under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR 11CONDITIONS OF ANY KIND, either express or implied. See the License for the 12specific language governing permissions and limitations under the License. 13 14## Intro 15 16This document describes the reference mailbox daemon contained in this 17repository. 18 19## Files 20 21The main mailbox daemon is implemented in mboxd.c. This file uses helper 22functions from the various mboxd\_\*.c files. 23 24``` 25dbus.c - Contains the handlers for the D-Bus commands which the daemon can 26 receive. 27flash.c - Contains the functions for performing flash access including 28 read, write and erase. 29lpc.c - Contains the functions for controlling the LPC bus mapping 30 including pointing the bus so it maps flash and memory. 31transport_mbox.c - Contains the handlers for the mbox commands which the daemon 32 can receive. 33windows.c - Contains the functions for managing the window cache. 34``` 35 36## Daemon State 37 38The daemon is a state machine with 5 valid states: 39 40``` 41UNINITIALISED - The daemon is still in the initialisation phase and 42 will not respond 43ACTIVE_MAPS_FLASH - The daemon is polling for incoming commands, is not 44 currently suspended and the LPC bus maps the flash 45 device. 46SUSPEND_MAPS_FLASH - The daemon is polling for incoming commands, is 47 currently suspended and the LPC bus maps the flash 48 device. 49ACTIVE_MAPS_MEM - The daemon is polling for incoming commands, is not 50 currently suspended and the LPC bus maps the reserved 51 memory region. 52SUSPEND_MAPS_MEM - The daemon is polling for incoming commands, is 53 currently suspended and the LPC bus maps the reserved 54 memory region. 55``` 56 57As described in the protocol, the daemon can be suspended to allow the BMC to 58access flash without the daemon interfering. The daemon will still respond to 59commands while suspended but won't allow the host to, or itself, access the 60flash. 61 62### State Transitions 63 64``` 65UNINITIALISED -> ACTIVE_MAPS_FLASH - Uninitiated: Occurs when the daemon is 66 finished initialising. 67ACTIVE_MAPS_FLASH -> SUSPEND_MAPS_FLASH - Suspend command received over 68 D-Bus 69SUSPEND_MAPS_FLASH -> ACTIVE_MAPS_FLASH - Resume command received over 70 D-Bus 71ACTIVE_MAPS_MEM -> SUSPEND_MAPS_MEM - Suspend command received over D-Bus 72SUSPEND_MAPS_MEM -> ACTIVE_MAPS_MEM - Resume command received over D-Bus 73ACTIVE_MAPS_FLASH -> ACTIVE_MAPS_MEM - GET_MBOX_INFO command received 74SUSPEND_MAPS_FLASH -> SUSPEND_MAPS_MEM - GET_MBOX_INFO command received 75ACTIVE_MAPS_MEM -> ACTIVE_MAPS_FLASH - Reset D-Bus or mbox command received 76SUSPEND_MAPS_MEM -> SUSPEND_MAPS_FLASH - Transition not allowed, we 77 don't let the host modify flash 78 while the daemon is suspended. 79``` 80 81## Window Cache 82 83While the protocol describes that there is only one active window at a time, the 84daemon keeps a cache of previously accessed windows to avoid the need to reload 85them from flash should the host access them again in the future. 86 87The reserved memory region is divided among a number of windows which make up 88the window cache. When the host requests a flash offset the cache is searched 89for one which contains that offset. If one is found we simply point the host to 90it at the correct LPC offset for that windows location and the requested flash 91offset. 92 93If there is no window in the cache which contains the requested flash offset 94then we have to find one to load with the requested flash contents. If there are 95any windows which are empty then we choose those, otherwise, we choose one to 96evict using a least recently used (LRU) scheme. The flash is then copied into 97this window and the host pointed at its location on the LPC bus. 98 99When ever the flash is changed we have to invalidate all windows in the window 100cache as their contents may no longer accurately reflect those of the flash. 101 102## Daemon Operation 103 104### Invocation 105 106The daemon is invoked on the command line with a few parameters: 107 108``` 109(*) - required 110(#) - optional but recommended 111(~) - optional 112 113--flash * - The size of the PNOR image on the flash device 114--window-size # - The size to make each window in the cache 115--window-num # - The number of windows to have in the cache 116--verbose ~ - Increase the verbosity with which the daemon runs 117--sys-log ~ - Use the system log rather than outputting to the console 118``` 119 120If any of the required parameters are missing or invalid an error will be 121printed and the daemon will terminate. If window-size and window-num aren't 122specified then the default is to have a single window which spans the entire 123reserved memory region. 124 125### Initialisation 126 127After the command line has been parsed the daemon will initalise its various 128interfaces. If any of these initialisations fail it will print an error and the 129daemon will terminate. 130 131After initilisation, the daemon points the LPC mapping to the actual flash 132device, sets the BMC_READY BMC event and starts polling. 133 134### Polling 135 136The daemon sits in a poll loop waiting for an event to happen on one or more of 137the mbox, D-Bus or signal file descriptors. 138 139#### Handling MBOX Commands 140 141When an event occurs on the mbox file descriptor the mbox request is read from 142the mbox registers and processed. 143 144The command is validated and then the appropriate handler called. The response 145is then written back to the mbox registers to indicate the outcome of the 146command and an interrupt is sent to the host. 147 148#### Handling D-Bus Commands 149 150When an event occurs on the D-Bus file descriptor the D-Bus request is read from 151the D-Bus interface and processed. 152 153The command is validated and then the appropriate handler called. The response 154is then written back to the D-Bus interface to indicate the outcome of the 155command. 156 157#### Handling Signals 158 159The daemon blocks SIGINTs, SIGTERMs, and SIGHUPs and instead polls for them on a 160signal file descriptor. 161 162When an event occurs on this file descriptor the signal received is determined 163and processed as follows: 164 165``` 166SIGINT - Terminate the daemon 167SIGTERM - Terminate the daemon 168SIGHUP - Clear the window cache and point the LPC bus mapping back to 169 flash 170``` 171 172### Termination 173 174The daemon can be terminated for multiple reasons; invalid command line, unable 175to initialise, received SIGINT or SIGTERM, or because it received the kill D-Bus 176command. 177 178On termination, the daemon clears the window cache and notifies the host that 179the active window has been closed, points the LPC bus mapping back to flash, 180clears the BMC_READY BMC event bit and frees all of its allocated resources. 181