README.md
1# phosphor-post-code-manager
2
3This phosphor-post-code-manager repository provides an infrastructure to persist
4the POST codes in BMC filesystem & it also owns the systemd services that are
5responsible for exposing the BIOS Post Codes to rest of the world via redfish.
6
7## To Build
8
9To build phosphor-post-code-manager package , do the following steps:
10
11```bash
12meson <build directory>
13ninja -C <build directory>
14```
15
16## Hosted Services
17
18This repository ships `xyz.openbmc_project.State.Boot.PostCode.service` systemd
19service along with its
20[template version](https://github.com/openbmc/docs/blob/master/designs/multi-host-postcode.md)
21and a tiny binary that exposes the necessary
22[dbus interfaces & methods](https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/State/Boot/PostCode.interface.yaml)
23to extract the POST codes per boot cycle.
24
25## Architecture
26
27This repository is tightly coupled with
28[phosphor-host-postd](https://github.com/openbmc/phosphor-host-postd) OpenBMC
29repository which is responsible for emitting the dbus signals for every new POST
30Code.
31
32phosphor-post-code-manager is architected to look for the property changed
33signals which are being emitted from the service that hosts
34[Value](https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/State/Boot/Raw.interface.yaml)
35property on `xyz.openbmc_project.State.Boot.Raw` interface & archive them per
36boot on the filesystem, so that those can be exposed over
37[redfish](https://github.com/openbmc/docs/blob/master/designs/redfish-postcodes.md)
38
39## Special Post code handling/eventing
40
41Platforms can provide custom configuration to allow for special handling of
42specific postcodes. Special handling include starting user configured systemd
43unit files and/or creating a structured event as defined by the user. The JSON
44configuration file can be passed in using the `--config PATH` or `-c PATH`
45options.
46
47Configuration format:
48
49```json
50[
51 {
52 "name": "SpecialPostCode",
53 "description": "Perform special handling of 0x12",
54 "primary": "0x12",
55 "secondary": "0x1234",
56 "targets": ["my_special.service"]
57 },
58 {
59 "name": "PowerFailure",
60 "description": "Detect a power rail fault",
61 "primary": "0x12",
62 "targets": ["power_failure.service"],
63 "event": {
64 "name": "xyz.openbmc_project.State.Power.PowerRailFault",
65 "arguments": {
66 "POWER_RAIL": "MyDevice",
67 "FAILURE_DATA": ""
68 }
69 }
70 }
71]
72```
73
74Each entry in the array describes a special handler for a specific post code.
75
76- `primary` - [required] The primary post code to match as a hex string.
77- `secondary` - [optional] The secondary post code (hex string) to match. If not
78 present, the matches all post codes which match just the primary
79- `targets` - [optional] List of systemd targets to start when the matching post
80 code is received.
81- `event` - [optional] The descriptor of the event to create with
82 phosphor-logging.
83 - `event::name` - Name of the event log. See `log-create --list` for a list of
84 possible events which can be created
85 - `event::arguments` - The named argument list which will be used to create
86 the event.
87