Re: [avr-libc-dev] RFD: more avr-libc API changes

[Joerg Wunsch]

As E. Weddington wrote:

> > If so, what to do with timer_enable_int() and enable_external_int(),
> > should I start a <compat/deprecated.h> for these?

> - We should define the <compat/*> include directory as for
> "compatability" includes only. I would take this as meaning
> "compatability with other compilers" (i.e. IAR, etc.), and
> "backwards compatability" (i.e. deprecated items that are
> semi-removed).

I agree. So then, <compat/deprecated.h> ought to be OK.

I'm no longer so sure about <compat/twi.h>.  Given that we've settled
for a util/ subdir, I'd rather move twi.h there, and leave stubs in
compat/ and avr/.

> - We should define the <avr/*> include directory as for includes
> that are specific to the AVR hardware. For example <avr/boot.h> and
> <avr/sleep.h>

Yep.

> - As a consequence, a "universal UART" header would go into the
> <avr/*> tree because it is still specific to the AVR hardware. IMHO,
> it would be <avr/uart.h> (or perhaps <avr/usart.h>). If one sees how
> <avr/sleep.h> has become a "universal SLEEP" header, then you can
> see how the "universal UART" header fits in here.

I'm not that happy about that...  I'd rather collect them elsewhere,
but I agree, they're AVR-specific.

Would people find it annoying to add another subdir level?  So then,
all "generic IO" headers could e.g. go into avr/generic/, the include
statement would then be

#include <avr/generic/uart.h>

supposedly providing a generic uniform UART view for as many as
possible AVRs.

> - I think it would be best to go ahead and deprecate
> timer_enable_int() and enable_external_int(). I agree that the
> naming wasn't very well thought out, perhaps.

OK, <compat/deprecated.h>?

> - I have a possible replacement for the "external interrupt" header. 
> ..., and I would suggest naming the header 
> <avr/extint.h>.

Or <avr/generic/extint.h> if we could agree on the above.

> - Going along with the theme, it would be good to eventually have an
> <avr/timer.h> header that deals with timers. Again, I have some
> possible candidates as a starting point.

Fine.  Be a bit careful about the name, we once already had an
<avr/timer.h>, so old source code floating in the Internet could
expect something else there.  Again, no deal with the additional
subd... :-)

> - Our previous offline discussion of having a <util/*> tree would be
> good for "utility headers", i.e. headers that are nice, but not
> necessary, and that is not related to the AVR hardware.

ACK.


As Wojtek Kaniewski wrote:

> >- I think your idea of <avr/deprecated.h> is a great idea! We could
> >put all of those outdated macros in it: sbi(), cbi(), outp(),
> >inp(), etc. ad naseum. :-)

> That would be great. I wouldn't have to explain my friends what does
> "PORTD&=~_BV(4);" mean (-;

Except you'd need to explain them what cbi means as it's not a C
standard, and could mean anything else beyond occasionally generating
a CBI instruction. ;-)

> Is there any policy for supporting some additional hardware?

In general, avr-libc wants to keep out of the hardware business.

> BTW, <util/...> would be a good place for <avr/crc16.h> too.

ACK.


As E. Weddington wrote:

> >If naming consistency is important, then we should probably do
> >something about fdevopen() and fdev_*() too. All fdev functions
> >except fdevopen() use underscores.

> Good point.

Half point.  To compare it to my original complaint about the
interrupt helpers, we didn't name one fdevopen() and the other one
setup_stream_fdev().

I found the underscores in the new names to improve readability, yet I
wouldn't want to rename fdevopen() as it's an established interface.
(fdevopen() has once been chosen as an analogy to fopen().)

> >Is there any policy for supporting some additional hardware?

> This gets complicated.

> One the one hand, avr-libc is supposed to provide a C library only,
> and we have extended it to support some of the on-board
> peripherals. I think we could, and should, do more to support the
> on-board peripherals. But that should be the extent of the avr-libc
> project.

I think the only on-board "peripheral" we've got support for is the
EEPROM, and well, that did cause us enough grief already.

Support for the LPM and SPM stuff could hardly be considered a
"peripheral"...  Perhaps the watchdog could be considered a
peripheral, yes.

> On the other hand, I abhor reinventing the wheel and there should be
> a place for *exactly* what you describe: libraries to interface to
> common external peripherals, that have been vetted.

I think this is worth a separate project.  However, to run this will
require a number of more volunteers to actively participate, as I see
all those currently involved to be staturated with what they've got.

> >BTW, <util/...> would be a good place for <avr/crc16.h> too.

> Very good point. crc16.h has nothing to do with AVR hardware, but it
> is a very useful utility.

Likewise for avr/parity.h, and probably also avr/delay.h.

That would leave the following user-visible headers in the avr/
subdir:

boot.h eeprom.h interrupt.h io.h pgmspace.h (signal.h) sleep.h wdt.h

-- 
cheers, J"org               .-.-.   --... ...--   -.. .  DL8DTL

http://www.sax.de/~joerg/                        NIC: JW11-RIPE
Never trust an operating system you don't have sources for. ;-)