rtems/src/scheduler* code convention issue

[Gedare Bloom]

On Fri, May 30, 2014 at 9:24 AM, Joel Sherrill
<joel.sherrill at oarcorp.com> wrote:
>
> On 5/30/2014 8:13 AM, Gedare Bloom wrote:
>> On Fri, May 30, 2014 at 9:04 AM, Joel Sherrill
>> <joel.sherrill at oarcorp.com> wrote:
>>> On 5/30/2014 2:43 AM, Peter Dufault wrote:
>>>> On May 29, 2014, at 17:47 , Gedare Bloom <gedare at rtems.org> wrote:
>>>>
>>>>> You understood precisely. I think it was not permitted in C90 perhaps?
>>>>> We should revisit it, but I think historically all variables are
>>>>> declared at the top of the function.
>>>> I'll dig up K&R, but I'm 95% sure it's been supported from the beginning.  What hasn't always been supported is declaring variables anywhere other than after an opening bracket:
>>>>
>>>> /* Local block */
>>>> {
>>>>       invoke_foo();
>>>>       int i;
>>>>       invoke_bar(&i);
>>>>       /* ... */
>>>> }
>>>>
>>>> The argument for permitting declaration inside brackets (not as above, but as allowed by K&R) is to declare variables in as restrictive a scope as possible.  The argument against is shadowing variables and getting subtle errors.
>>> I don't know if we have it on but gcc has a shadowing warning which
>>> is pretty effective. I did a code review for a project and learned they
>>> had disabled warnings "because there were too many." When I turned
>>> them back on, there were 1000s and among them:
>>>
>>> + parameters shadowing global variables.
>>> + outer scope local variables shadowing global variables.
>>> + inner scope local variables (from macros) shadowing local variables
>>>
>>> GCC spotted all of the above. I am pretty confident in GCC's shadowing
>>> detection.  If we want to allow/encourage this, we need to turn
>>> the warning on.
>>>
>> Thanks for the discussion on this. I will put a rule as declaring
>> variables at the start of a block, and not to shadow variables.
>>
>> Whether we want to encourage variables in nested scopes remains open
>> for discussion, but I think we should allow it at least.
>>
>>> Also we need to remember to write down that macro parameters
>>> start with an _ so as to avoid name collision. The project I reviewed
>>> didn't follow that rule.  They also didn't have naming rules which
>>> prevented collisions between local, global, and parameters.
>> I'll add a note about it.
> In case there is not a rule about naming. The public API routines follow
> a standard API like POSIX or *BSD or start with rtems_. In the 4.7-4.9
> timeframe, I cleaned up a lot of support code to do this like the
> stack checker, cpu use, period use, etc.
>
> If a method starts with rtems_, then it should be assumed to be
> available for use by the application and have documentation in
> the User's Guide.
>
There is now a page about naming, linked from the coding conventions:
http://www.rtems.org/wiki/index.php/Naming_rules

> Internal methods (inside score, sapi, rtems, and posix with
> hope that libcsupport and RTEMS specific filesystems and other
> cpukit code follow along) are named by "package" and "method".
> If you think C++, you get package::method. But _[A-Z] indicates
> where a namespace separator would be. The leading _ makes it
> private.
>
I don't quite follow, perhaps you should read the naming rules and
make sure they are consistent with your thinking. My understanding is
that everything that is internal starts with an underscore. There is
no distinction about "private" (in the OOP sense), and any internal
RTEMS code can call any other internal RTEMS code. That said, there
are some layering rules about what code can call what code, but I
don't see them codified anywhere. I have a section set-aside for those
rules when someone gets time to define them.

-Gedare

> _Chain_Get_first is a private method named Get_first in Chain.
> In C++, it might be _Chain::Get_first.
>
> Many modules are essentially classes which encapsulate a
> data structure and all accesses with methods. The first
> parameter to most methods is then going to be logically
> an instance pointer like C++ this.
>
> I don't know if I am rambling, repeating things documented
> now, or something else. But hopefully core dumping like
> this helps.
>> -Gedare
>>
>>>> Peter
>>>> -----------------
>>>> Peter Dufault
>>>> HD Associates, Inc.      Software and System Engineering
>>>>
>>> --
>>> Joel Sherrill, Ph.D.             Director of Research & Development
>>> joel.sherrill at OARcorp.com        On-Line Applications Research
>>> Ask me about RTEMS: a free RTOS  Huntsville AL 35805
>>> Support Available                (256) 722-9985
>>>
>
> --
> Joel Sherrill, Ph.D.             Director of Research & Development
> joel.sherrill at OARcorp.com        On-Line Applications Research
> Ask me about RTEMS: a free RTOS  Huntsville AL 35805
> Support Available                (256) 722-9985
>