RE: [avr-libc-dev] Adding (some) Procyon AVRlib functionality to avr-libc

[Ron Kreymborg]

Some thoughts on a library.

Let me start with a library that manages just the processor's internal
peripherals: best practise would have all data structures the code requires
declared as private (static). Data in, data out, exceptions and status would
all be accessible only via public functions (external). Any housekeeping
data would be private. All this probably goes without saying, but now some
very sticky questions need to be answered. 

Best practise would also specify that interrupts be used as this makes for
the most efficient use of the peripheral. The "send" side of the code causes
problems in how to handle a busy device. Typically an "are-you-ready"
function will suffice, but others will need tools to add for example,
semaphore access. While these problems are not that difficult the "receive"
side problems are. A polling (status) function could be provided or a
call-back function could signal the host program that "something" has
arrived. The call-back could set a flag the host program eventually actions
in some background loop, but this by definition would be time indeterminate.
Perhaps the module could use a software interrupt so the host can action the
event with some alacrity, but that means defining additional interrupts per
device. And some applications will require the interrupt function be outside
the library module altogether because the data stream simply requires
immediate action. While this could also be a call-back function we are then
stuck with avrgcc stacking every register (the C++ bugbear).

External peripherals are not so bad. Most display drivers for instance are
essentially one way. Most networks (CAN, LIN, etc) are happy with a flag
setting call-back for the packet "receive" side which should be adequate
except where speed is an absolute premium. Thus the internal data structures
for these modules can be safely hidden and a standard set of access
functions written that cover most possibilities. 

A library for handling data structures (queues, lists, stacks, trees, etc
(something like a cut down STL)) would also lend itself to a closed library.

My point is that creating this library (or these libraries) is not a case of
us collecting our best bits and bundling them up. While the internals may
not be that hard, I think defining the API for each module will require
considerable discussion.

So Jorg, the idea of a separate list sound good in the long run, but might I
suggest we thrash out the ideas for, say, a USART API here on this list,
keeping in mind the points I raised in the second para. Many of us have
implemented one of these so there will be a good cross section of ideas on
what it should look like and how it should work. Let me suggest some basic
rules:

-------------

1a. All public functions are capitalised with no underscores and prefixed
with up to 4 letters defining the device.

Or conversely:

1b. All public functions are lower case using underscores for readability
with up to 4 letters defining the device.

An example of 1a) would be spiSendMessage, and of 1b) spi_send_message. I
vote for 1a but democracy would rule.

2. All modules which require prior initialisation use the same name for this
function, such as Init or Setup. Eg spiInit or spi_init.

3. All internal data structures are private (static) and only accessible via
public functions. All internal functions are likewise private.

--------------

If this looks like the definition for a C++ class then that is my basic
idea. 

David Brown's idea of partial releases for community testing is good. The
library group can internally decide on a peripheral, work out an initial
API, put it out for comment, revise as necessary, implement, release for
beta, and finally release the module integrated into the library. The source
code can be released after adoption as otherwise the suggestions will be
overwhelming. At that point individuals can play with it at their leisure
but the distributed library would only change for bug fixes.

I think enough of us have written this stuff that the code itself is not the
challenge, but defining each module's API so we can all use it for most
projects will be.

All suggestions welcome.
Ron