Re: [avr-libc-dev] dox status and next release

[Joerg Wunsch]

As E. Weddington wrote:

> > The only open topic was whether it's OK to have no _LPM() (but only
> > __LPM()) in the default header, i. e. to require users who want the
> > IAR compatibility names to include <avr/ina90.h>.

> IMHO, users who want an API that belongs to another compiler should 
> have to include the appropriate header file needed.

I agree with this.

Btw., we currently have nothing that could be used in C code to cause
a sleep instruction, except of _SLEEP() in ina90.h.  Although it's
basically a simple inline asm statement, i think we should provide a C
equivalent for it.  The question is: how to name it, and which header
file to put it into?  The name sleep(), although not reserved by the
standard, is usually (i. e. in Unix, and thus in C dialects that mimic
some aspects of the Unix API) meant to suspend program execution for a
number of seconds that is going to be passes as an argument to this
function, therefore i think it's merely a poor choice.  suspend()?
avr_sleep()?  mcu_sleep()?

Every AVR datasheet mentions that SE (sleep enable) should only be set
immediately before entering sleep mode.  This would warrant to extend
the functionality of this macro to do this.  We could finally also
provide macros to give the various sleep modes more descriptive names,
but they are fairly device-dependant.  However, then it's probably
worth to put all this into a file of its own, like <avr/sleep.h>...

> But what were the rules regarding 1 and 2 leading underscores? (I 
> think I missed that).

Ah, yes.

Well, the standard is quite obfuscated on this.  Unfortunately, i
don't have it available in a cut&paste form, so i have to type it
manually:

7.1.3 Reserved identiviers

Each header declares or defines all identifiers listed in its
associated subclause, and optioanlly declares or defines identifiers
listed in its associated future library directions subclause and
identifiers which are always reserved either for any use of for use as
file scope identifiers.

- All identifiers that begin with an underscore and either an
  uppercase letter or another underscore are always reserved for any
  use.

- All identifiers that begin with an underscore are always reserved
  for use as macros and as identifiers with file scope in both the
  ordinary and tag name spaces.

- Each macro name in any of the following subclauses (including the
  future library directions) is reserved for use as specified if any
  of its associated headers is included; unless explicitly stated
  otherwise (see 7.1.8).

- All identifiers with external linkage in any of the followin
  subclauses (including the future library directions) are always
  reserved for use as identifiers with external linkage.

- Each identifier with file scope listed in any of the following
  subclauses (including the future library directions) is reserved for
  use as macro and as an identifier with file scope in the same name
  space if any of its associated headers is included.

No other identifiers are reserved.  If the program declares or defines
an identifier that is reserved in that context (other than as allowed
by 7.1.8), the behaviour is undefined.


All is quite clear now, isn't it? :-)

Several things come to mind here.

First, we should be fine using both, __FOO and _FOO.  __foo is a bit
different, although the difference might be neglicible in most cases.

Then, remember that all this refers to standard headers.  Any
additional custom header file is not subject of the standard's
restrictions.  That's why i think we could have continued to use BV(),
it's purely AVR-specific and only #defined if <avr/io.h> was included.
(Further, if an application believes it needs this name, it is free to
just #undef it.)  Anyway, the transition to _BV() has been done now,
so i don't vote for reverting this.

Even for standard headers, systems like Unix-like ones usually extend
them by further declarations and definitions.  They then hide the
extensions behind !defined(_ANSI_SOURCE).

There are some more things we should care about in future.  There are
"function-like" macros (like abs()), and there's a requirement that
for each such macro, a true function prototype must be provided as
well (for obvious reasons, it must preced the macro definition in the
respective header file), and the user can access this function (and
e. g. take the address of it, to pass it to another function) by
#undef'ing the macro.

Also, there's a lot to care about in <math.h>.  This is future stuff
though, i wouldn't delay a prospective version 1.0 for this.  The only
thing we should clarify before is any changes that are incompatible
with previous versions (like the outb() changes) so there won't be
many more annoying (for the users) API changes in future.

-- 
J"org Wunsch                                           Unix support engineer
address@hidden        http://www.interface-systems.de/~j/