[PATCH] c-user: Document CONFIGURE_DIRTY_MEMORY

[Gedare Bloom]

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.

Gedare

> Chris
>
> > +    :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
> >  =========================
> >
> _______________________________________________
> devel mailing list
> devel at rtems.org
> http://lists.rtems.org/mailman/listinfo/devel