Add documentation for generator extensions.
Change-Id: I889021a26e89e7d60a0f44cbe7665e359dbd7307
diff --git a/docs/GeneratorExtensions.md b/docs/GeneratorExtensions.md
new file mode 100644
index 0000000..0664b8f
--- /dev/null
+++ b/docs/GeneratorExtensions.md
@@ -0,0 +1,69 @@
+# Extending `cper-generator` With OEM Sections
+Much like `cper-parse`, `cper-generator` supports the addition of arbitrary OEM sections as extensions. This document details how an OEM section generator could be added to the `cper-generate` project from a stock version.
+
+## Creating a Section Generator
+The first step is to create the generator itself. To do this, you should create a function predefinition inside `sections/gen-section.h` as shown below, and then create a C file within `sections/` to house your generation code. For the sake of example, we will create a generator for a fake OEM section "myVendorSection".
+
+*sections/gen-section.h*
+```c
+//Section generator function predefinitions.
+...
+size_t generate_section_cxl_protocol(void** location);
+size_t generate_section_cxl_component(void** location);
+size_t generate_section_myvendor(void** location);
+```
+
+*sections/gen-myvendor.c*
+```c
+/**
+ * Functions for generating pseudo-random MyVendor error sections.
+ *
+ * Author: author@example.com
+ **/
+
+#include <stdlib.h>
+
+size_t generate_section_myvendor(void** location)
+{
+ //...
+}
+```
+
+## Adding a Section GUID
+To identify our section for parsing, we must define a section GUID within `edk/Cper.h` and `edk/Cper.c` respectively.
+This is the same step taken when adding an OEM extension to `cper-parse`, so if you've already done this, you do not need to repeat it again.
+
+*edk/Cper.h*:
+```c
+...
+extern EFI_GUID gEfiCxlVirtualSwitchErrorSectionGuid;
+extern EFI_GUID gEfiCxlMldPortErrorSectionGuid;
+extern EFI_GUID gMyVendorSectionGuid;
+```
+
+*edk/Cper.c*:
+```c
+...
+EFI_GUID gEfiCxlVirtualSwitchErrorSectionGuid = { 0x40d26425, 0x3396, 0x4c4d, { 0xa5, 0xda, 0x3d, 0x47, 0x26, 0x3a, 0xf4, 0x25 }};
+EFI_GUID gEfiCxlMldPortErrorSectionGuid = { 0x8dc44363, 0x0c96, 0x4710, { 0xb7, 0xbf, 0x04, 0xbb, 0x99, 0x53, 0x4c, 0x3f }};
+EFI_GUID gMyVendorSectionGuid = { 0x40d26425, 0x3396, 0x4c4d, { 0xa5, 0xda, 0x3d, 0x47, 0x26, 0x3a, 0xf4, 0x25 }};
+```
+
+## Adding a Generator Definition
+Now that a GUID and generation function are created for our section, we can finally add it to the generator definitions for `cper-generate`. To do this, edit `sections/gen-section.c` and add your generator definition to the `generator_definitions` array. The second string parameter here is the shortcode used for generating your section, and must contain **no spaces** (this is also asserted via. GTest).
+```c
+/**
+ * Describes available section generators to the CPER generator.
+ *
+ * Author: Lawrence.Tang@arm.com
+ **/
+#include "gen-section.h"
+
+CPER_GENERATOR_DEFINITION generator_definitions[] = {
+ ...
+ {&gEfiCxlVirtualSwitchErrorSectionGuid, "cxlcomponent-vswitch", generate_section_cxl_component},
+ {&gEfiCxlMldPortErrorSectionGuid, "cxlcomponent-mld", generate_section_cxl_component},
+ {&gMyVendorSectionGuid, "myvendor", generate_section_myvendor},
+};
+```
+Once this is complete, after a `cmake .` and `make`, your section should be available to generate through `cper-generate` and `libcper-generate`.
\ No newline at end of file
diff --git a/tests/ir-tests.cpp b/tests/ir-tests.cpp
index 0c9dad8..affa305 100644
--- a/tests/ir-tests.cpp
+++ b/tests/ir-tests.cpp
@@ -4,6 +4,7 @@
* Author: Lawrence.Tang@arm.com
**/
+#include <ctype.h>
#include "gtest/gtest.h"
#include "test-utils.hpp"
extern "C" {
@@ -12,6 +13,7 @@
#include "../json-schema.h"
#include "../generator/cper-generate.h"
#include "../sections/cper-section.h"
+#include "../generator/sections/gen-section.h"
}
/*
@@ -103,10 +105,10 @@
*/
TEST(CompileTimeAssertions, TwoWayConversion)
{
- for (int i=0; i<section_definitions_len; i++)
- {
+ for (int i = 0; i < section_definitions_len; i++) {
//If a conversion one way exists, a conversion the other way must exist.
- std::string err = "If a CPER conversion exists one way, there must be an equivalent method in reverse.";
+ std::string err =
+ "If a CPER conversion exists one way, there must be an equivalent method in reverse.";
if (section_definitions[i].ToCPER != NULL)
ASSERT_NE(section_definitions[i].ToIR, NULL) << err;
if (section_definitions[i].ToIR != NULL)
@@ -114,6 +116,19 @@
}
}
+TEST(CompileTimeAssertions, ShortcodeNoSpaces)
+{
+ for (int i = 0; i < generator_definitions_len; i++) {
+ for (int j = 0;
+ generator_definitions[i].ShortName[j + 1] != '\0'; j++) {
+ ASSERT_FALSE(
+ isspace(generator_definitions[i].ShortName[j]))
+ << "Illegal space character detected in shortcode '"
+ << generator_definitions[i].ShortName << "'.";
+ }
+ }
+}
+
/*
* Single section tests.
*/