[avr-libc-dev] Re: [avr-gcc-list] Re: What Happened to the sbi() and cbi() Macros????

[Kevin Neff]

On Sun, 30 Jan 2005, E. Weddington wrote:

> I'm certainly not against having a non-confrontational discussion about 
> this, so let's revisit the subject. 

Good.  Thanks.

> I would like to create an API that can be used to operate on bits. I 
> propose that this would be a new header, <avr/bit.h>. In this header, 
> would be macros that would set, clear, toggle, read, and test bits in a 
> variable. These macros would also be defined to work on variables of 
> size 8 bit, 16 bit and 32 bit. For example:
> ----------------------------------------------------------------
> #include <inttypes.h>
> #define bit_set_8(var, mask)   ((var) |= (uint8_t)(mask))
> #define bit_clear_8(var, mask)   ((var) &= (uint8_t)~(mask))
> #define bit_toggle_8(var, mask)   ((var) ^= (uint8_t)(mask))
> #define bit_read_8(var, mask)   ((var) & (uint8_t)(mask))
> 
> #define bit_set_16(var, mask)   ((var) |= (uint16_t)(mask))
> #define bit_clear_16(var, mask)   ((var) &= (uint16_t)~(mask))
> #define bit_toggle_16(var, mask)   ((var) ^= (uint16_t)(mask))
> #define bit_read_16(var, mask)   ((var) & (uint16_t)(mask))
> 
> // 32 bit versions here
> 
> // Shorter named versions for the common operation.
> #define bit_set(var, mask)   bit_set_8(var, mask)
> #define bit_clear(var, mask) bit_clear_8(var, mask)
> #define bit_toggle(var, mask) bit_toggle_8(var, mask)
> #define bit_read(var, mask) bit_read_8(var, mask)
> ----------------------------------------------------------------
> 
> There are several reasons why I think this would be useful:
> - Doing bit operations with the C language bit operators is confusing to 
> most newbies. This usually has to be explained again and again. These 
> macros make it easier for newbies.
> - It's makes it easier to read what operation is happening rather than 
> trying to remember the bit operations themselves.

I have trouble remembering things that I don't use regularly, so I don't
find this argument particularly convincing.

I am against intentionally making tools hard to use for beginners but I
think that the "improvements" should have technical merit beyond making
things easier for newbies.

> - The typecasts are in there to workaround the C language Standard of 
> promoting the operands of bit operaters to ints, which are 16 bits for 
> the AVR (see the avr-libc FAQ for more discussion of this). If these 
> macros are used, then users don't have to remember to do the typecasts, 
> which should, in theory, help with the size of their code.
 
A good point... but isn't there a way to do this during the build process?

> I would also like to propose two other macros for this file:
> 
> #define BIT(x)   (1 << (x))
> #define LONGBIT(x)   ((uint32_t)1 << (x))
> 
> Yes, the BIT() macro is the same as _BV(). The _BV() macro is confusing 
> in two ways: one has to remember that "BV" stands for Bit Value. The 
> name BIT is slightly more descriptive. And _BV() has a leading 
> underscore, which technically is supposed to be reserved for the 
> "implementation" according to the C Standard (in this case the library). 
> Having to type out the underscore is annoying. I feel that it's easier 
> to just write out "BIT".
 
As an alternative to this suggestion, I would advocate adding some simple
bit value macros.  They are fewer characters to type and do not require
special treatement of larger words. 

  #define B0 0x01
  #defind B1 0x02
   ...

--Kevin Neff