2 files changed, 45 insertions, 0 deletions
diff --git a/Documentation/security/index.md b/Documentation/security/index.md
index 9ad54866c2a5..379375b6168a 100644
--- a/Documentation/security/index.md
+++ b/Documentation/security/index.md
@@ -6,3 +6,4 @@ This section describes documentation about the security architecture of coreboot
 
 - [Verified Boot](vboot/index.md)
 - [Measured Boot](vboot/measured_boot.md)
+- [Memory clearing](memory_clearing.md)
diff --git a/Documentation/security/memory_clearing.md b/Documentation/security/memory_clearing.md
new file mode 100644
index 000000000000..3d985925d926
--- /dev/null
+++ b/Documentation/security/memory_clearing.md
@@ -0,0 +1,44 @@
+# Memory clearing
+
+The main memory on computer platforms in high security environments contains
+sensible data. On unexpected reboot the data might persist and could be
+read by a malicious application in the bootflow or userspace.
+
+In order to prevent leaking information from pre-reset, the boot firmware can
+clear the main system memory on boot, wiping all information.
+
+A common API indicates if the main memory has to be cleared. That could be
+on user request or by a Trusted Execution Environment indicating that secrets
+are in memory.
+
+As every platform has different bring-up mechanisms and memory-layouts, every
+The device must indicate support for memory clearing as part of the boot
+process.
+
+## Requirements
+
+1. The platform must clear all platform memory (DRAM) if requested
+2. Code that is placed in DRAM might be skipped (as workaround)
+3. Stack that is placed in DRAM might be skipped (as workaround)
+4. All DRAM is cleared with zeros
+
+## Implementation
+
+A platform that supports memory clearing selects Kconfig
+``PLATFORM_HAS_DRAM_CLEAR`` and calls
+
+```C
+bool security_clear_dram_request(void);
+```
+
+to detect if memory should be cleared.
+
+The memory is cleared in ramstage as part of `DEV_INIT` stage. It's possible to
+clear it earlier on some platforms, but on x86 MTRRs needs to be programmed
+first, which happens in `DEV_INIT`.
+
+Without MTRRs (and caches enabled) clearing memory takes multiple seconds.
+## Exceptions
+
+As some platforms place code and stack in DRAM (FSP1.0), the regions can be
+skipped.