From fe96aee47cdb889bb02b337fd916c3d240fc4128 Mon Sep 17 00:00:00 2001
From: PMheart <17109513+PMheart@users.noreply.github.com>
Date: Thu, 31 Dec 2020 09:03:59 +0800
Subject: [PATCH] Docs: Bring more details to ocvalidate

---
 Utilities/ocvalidate/README.md | 29 ++++++++++++++++++-----------
 1 file changed, 18 insertions(+), 11 deletions(-)

diff --git a/Utilities/ocvalidate/README.md b/Utilities/ocvalidate/README.md
index be28a3c2..48ecc0aa 100644
--- a/Utilities/ocvalidate/README.md
+++ b/Utilities/ocvalidate/README.md
@@ -1,12 +1,19 @@
-ocvalidate Checklist
+ocvalidate
 ====================
 
-## At a glance
+Utility to validate whether a `config.plist` matches requirements and conventions imposed by OpenCore.
+
+## Usage
+- Pass one single path to `config.plist` to verify it.
+- Pass `--version` for current supported OpenCore version.
+
+## Technical background
+### At a glance
 - ocvalidate firstly calls `OcSerializeLib` which performs fundamental checks in terms of syntax and semantics. After that, the following will be checked.
 - The error message `<OCS: No schema for xxx>` complained by `OcSerializeLib` indicates unknown keys that can be deprecated in new versions of OpenCore. Such keys should be ***removed*** in order to avoid undefined behaviours.
 - Under active development, newer versions of OpenCore hardly have backward compatibility at this moment. As a result, please first run `ocvalidate --version` to check which version of OpenCore is supported, and thus please only use the specific version. 
 
-## Global Rules
+### Global Rules
 - All entries must be set once only. Duplication is strictly prohibited.
 - All strings (fields with plist `String` format) throughout the whole config only accept ASCII printable characters at most. Stricter rules may apply. For instance, some fields only accept specified values, as indicated in [Configuration.pdf](https://github.com/acidanthera/OpenCorePkg/blob/master/Docs/Configuration.pdf).
 - Most binary patches must have `Find`, `Replace`, `Mask` (if used), and `ReplaceMask` (if used) identical size set. Also, `Find` requires `Mask` (or `Replace` requires `ReplaceMask`) to be active (set to non-zero) for corresponding bits.
@@ -17,12 +24,12 @@ ocvalidate Checklist
 - Entries requiring bitwise operations (e.g. `ConsoleAttributes`, `PickerAttributes`, or `ScanPolicy`) only allow known bits stated in [Configuration.pdf](https://github.com/acidanthera/OpenCorePkg/blob/master/Docs/Configuration.pdf) to be set.
 - Entries involving GUID (mainly in Section `NVRAM`) must have correct format set.
 
-## ACPI
+### ACPI
 #### Add
 - Entry[N]->Path: Only `.aml` and `.bin` filename suffix are accepted.
 - Entry[N]->Path: If a customised DSDT is added and enabled, `RebaseRegions` in `ACPI->Quirks` should be enabled.
 
-## Booter
+### Booter
 #### MmioWhitelist
 - Entry[N]->Enabled: When at least one entry is enabled, `DevirtualiseMmio` in `Booter->Quirks` should be enabled.
 #### Patch
@@ -34,10 +41,10 @@ ocvalidate Checklist
 - If `ProvideMaxSlide` is set to a number greater than zero, `ProvideCustomSlide` should be enabled altogether.
 - When `DisableVariableWrite`, `EnableWriteUnprotector`, or `ProvideCustomSlide` is enabled, `OpenRuntime.efi` should be loaded in `UEFI->Drivers`.
 
-## DeviceProperties
+### DeviceProperties
 - Requirements here all follow Global Rules.
 
-## Kernel
+### Kernel
 #### Add
 - Entry[N]->Arch: Only `Any`, `i386`, or `x86_64` are accepted.
 - Entry[N]->BundlePath: Filename should have `.kext` suffix.
@@ -54,7 +61,7 @@ ocvalidate Checklist
 - KernelArch: Only `Auto`, `i386`, `i386-user32`, or `x86_64` are accepted.
 - KernelCache: Only `Auto`, `Cacheless`, `Mkext`, or `Prelinked` are accepted.
 
-## Misc
+### Misc
 #### Boot
 - HibernateMode: Only `None`, `Auto`, `RTC`, or `NVRAM` are accepted.
 - PickerMode: Only `Builtin`, `External`, or `Apple` are accepted.
@@ -64,16 +71,16 @@ ocvalidate Checklist
 - Vault: Only `Optional`, `Basic`, or `Secure` are accepted.
 - SecureBootModel: Only `Default`, `Disabled`, `j137`, `j680`, `j132`, `j174`, `j140k`, `j780`, `j213`, `j140a`, `j152f`, `j160`, `j230k`, `j214k`, `j223`, `j215`, `j185`, `j185f`, or `x86legacy` are accepted.
 
-## NVRAM
+### NVRAM
 - Requirements here all follow Global Rules.
 
-## PlatformInfo
+### PlatformInfo
 - UpdateSMBIOSMode: Only `TryOverwrite`, `Create`, `Overwrite`, or `Custom` are accepted.
 #### Generic
 - SystemProductName: Only real Mac models are accepted.
 - SystemMemoryStatus: Only `Auto`, `Upgradable`, or `Soldered` are accepted.
 
-## UEFI
+### UEFI
 #### APFS
 - When `EnableJumpstart` is enabled, `ScanPolicy` in `Misc->Security` should have `OC_SCAN_ALLOW_FS_APFS` (bit 8) set, together with `OC_SCAN_FILE_SYSTEM_LOCK` (bit 0) set. Or `ScanPolicy` should be `0` (failsafe value).
 #### Quirks