## Wednesday, November 19, 2008

### Writing portable Embedded code - Pin portability

EDIT: I've posted a C++ alternative using templates here.

Portability can be hard on embedded systems. The fact that we can code in C most of the time doesn't mean code is portable. Even worse, it means that you may have to rewrite many functions/macros in order to get the 'same' code to work on another platform/chip.

A nice approach is to write a simple yet powerful HAL (Hardware Abstraction Layer), sometimes called a driver. There are many protocols and peripherals whose functions are nearly the same between different vendors and chips, such as I2C, SPI, UART,MCI controllers. For SPI we would code at least three functions: SPI_init(), SPI_tx() and SPI_rx(). Actually SPI_tx() and SPI_rx() might be the same due to SPI's full duplex capability. There might be other functions or macros to control the chip select line. This approach works nice for standard peripherals, but we may need to access port pins individually to perform some task or communicate to a device by bit-banging.

Most LCD character displays work the same way and use the same protocol and control lines. A 'universal' C module for character LCD control sounds great, but pin compatibility should be addressed first, it's not attractive if we need to change tens of lines to port it.

We'll first define some useful string-concatenating macros:

#define    _CAT3(a,b,c)  a## b ##c#define    CAT3(a,b,c)   _CAT3(a,b,c)#define    _CAT2(a,b)    a## b#define    CAT2(a,b)    _CAT2(a,b)

The macros are called twice to ensure tokens are preprocessed as we want them. Kernighan and Ritchie's wonderful C book has good information about how that works. These macros can be defined in a global header file so they can be included whenever they're needed.

Basic operations on port pins include setting a pin as output or input, clearing a bit, setting a bit and reading it's value when configured as input. Given that I defined another header file which looks like this, specially made for the Philips LPC23xx family (ARM7):

/* Set bit */#define FPIN_SET(port,bit)  CAT3(FIO,port,SET) = (1<<(bit))#define FPIN_SET_(port_bit) FPIN_SET(port_bit)/* Clear bit */#define FPIN_CLR(port,bit)  CAT3(FIO,port,CLR) = (1<<(bit))#define FPIN_CLR_(port_bit) FPIN_CLR(port_bit)/* Set as input */#define FPIN_AS_INPUT(port,bit)  CAT3(FIO,port,DIR) &=~(1<<(bit))#define FPIN_AS_INPUT_(port_bit) FPIN_AS_INPUT(port_bit)/* Set as output */#define FPIN_AS_OUTPUT(port,bit)  CAT3(FIO,port,DIR) |= (1<<(bit))#define FPIN_AS_OUTPUT_(port_bit) FPIN_AS_OUTPUT(port_bit)/* when used as input */#define FPIN_ISHIGH(port,bit)  ( CAT3(FIO,port,PIN) &  (1<<(bit)) )#define FPIN_ISHIGH_(port_bit) FPIN_ISHIGH(port_bit)/* returns !=0 if pin is LOW */#define FPIN_ISLOW(port,bit)  (!( CAT3(FIO,port,PIN)& (1<<(bit)) ))#define FPIN_ISLOW_(port_bit) FPIN_ISLOW(port_bit)

Done this we can set bit 2.1 by ussuing FPIN_SET(2,1), or clear it by doing FPIN_CLR(2,1). The functions ending with an underscore are meant to be used when pin position is given as a #define macro, such as:

#define LEDA 2,1#define LEDB 2,1FPIN_AS_OUTPUT_( LEDA );FPIN_SET_( LEDA );FPIN_CLR_( LEDB );

I agree this may sound complicated, but by defining all these functions it's possible to manipulate all port pins easily and in a portable way. If we want to change the pin or port LEDA is using we only need to change it once, the macros will take care of it.

If we were to do the same on an AVR it's a question of changing the macros as shown below. Don't forget ports are named with letters (A,B,C,D...) rather than numbers.

/* Set bit */#define FPIN_SET(port,bit)  CAT2(PORT,port) |= (1<<(bit))#define FPIN_SET_(port_bit) FPIN_SET(port_bit)/* Clear bit */#define FPIN_CLR(port,bit)  CAT2(PORT,port) &=~(1<<(bit))#define FPIN_CLR_(port_bit) FPIN_CLR(port_bit)/* Set as input */#define FPIN_AS_INPUT(port,bit)  CAT2(DDR,port) &= ~(1<<(bit))#define FPIN_AS_INPUT_(port_bit) FPIN_AS_INPUT (port_bit)/* Set as output */#define FPIN_AS_OUTPUT(port,bit)  CAT2(DDR,port) |= (1<<(bit))#define FPIN_AS_OUTPUT_(port_bit) FPIN_AS_OUTPUT(port_bit)/* when used as input */#define FPIN_ISHIGH(port,bit)  CAT2(PIN,port) & (1<<(bit)))#define FPIN_ISHIGH_(port_bit) PIN_ISHIGH(port_bit)/* returns !=0 if LOW */#define FPIN_ISLOW(port,bit)  (!( CAT2(PIN,port) & (1<<(bit))) )#define FPIN_ISLOW_(port_bit) FPIN_ISLOW(port_bit)

Now the LCD routines are really portable. Minor changes might be needed if there are other pin registers to modify, but the basic pin functionality is covered by the macros defined above.

1. Hi CjB,

This is a great post about pin portability. Thanks for sharing it with us.

I'm trying to implement this to my project with lpc2368 but I have a problem with IO names. In my project for PORT0 and PORT1 I have to use IODIR0 and IODIR1 instead of FIO0DIR and FIO1DIR. I tried to implement this to my code by conditionally selecting CAT2 or CAT3 macros like :

#define _PORT_SEL(port) ((port) < (2) ? (CAT2(IODIR,port)) : (CAT3(FIO,port,SET)))

But each time I want to access my FIO4SET I'm getting error "IODIR4 is undefined". What can I do to implement this part?

2. Hi, I think the issue is that the macro you are calling is generating code for both CAT2(...) and CAT3(...), which is why you get that error at compile time. You need to find a way to generate the code for only one of them.

Is it possible to create some definitions such as

#define FIO0DIR IODIR0
#define FIO1DIR IODIR1

Would that work for you?

3. This comment has been removed by the author.

4. i, sorry for late response. I figured out that I can use FIO registers for PORT0-PORT1 if I set SCS register's bit0 to 1. It's done easily as this:

SCS |= 0x00000001; //Enable FIO registers for Port0 and Port1

So, now I successfully implemented your code to my project and it's working like charm. I got the portability I wanted thanks to you.

Just a little improvement, at least i think it is: Changing '=' to '|=' in FPIN_SET and FPIN_CLR functions would be better for not touching other bits when using these functions. Like:

/* Set bit */
#define FPIN_SET(port,bit) CAT3(FIO,port,SET) |= (1<<(bit))
#define FPIN_SET_(port_bit) FPIN_SET(port_bit)

/* Clear bit */
#define FPIN_CLR(port,bit) CAT3(FIO,port,CLR) |= (1<<(bit))
#define FPIN_CLR_(port_bit) FPIN_CLR(port_bit)