Add documentation on extending.
Change-Id: I1065519f4bb34885ec6b52a534bf4853f8573fdb
diff --git a/docs/OEMExtensions.md b/docs/OEMExtensions.md
new file mode 100644
index 0000000..68bc1c3
--- /dev/null
+++ b/docs/OEMExtensions.md
@@ -0,0 +1,93 @@
+# Extending `cper-parse` With OEM Sections
+Section definitions within `cper-parse` are entirely modular, and can be easily modified at compile time to include custom OEM section extensions. This document will detail how these extensions can be added in from a stock version of the project.
+
+## Creating a Section Parser
+First, we need to create a parser to actually handle the conversion of the section from CPER -> CPER-JSON and CPER-JSON -> CPER.
+For the purposes of example here, we will create a fake CPER section, "myVendorSection", in `cper-section-myvendor.h` and `cper-section-myvendor.c`.
+
+*sections/cper-section-myvendor.h*
+```c
+#ifndef CPER_SECTION_MYVENDOR
+#define CPER_SECTION_MYVENDOR
+
+#include <json.h>
+#include "../edk/Cper.h"
+
+json_object* cper_section_myvendor_to_ir(void* section, EFI_ERROR_SECTION_DESCRIPTOR* descriptor);
+void ir_section_myvendor_to_cper(json_object* section, FILE* out);
+
+#endif
+```
+
+*sections/cper-section-myvendor.c*
+```c
+/**
+ * Describes functions for converting MyVendor sections from binary and JSON format
+ * into an intermediate format.
+ *
+ * Author: author@example.com
+ **/
+#include <stdio.h>
+#include <json.h>
+#include "../edk/Cper.h"
+#include "cper-section-ccix-per.h"
+
+json_object* cper_section_myvendor_to_ir(void* section, EFI_ERROR_SECTION_DESCRIPTOR* descriptor)
+{
+ //Define a method here that converts the bytes starting from "section" into JSON IR.
+ //The length of the bytes is described in descriptor->Length.
+ //...
+}
+
+void ir_section_myvendor_to_cper(json_object* section, FILE* out)
+{
+ //Define a method here that converts the given JSON IR object into CPER binary,
+ //writing the output to the provided stream.
+ //...
+}
+```
+Once this is done, we can add our section to the parser.
+
+## 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.
+They are defined here for shared use in both `cper-parse` and also `cper-generator` if you wish to write a generation method for your section.
+
+*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 Section Definition
+Finally, we need to add a section definition for our section, matching the GUID to the name and conversion methods.
+Open `sections/cper-section.c` and add your definition to the `section_definitions` array, like so:
+
+*sections/cper-section.c*
+```c
+/**
+ * Describes available sections to the CPER parser.
+ *
+ * Author: Lawrence.Tang@arm.com
+ **/
+#include "../edk/Cper.h"
+#include "cper-section.h"
+...
+#include "cper-section-myvendor.h"
+
+//Definitions of all sections available to the CPER parser.
+CPER_SECTION_DEFINITION section_definitions[] = {
+ ...
+ {&gMyVendorSectionGuid, "MyVendor Error", cper_section_myvendor_to_ir, ir_section_myvendor_to_cper},
+};
+```
+Now you're done! After a further `cmake .` and `make`, `cper-convert` and all other conversion libraries included should successfully convert your OEM CPER section between CPER-JSON and CPER binary.
\ No newline at end of file