[PATCH] c-user: Document CONFIGURE_DIRTY_MEMORY

[Chris Johns]

On 11/2/20 4:57 pm, Sebastian Huber wrote:
> 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."

Nice. A minor tweak ...

... incorrectly assumes the contents ... ?

?

Chris