1# Extending `cper-generator` With OEM Sections
2
3Much like `cper-parse`, `cper-generator` supports the addition of arbitrary OEM
4sections as extensions. This document details how an OEM section generator could
5be added to the `cper-generate` project from a stock version.
6
7## Creating a Section Generator
8
9The first step is to create the generator itself. To do this, you should create
10a function predefinition inside `sections/gen-section.h` as shown below, and
11then create a C file within `sections/` to house your generation code. For the
12sake of example, we will create a generator for a fake OEM section
13"myVendorSection".
14
15_sections/gen-section.h_
16
17```c
18//Section generator function predefinitions.
19...
20size_t generate_section_cxl_protocol(void** location);
21size_t generate_section_cxl_component(void** location);
22size_t generate_section_myvendor(void** location);
23```
24
25_sections/gen-myvendor.c_
26
27```c
28/**
29 * Functions for generating pseudo-random MyVendor error sections.
30 *
31 * Author: author@example.com
32 **/
33
34#include <stdlib.h>
35
36size_t generate_section_myvendor(void** location)
37{
38    //...
39}
40```
41
42## Adding a Section GUID
43
44To identify our section for parsing, we must define a section GUID within
45`edk/Cper.h` and `edk/Cper.c` respectively. This is the same step taken when
46adding an OEM extension to `cper-parse`, so if you've already done this, you do
47not need to repeat it again.
48
49_edk/Cper.h_:
50
51```c
52...
53extern EFI_GUID   gEfiCxlVirtualSwitchErrorSectionGuid;
54extern EFI_GUID   gEfiCxlMldPortErrorSectionGuid;
55extern EFI_GUID   gMyVendorSectionGuid;
56```
57
58_edk/Cper.c_:
59
60```c
61...
62EFI_GUID gEfiCxlVirtualSwitchErrorSectionGuid = { 0x40d26425, 0x3396, 0x4c4d, { 0xa5, 0xda, 0x3d, 0x47, 0x26, 0x3a, 0xf4, 0x25 }};
63EFI_GUID gEfiCxlMldPortErrorSectionGuid = { 0x8dc44363, 0x0c96, 0x4710, { 0xb7, 0xbf, 0x04, 0xbb, 0x99, 0x53, 0x4c, 0x3f }};
64EFI_GUID gMyVendorSectionGuid = { 0x40d26425, 0x3396, 0x4c4d, { 0xa5, 0xda, 0x3d, 0x47, 0x26, 0x3a, 0xf4, 0x25 }};
65```
66
67## Adding a Generator Definition
68
69Now that a GUID and generation function are created for our section, we can
70finally add it to the generator definitions for `cper-generate`. To do this,
71edit `sections/gen-section.c` and add your generator definition to the
72`generator_definitions` array. The second string parameter here is the shortcode
73used for generating your section, and must contain **no spaces** (this is also
74asserted via. GTest).
75
76```c
77/**
78 * Describes available section generators to the CPER generator.
79 *
80 * Author: Lawrence.Tang@arm.com
81 **/
82#include "gen-section.h"
83
84CPER_GENERATOR_DEFINITION generator_definitions[] = {
85    ...
86    {&gEfiCxlVirtualSwitchErrorSectionGuid, "cxlcomponent-vswitch", generate_section_cxl_component},
87    {&gEfiCxlMldPortErrorSectionGuid, "cxlcomponent-mld", generate_section_cxl_component},
88    {&gMyVendorSectionGuid, "myvendor", generate_section_myvendor},
89};
90```
91
92Once this is complete, after a `cmake .` and `make`, your section should be
93available to generate through `cper-generate` and `libcper-generate`.
94