Re: [avr-libc-dev] Ordered todo

[Theodore A. Roth]

On Thu, 12 Dec 2002, Joerg Wunsch wrote:

:) As E. Weddington wrote:
:)
:) > Lastly, should the "port newlib" item be dropped? i.e. how useful is
:) > this item?
:)
:) I think it's not useful at all, but i don't know who has ever put it
:) onto this list.  Marek?
:)
:) I've already moved it to the bottom for that reason. ;-)
:)
:) > Before avr-libc 1.0
:) >  - Doxument the following:
:) >    * interfaces in:
:) >      + include/avr/crc16.h  ???
:) >      + include/avr/delay.h  ???
:) >      + 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.

:)
:) I'd also like to see the following two files in include/compat/.  For
:) version 1.0, we do supply the wrappers directly under include/ anyway
:) that issue a warning.  In later revisions, we could drop them if we
:) prefer.
:)
:) >      + include/avr/timer.h (move to examples?)
:)
:) See above.  Many people think it's not useful in any way at all, and
:) it's sheer impossible to get it to a point where it could be useful
:) enough to save people some work.
:)
:) >      + include/avr/twi.h (move to examples?)
:)
:) Perhaps suitable for examples, but only together with a genuine
:) example (like an I²C EEPROM driver or something like that).

That and/or a I2C data flash driver sound like good examples to me.

:)
:) >      + 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).

:)
:) >      + include/avr/parity.h (move to examples?)
:)
:) I think that's a nice one to keep, but wouldn't mind moving it to
:) examples.  The only alternative i know of is from the BSD fortune
:) database:
:)
:) #define BITCOUNT(x)     (((BX_(x)+(BX_(x)>>4)) & 0x0F0F0F0F) % 255)
:) #define  BX_(x)         ((x) - (((x)>>1)&0x77777777)                    \
:)                              - (((x)>>2)&0x33333333)                    \
:)                              - (((x)>>3)&0x11111111))
:)
:)                 -- really weird C code to count the number of bits in a word
:)
:) Stripped down to 8-bit integers, it'll still yield some more code
:) than Marek's assembler version.
:)
:) >    * the mechanism behind include/avr/io*.h ???

This just needs a bit more explaining in include/avr/io.h. It's not clear
in that section of the dox that one and only one of the ioXXXX.h files is
included by <avr/io.h>.

:)
:) 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.  Doing so would allow us to remove some `magic numbers' from
:) a few library C files (like malloc(3) that needs to know about the
:) stack pointer).  Perhaps it'd even allow us to move the compilation of
:) the assembler (.S) library files away from faked -m<cpu> flags to
:) -m<architecture>.
:)
:) 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.

Much more than that and it is going to be some large patches.

:)
:) >    * merge chapter 3 from Rich Neswold's doc. Needs some rewriting to
:) >      update for newer tools. (explanation of start code)
:)
:) Hmm. :)

I can hear the gears spinning... ;-)

:)
:) >    * gcrt1.S
:)
:) Hmm.  Part of that is already explained in Ted's section about memory
:) sections.

Might need to discuss it's roll with the crt*.o files and the linker.
Sometimes you need to roll your own.

:)
:) >  - 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).

:)
:) >  - 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

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.)

:)
:) That's nothing to do before 1.0.  By now, we simply gotta live with
:) it.  One idea would be to move all the documentation away from the
:) header files into the respective source file, where we don't need to
:) care for potentially weird user macros that could shoot into our feet.

Agreed. It can wait.

Ted Roth