README.md
1# CPER JSON Representation & Conversion Library
2
3This repository specifies a structure for representing UEFI CPER records (as
4described in UEFI Specification Appendix N) in a human-readable JSON format, in
5addition to a library which can readily convert back and forth between the
6standard CPER binary format and the specified structured JSON.
7
8## Prerequisites
9
10Before building this library and its associated tools, you must have meson
11(>=1.1.1)
12
13## Building
14
15This project uses Meson (>=1.1.1). To build for native architecture, simply run:
16
17```sh
18meson setup build
19ninja -C build
20```
21
22## Usage
23
24This project comes with several binaries to help you deal with CPER binary and
25CPER-JSON. The first of these is `cper-convert`, which is a command line tool
26that can be found in `build/`. With this, you can convert to and from CPER and
27CPER-JSON through the command line. An example usage scenario is below:
28
29```sh
30cper-convert to-cper samples/cper-json-test-arm.json --out cper.dump
31cper-convert to-json cper.generated.dump
32```
33
34Another tool bundled with this repository is `cper-generate`, found in `build/`.
35This allows you to generate pseudo-random valid CPER records with sections of
36specified types for testing purposes. An example use of the program is below:
37
38```sh
39cper-generate --out cper.generated.dump --sections generic ia32x64
40```
41
42Help for both of these tools can be accessed through using the `--help` flag in
43isolation.
44
45Finally, a static library containing symbols for converting CPER and CPER-JSON
46between an intermediate JSON format can be found generated at
47`lib/libcper-parse.a`. This contains the following useful library symbols:
48
49```sh
50json_object* cper_to_ir(FILE* cper_file);
51void ir_to_cper(json_object* ir, FILE* out);
52```
53
54## Specification
55
56The specification for this project's CPER-JSON format can be found in
57`specification/`, defined in both JSON Schema format and also as a LaTeX
58document. Specification for the CPER binary format can be found in
59[UEFI Specification Appendix N](https://uefi.org/sites/default/files/resources/UEFI_Spec_2_9_2021_03_18.pdf)
60(2021/03/18).
61
62## Usage Examples
63
64This library is utilised in a proof of concept displaying CPER communication
65between a SatMC and OpenBMC board, including a conversion into CPER JSON for
66logging that utilises this library. You can find information on how to reproduce
67the prototype at the
68[scripts repository](https://gitlab.arm.com/server_management/cper-poc-scripts),
69and example usage of the library itself at the
70[pldm](https://gitlab.arm.com/server_management/pldm) repository.
71