[avr-libc-dev] [RFC] Conditional poisoning of deprecated items

[Weddington, Eric]

Hi All,

We haven't had an RFC (Request For Comments) in a long time.

I've been going through a bunch of the I/O header files recently for one of the 
bug reports/feature requests. I noticed, and also remembered, that we have an 
awful lot of deprecated items, e.g. old ISR vector names.

Deprecated items, usually, are supposed to be eventually removed from a project 
over time. However, we have users who tend to continue to use deprecated items, 
blissfully unaware of the fact that they are deprecated and *might* be 
eventually removed (e.g. the sbi/cbi macro debacle of a few years back).

A lot of this problem falls on us. We don't really document the deprecated 
items very well, if at all. And we haven't let the user easily find out, via 
the toolchain, which items are deprecated so they can go change their source 
code. We need to change this so we can eventually clean up avr-libc.

GCC has a #pragma that will "poison" identifiers which will cause a hard error 
if they are used in a program.

For example, this source code:

-----------------------------------------
#define __AVR_LIBC_DEPRECATED_DISABLE__

#define xyz 3

#if defined(__AVR_LIBC_DEPRECATED_DISABLE__)
#pragma GCC poison xyz
#endif


int main(void)
{
    volatile int a;
    
    a = xyz;
    
    return 0;
}
-----------------------------------------

Will return this output:

+ avr-gcc -mmcu=atmega128 -Os -save-temps -c test.c -o test.o
test.c:7:20: warning: poisoning existing macro "xyz"
test.c:15:9: error: attempt to use poisoned "xyz"


A few things to point out:

- The poisoning happens *after* the macro definition. This will allow the 
warning to happen about the existing macro definition. The error will only 
occur on usage of the macro.

- The poisoning happens only on a conditional define. The 
__AVR_LIBC_DEPRECATED_DISABLE__ must be defined in the user's source code, 
preferably before any system (avr-libc) header files are included.

I propose that this poisoning be done in avr-libc header files, as needed, 
using such a conditional define. The default would be to have the poisoning 
OFF, like above, which allows all deprecated items exist as before. A user 
would define the symbol above to turn on the poisoning of all deprecated items 
in avr-libc, for the purpose of discovering and fixing all deprecated items in 
their application code.

I'm not stuck on the name of the conditional define to use. I'm open to better 
ideas.

Thoughts?

Eric Weddington