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

[Gedare Bloom]

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. However, we could
put most of this in the porting document, and the comment in no_cpu is
better than just saying "this is the size of a pointer" since it tells
why we use it.
-Gedare

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