[PATCH] c-user: Document CONFIGURE_DIRTY_MEMORY

[Sebastian Huber]

On 10/02/2020 22:30, Gedare Bloom wrote:

> On Mon, Feb 10, 2020 at 2:14 PM Chris Johns <chrisj at rtems.org> wrote:
>>
>>
>> On 10/2/20 8:32 pm, Sebastian Huber wrote:
>>> 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
>> .. "assumes memory starts set to zero" does not look right to me?
>>
> At first I disagreed, but then it does seem ambiguous, whether it
> means the starting address is 0 or the value is 0.
>
> It should be clarified, "memory values start set to zero" or "set to
> all zeroes" to make it clear memory is meant in the plural sense.

The FreeBSD man page uses "The memory is set to zero." Should I change 
it to:

"It may assist in finding code that assumes the content of free memory 
areas is cleared to zero during system initialization."