[rtems commit] sparc/cpu.h: Add comments

[Gedare Bloom]

On Tue, Mar 19, 2013 at 12:35 PM, Sebastian Huber
<sebastian.huber at embedded-brains.de> wrote:
> On 03/19/2013 05:31 PM, Gedare Bloom wrote:
>>
>> On Tue, Mar 19, 2013 at 4:39 AM, Sebastian Huber
>> <sebastian.huber at embedded-brains.de>  wrote:
>>>
>>> >On 03/18/2013 07:14 PM, Joel Sherrill wrote:
>>>>
>>>> >>
>>>> >>On 3/18/2013 1:05 PM, Gedare Bloom wrote:
>>>>>
>>>>> >>>
>>>>> >>>Why is your comment a question?
>>>>
>>>> >>
>>>> >>Most of the CPU port comment blocks are questions about the parameter
>>>> >>and a description of that parameter. This is followed by a port
>>>> >> specific
>>>> >>answer.
>>>> >>
>>>> >>I didn't know the best way to phrase the answer.  [And I wanted to get
>>>> >>this patch off my microblaze branch.]
>>>> >>
>>>> >>I think Sebastian added this definition to every port with no comment
>>>> >>block.
>>>
>>> >
>>> >
>>> >The no_cpu file has a comment:
>>> >
>>> >/**
>>> >  * Size of a pointer.
>>> >  *
>>> >  * This must be an integer literal that can be used by the assembler.
>>> > This
>>> >  * value will be used to calculate offsets of structure members.  These
>>> >  * offsets will be used in assembler code.
>>> >  */
>>> >#define CPU_SIZEOF_POINTER         4
>>> >
>>> >
>>>>
>>>> >>If you like, I can propagate the question to all ports with an
>>>> >>answer like:
>>>> >>
>>>> >>The size of a pointer (e.g. void *) is always XXX bytes.
>>>> >>
>>>> >>OR
>>>> >>
>>>> >>The size of a pointer (e.g. void *) is varies based upon the multilib
>>>> >>variant. For X and Y, it is NNN bytes. For all others, it is MMM
>>>> >> bytes.
>>>> >>
>>>> >>Are those viable options?
>>>
>>> >
>>> >
>>> >I don't think we should comment the obvious.  A useful comment would be
>>> > a
>>> >reference to the corresponding ABI document and section.
>>> >
>>
>> Obviousness is subjective. Just looking at a definition like this
>> would not tell me anything if there is a multilib.
>
>
> If this is defined unconditionally, then there is no multilib involved.  If
> you see something like this
>
> #ifdef __m32cm_cpu__
>   #define CPU_SIZEOF_POINTER 4
> #else
>   #define CPU_SIZEOF_POINTER 2
> #endif
>
> a multilib is involved.
>
OK. I think we should just propagate a comment like what we have in
no_cpu that tells how the definition is used.

>
> --
> Sebastian Huber, embedded brains GmbH
>
> Address : Dornierstr. 4, D-82178 Puchheim, Germany
> Phone   : +49 89 189 47 41-16
> Fax     : +49 89 189 47 41-09
> E-Mail  : sebastian.huber at embedded-brains.de
> PGP     : Public key available on request.
>
> Diese Nachricht ist keine geschäftliche Mitteilung im Sinne des EHUG.