[GSOC] : Reducing Publicly Installed .h Files

[Joel Sherrill]

On 4/14/2013 4:37 PM, Rempel, Cynthia wrote:
>> ________________________________________
>> From: Joel Sherrill [joel.sherrill at oarcorp.com]
>> Sent: Sunday, April 14, 2013 1:34 PM
>> To: Rempel, Cynthia
>> Cc: Vipul Nayyar; rtems-devel at rtems.org
>> Subject: [GSOC] : Reducing Publicly Installed .h Files
>>
>> Hi
>>
>> I had an insight which makes it easy to answer the question
>> "What BSP specific .h files do the testsuites depend upon?"
> Thanks for figuring out what question to ask, and coming up with a reasoned answer!
>> We typically think of BSPs for real hardware with levels of
>> complexity. It is easy to forget that RTEMS has a number of
>> very simple BSPs for the simulators built into gdb.
>>
>> Looking at gdbv850sim, m32rsim, m32csim, and h8sim, I can
>> pretty confidently state that this is the MINIMUM set of .h files
>> a BSP must install:
>>
>> $(PROJECT_INCLUDE)/bsp.h
>> $(PROJECT_INCLUDE)/tm27.h
>> $(PROJECT_INCLUDE)/bspopts.h
>> $(PROJECT_INCLUDE)/bsp/bootcard.h
>> $(PROJECT_INCLUDE)/coverhd.h
>>
>> And here are some notes on these:
>>
>> $(PROJECT_INCLUDE)/bsp.h - Universally needed per current rules
>> $(PROJECT_INCLUDE)/tm27.h - Only used by tmtests/tm27
>> $(PROJECT_INCLUDE)/bspopts.h - Universally needed per current rules
>> $(PROJECT_INCLUDE)/bsp/bootcard.h - Needed for fatal error information
>>     Rework possible since it has mix of what I would think is internal to the
>>     BSP and what would be part of its public interface.
>> $(PROJECT_INCLUDE)/coverhd.h - Used by tmtests.
>>      We could discuss obsoleting this. I bet most recent BSPs use the
>> version
>>      which default all values to 0.
> If coverhd.h, and tm27.h are just for supporting tmtests we should deprecate them, and obsolete them once we integrate one of the unit testing frameworks into the testsuite.
coverhd.h can probably be eliminated. It is "calling overhead" and 
represents the
time required (old school) to push arguments onto the stack, make the 
call, return,
and restore the stack. Eliminating this can be done as one sweep. But it 
will touch
all tmtests, possibly all psxtmtests, and all BSP Makefile.am's. It 
touches all timing
tests because they either directly use an overhead constant or at least 
use a macro
that expects one and is passed a zero.

But do-able and probably worth the trouble for something of decreasingly 
little value.

tm27.h cannot be removed. It is the BSP specific support mechanism for 
generating
an interrupt for benchmark purposes. With this, we can benchmark 
interrupt entry
and exit both with and without preemption.

And AFAIK the test frameworks discussed were not benchmarking 
frameworks. Both
these files are for benchmarking support.
> The merge procedure could start with the easiest to merge of bsp.h, bspopts.h, and bsp/bootcard.h and slowly work towards the harder to merge bsp files.
You can't merge these. These were the one that I would say are justified 
in staying. :)

Anything not in the "magic 5" needs to be justified.
>> Anything beyond that needs to be questioned using this as a starting point
>> for things which can be public:
>>
>> + Is it in support of an optional (but standard) API?
>>     - PCI
>>     - PIC IRQ
>>     - ... more TBD but a known list ...
> If the header is part of an optional (but standard) API that we are supporting, and not in the testsuite, tests should be added for them in the testsuite, so we can check the libraries. (This should most likely be added to the "wishlist" and not included in the header cleanup GSoC project.) We could also add to the "wishlist" (not the header cleanup GSoC project) patching the "sid" sourceware, qemu, and skyeye projects respectively to support testing these optional (but standard) API on simulated hardware, so we can run regression tests on at least simulated hardware.
Agreed. But the testing of these "optional APIs" will be tricky. They 
are to support hardware
that is sometimes present. We will probably have to create fake support 
layers to test with
like I did with the termios tests.

Yep.. if we can simulate the hardware and can test a real configuration 
that increases
confidence.

But this is for things like PCI, VMEBus, etc. A BSP won't even build it 
if the hardware
feature isn't there. And that means there needs to be a standard way of 
saying
"my BSP supports X".

A sticky problem but at least one that a single solution can apply to 
multiple
optional hardware APIs.
>> + ... more questions TBD ...
>>
>> If the answer isn't yes based on that growing list of questions, then we
>> should
>> push to make it private.
>>
>> Every publicly installed .h file should be there for a known reason. :)
> I agree.

I think that's what makes this project doable. bsp.h, bspopts.h, and 
bootcard.h all
have justified reasons. tm27.h does also.

coverhd.h is on the cusp.

Anything else needs to be discussed.  A simple rule is likely that if 
the file is not
shared with any other BSP or supports an optional hardware framework, then
it is private.

If it is in support of a shared API implementation, it may be public. I 
think
the PIC IRQ framework requires a public <bsp/irq.h> so that would be one
we would say OK to.

FWIW the real-time clock drivers are sometimes called time of day drivers.
The BSPs are horribly inconsistent about this. We should standardize and
fix these.
>> --
>> 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