1# BMC Handler Configuration 2 3The BMC BLOB handler for the flash objects is configured at run-time via a json 4file or multiple json files. The json fields detail every aspect of how the 5handler should behave for a given blob id. 6 7There are three json configurations available by default: 8 9- config-bios.json 10- config-static-bmc-reboot.json 11- config-static-bmc.json 12 13Let's break them down, what they contain and what it means, and then how to 14write your own. It's helpful to start here. 15 16## config-bios.json 17 18This file is generated from configuration and therefore some values can be 19replaced, here we're using the defaults. 20 21```json 22[ 23 { 24 "blob": "/flash/bios", 25 "handler": { 26 "type": "file", 27 "path": "/tmp/bios-image" 28 }, 29 "actions": { 30 "preparation": { 31 "type": "systemd", 32 "unit": "phosphor-ipmi-flash-bios-prepare.target" 33 }, 34 "verification": { 35 "type": "systemd", 36 "unit": "phosphor-ipmi-flash-bios-verify.target" 37 }, 38 "update": { 39 "type": "systemd", 40 "unit": "phosphor-ipmi-flash-bios-update.target" 41 } 42 } 43 } 44] 45``` 46 47Each json file is expected to be an array of flash handler configurations. You 48can define more than one handler inside a json file, or you can have one per 49file. It will make no difference. The file though, must contain an array. 50 51Beyond this, the flash handler configuration is a dictionary or object with 52three fields. 53 54- `blob` 55- `handler` 56- `actions` 57 58### `blob` 59 60The `blob` field expects to hold a string. This string is the blob id that'll be 61presented to the host and registered with the blob manager. It must be unique 62among all blobs on a system and must start with `/flash/`. The uniqueness is not 63presently verified at any stage. If there is another blob id that matches, the 64first one loaded will be the first one hit during any calls from the host. It's 65generally unlikely that there will be a name collision. 66 67### `handler` 68 69The `handler` field expects to hold a dictionary or object with at least one 70field. 71 72- `type` 73 74The `type` field expects a string and will control what other parameters are 75required. The type here refers to the handler for the incoming data associated 76with the flash image contents. The hash data is always done as a file, but the 77image data is configurable via the json. 78 79In the above configuration the `type` is set to `file`. The `file` type handler 80requires one parameter: `path`. The `path` here is the full file system path to 81where to write the bytes received into a file. In this case specifically the 82byte received will be written to `/tmp/bios-image`. 83 84### `actions` 85 86Because `phosphor-ipmi-flash` is a framework for sending data from the host to 87the BMC for updating various firmware, it needs to be told what to do to verify 88the data and cause an update. It additionally provides a mechanism for preparing 89the BMC to receive the data. On a low memory BMC, the preparation step can be 90used to shut down unnecessary services, etc. 91 92The actions are split into three fields: 93 94- `preparation` 95- `verification` 96- `update` 97 98The `preparation`, `verification`, and `update` fields expect a `type` field, 99similarly to the `handler` field. This dictates what other parameters may be 100required. 101 102In this configuration the `preparation` type is `systemd`. The `systemd` type 103expects to receive a `unit`. The `unit` value is expected to be a string that is 104the name of the systemd unit to start. In this case, it'll start 105`phosphor-ipmi-flash-bios-prepare.target`. This can be a single service name, or 106a target. 107 108In this configuration the `verification` type is `systemd`. This will query 109systemd for the status of the verification unit to determine running, success, 110or failure. 111 112In this configuration the `update` type is `systemd`. This is the same object as 113with the `preparation` action. 114 115## config-static-bmc-reboot.json 116 117This file is generated from configuration and therefore some values can be 118replaced, here we're using the defaults. 119 120```json 121[ 122 { 123 "blob": "/flash/image", 124 "handler": { 125 "type": "file", 126 "path": "/run/initramfs/bmc-image" 127 }, 128 "actions": { 129 "preparation": { 130 "type": "systemd", 131 "unit": "phosphor-ipmi-flash-bmc-prepare.target" 132 }, 133 "verification": { 134 "type": "systemd", 135 "unit": "phosphor-ipmi-flash-bmc-verify.target" 136 }, 137 "update": { 138 "type": "reboot" 139 } 140 } 141 } 142] 143``` 144 145Given the bios configuration, we can skip the parts of this configuration that 146are already explained. The new action type is `reboot`. This is a special action 147type that has no parameters. It will simply trigger a reboot via systemd. 148 149## config-static-bmc.json 150 151This file is generated from configuration and therefore some values can be 152replaced, here we're using the defaults. 153 154```json 155[ 156 { 157 "blob": "/flash/image", 158 "handler": { 159 "type": "file", 160 "path": "/run/initramfs/bmc-image" 161 }, 162 "actions": { 163 "preparation": { 164 "type": "systemd", 165 "unit": "phosphor-ipmi-flash-bmc-prepare.target" 166 }, 167 "verification": { 168 "type": "systemd", 169 "unit": "phosphor-ipmi-flash-bmc-verify.target" 170 }, 171 "update": { 172 "type": "systemd", 173 "unit": "phosphor-ipmi-flash-bmc-update.target" 174 } 175 } 176 } 177] 178``` 179 180This configuration is of no significance in its difference. 181 182## Writing your own json Configuration 183 184If you wish to write your own json configuration, you simply create a legal json 185file containing an array of at least one entry. This array will define any 186entries you wish. You can provide multiple BMC update json configurations if you 187wish. There may be parameters you desire to pass to an update process, for 188instance, clearing the whitelisted files. In this case, it's trivial to create 189two targets. The first target performs a normal update, the second starts a 190service that performs the desired other update. You can leverage the 191default-provided configuration files, and also add your own to add additional 192support if desired. 193 194An entry, regardless, must contain a `blob`, a `handler`, and `actions`. 195 196### Handler Types 197 198A handler determines how the bytes from the host are stored. 199 200#### `file` 201 202The `file` handler type writes the bytes to a file path specified by the 203required parameter `path`. 204 205- `path` - full file system path to where to write bytes. 206 207### Action Types 208 209Action types are used to define what to do for a specific requested action, such 210as "verify the blob contents." 211 212#### `skip` 213 214The `skip` type will effectively make that action a no-op and always return 215success. 216 217#### `systemd` 218 219The `systemd` type should be used when you wish to start a systemd service or 220target. For verification and update operations this will track the status of the 221systemd service to determine success or failure. 222 223- `unit` - required - string - the systemd unit to start. 224- `mode` - optional - string - default: replace - the mode for starting the 225 service. 226 227#### `fileSystemdVerify` & `fileSystemdUpdate` 228 229Because one may care about the result of their actions, the `fileSystemdVerify` 230and `fileSystemdUpdate` action type exists. It will start the service and when 231asked for a status, it'll read the contents of a file. Therefore, whatever is 232performing the action will want to update that file. NOTE: Now that the systemd 233type action tracks unit status, that action is now preferred. 234 235- `path` - required - string - the full file system path to where one finds the 236 status. 237- `unit` - required - string - the systemd unit to start 238- `mode` - optional - string - default: replace - the mode for starting the 239 service. 240 241#### `reboot` 242 243The `reboot` type causes a reboot via systemd. If this happens quickly enough, 244you may not receive a response over IPMI that your command succeeded. 245 246### Installing your own json configuration 247 248To install your own configuration(s) you can add your own bbappend file that 249appends to the install task. The json files are installed in 250`${D}${datadir}/phosphor-ipmi-flash/` 251 252## Adding your own handler type 253 254Firstly, welcome! The maintainers of this repository appreciate your 255contribution. A handler is just an implementation of the 256`ImageHandlerInterface`. 257 258Your handler must implement: 259 260- `bool open(const std::string& path)` 261- `void close()` 262- `bool write(std::uint32_t offset, const std::vector<std::uint8_t>& data)` 263- `int getSize()` 264 265The handler is meant to receive the bytes, and write the bytes. 266 267Once the object is defined you can specify a type and parameters here and in the 268`buildjson` module. 269 270## Adding your own action type 271 272Firstly, welcome! The maintainers of this repository appreciate your 273contribution. An action is just an implementation of the 274`TriggerableActionInterface`. 275 276Your action must implement: 277 278- `bool trigger()` 279- `void abort()` 280- `ActionStatus status()` 281 282The abort method is not a guarantee. 283 284Once the object is defined you can specify a type and parameters here and in the 285`buildjson` module. 286