[rtems-docs commit] c-user: Document CONFIGURE_DIRTY_MEMORY

[Sebastian Huber]

Module:    rtems-docs
Branch:    master
Commit:    e57733a9bd31398fb0fbe00e5ab9fb95e68e7830
Changeset: http://git.rtems.org/rtems-docs/commit/?id=e57733a9bd31398fb0fbe00e5ab9fb95e68e7830

Author:    Sebastian Huber <sebastian.huber at embedded-brains.de>
Date:      Mon Feb 10 10:28:49 2020 +0100

c-user: Document CONFIGURE_DIRTY_MEMORY

Close #3843.

---

 c-user/configuring_a_system.rst | 36 +++++++++++++++++++++++++++++++++++-
 1 file changed, 35 insertions(+), 1 deletion(-)

diff --git a/c-user/configuring_a_system.rst b/c-user/configuring_a_system.rst
index 81bc9bb..00584c1 100644
--- a/c-user/configuring_a_system.rst
+++ b/c-user/configuring_a_system.rst
@@ -425,6 +425,38 @@ General System Configuration
 This section defines the general system configuration options supported by
 ``<rtems/confdefs.h>``.
 
+.. index:: CONFIGURE_DIRTY_MEMORY
+
+.. _CONFIGURE_DIRTY_MEMORY:
+
+CONFIGURE_DIRTY_MEMORY
+----------------------
+
+CONSTANT:
+    ``CONFIGURE_DIRTY_MEMORY``
+
+DATA TYPE:
+    Boolean feature macro.
+
+RANGE:
+    Defined or undefined.
+
+DEFAULT VALUE:
+    By default, the memory used by the RTEMS Workspace and the C Program Heap
+    is uninitialized memory.
+
+DESCRIPTION:
+    This macro indicates whether RTEMS should dirty the memory used by the
+    RTEMS Workspace and the C Program Heap as part of its initialization.  If
+    defined, the memory areas are dirtied with a ``0xCF`` byte pattern.
+    Otherwise, they are not.
+
+NOTES:
+    Dirtying memory can add significantly to system boot time.  It may assist
+    in finding code that assumes memory starts set to zero.  In case
+    :ref:`CONFIGURE_ZERO_WORKSPACE_AUTOMATICALLY` is also defined, then the
+    memory is first dirtied and then zeroed.
+
 .. index:: CONFIGURE_EXTRA_TASK_STACKS
 .. index:: memory for task tasks
 
@@ -1006,7 +1038,9 @@ DESCRIPTION:
 
 NOTES:
     Zeroing memory can add significantly to system boot time. It is not
-    necessary for RTEMS but is often assumed by support libraries.
+    necessary for RTEMS but is often assumed by support libraries.  In case
+    :ref:`CONFIGURE_DIRTY_MEMORY` is also defined, then the memory is first
+    dirtied and then zeroed.
 
 Classic API Configuration
 =========================