Re: [avr-libc-dev] Ordered todo

[Joerg Wunsch]

As Theodore A. Roth wrote:

> :) >      + include/avr/ina90.h  ???
> :)
> :) I'd wish to move that to include/compat/ina90.h.  Documentation could
> :) probably be sparse, just mention that it's there for IAR
> :) compatibility.
> 
> I'm ok with that if the avr/*.h files are "ina90.h" clean. In reality,
> anything in ina90.h should be defined in terms of the avr/* stuff, not
> vice versa.

Exactly.  I thought we already moved/renamed the affected parts.  Will
do some research on this.

> :) >      + include/avr/wdt.h (move to examples?)
> :)
> :) This one could be kept, IMHO.  Fairly useful, basically a complete
> :) interface for the watchdog, and keeps all the hairy details away
> :) from the luser.  I could document it.

> I mostly agree. It needs dox and probably should define some values
> to pass. Similar to what I did with sleep.h (sleep.h needs to be
> genericized to handle more than the m128 though).

The question is whether it makes any sense to invent names for the
watchdog timer prescaler argument (0 through 7).  Since the watchdog
oscillator frequency heavily depends not only on the device but also
on things like supply voltage and temperature, you can't tell an exact
number of (milli)seconds for these 8 constants.  The only general rule
that applies is that larger constants give longer timeouts.  So, the
only symbolic constants that would make sense are WDT0 through WDT7...

> :) I wish we could move out the common register definitions into
> :) <avr/io.h> itself before 1.0 as well.  So far, that's at least SREG,
> :) SPL, SPH. [...]

> :) Ted, didn't you say you want to do that some day?  Otherwise i might
> :) look into that, too.
> 
> Ultimately, yes. I'd say go ahead and move SREG, SPL and SPH now since
> that is a relatively simple change.

SPL/SPH is not present on avr1 architecture devices, but that is easy
to handle.  There are some devices (with only 256 bytes of SRAM) that
don't support SPH (2313, 2323, 2343, tiny22, tiny26), but i guess
nothing bad will happen when attempting to write to the respective
non-register.  Hopefully, the non-present SPH will read out as 0,
otherwise malloc() might run into troubles anyway...  We can easily
#define all the common registers first in <avr/io.h>, and then divert
to the MCU-specific <avr/ioXXX.h> which can #undefine SPH so the
application won't see the wrong register name.  Some of the headers
are even wrong here, e. g. the 2333 has only 128 bytes of SRAM and
thus no SPH, but the header file declares it anyway...

MCUCR is only missing in tiny28 and at94k.

WDTCR is only missing in AT90C8534 (an almost unknown device anyway).
Pah.  Does the tiny28 really have a different location for WDTCR, or
is this an error in the header file (0x01 vs. 0x21, looks pretty damn
like _SFR_OFFSET).  Gotta look into that datasheet...

XL/XH/YL/YH are only missing in avr1 architectures, easy to catch.

ZL/ZH is present in all devices.

I guess that's the common registers so far.  I'm reluctant to pull
anything like PORTA etc. out of the device-specific section even
though some of the ports are probably present on almost any AVR.

> :) >  - Document how to pre-program the EEPROM.
> :)
> :) Hmm, hmm.  Wasn't there something already?  I remember that someone
> :) submitted a bugfix (fix offset for avr-objcopy).

> That bug fix was for extracting the .eeprom from the elf file. I
> started looking into writing up how to use uisp to do this, but uisp
> looked to be broken in this case and I never followed up on it
> (needs more research).

I could describe how to do it in avrprog, but Brian's section about
avrprog already basically does it (although only verbally, not within
an example).  I do have no clues about UISP.

> :) >  - Figure out how to remove __ prefix from function args in dox.
> 
> Here's an ugly way to do it:
> 
> /** \ingroup silly_example
>     \param foo An integer argument.
>     \param bar A shady character.
> 
>     \returns Nothing. */
> 
> #ifdef DOXYGEN
> void dox_proto (int foo, char bar);
> #else
> void dox_proto (int __foo, char __bar);
> #endif

Hmm.  Better than nothing.

Btw., that "DOXYGEN" above gets in from doxygen.conf, doesn't it?  I
don't like it.  Should be "__DOXYGEN" so to not collide with the
application namespace.  Otherwise, a luser defining DOXYGEN before
including our header files might get funny results.

If we agree, the sweep to convert all DOXYGEN into __DOXYGEN should be
made before 1.0, the rest can wait.

> Or for macros, you just use a _fake_ function prototype for doxygen
> and the macro for the real program. (I don't like the macro style
> dox since it doesn't convey what the type of the args should be.)

Agreed.

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