How to write header files for Devices

Question

I am new to Embedded Programming, taking courses on it. And working with ATSTK600.

I am looking for some help on "how to write header files for Devices". Well, to be specific, what are the standard to be followed while writing header files like naming a register, etc (how to create .h & include, that I know).

Recently, I got an assignment to create a header file which I did, was on right track with some mistakes to be corrected before re-submission. While defining USART (made a mistake as this is very new to me)

#define USART_RX $0032 [which professor said is wrong because of $ sign #define will not work]. So is the following definition correct?

#define USART0_RX  32
#define USART0_UDRE  34
#define USART0_TX  36

Another thing is I defined ports as following, is this correct naming convention?

#define I_PINS_PORTA  0x20
#define DD_PORTA  0x21
#define DATA_PORTA  0x22

Well, somewhere I read the proper naming convention is #define BASE_ADDR_PORTA 0x20 but then what should be used for DD_PORTA & I_PINS_PORTA?

I was looking for some help on this over the web & came across this forum.

P.S. AM using C as a programming language.

Answer 1

One convention that you seemed to have followed for the UART, but not for PORTA is to put the system's name at the beginning of the name. It makes it easier to spot in code. So rather than

#define DD_PORTA 0x21

you might have

#define PORTA_DD 0x21

Using base addresses for devices that span a region of registers is also a good idea. To do this you would have:

#define PORTA_BASE 0x20

#define PORT_I       0x00
#define PORT_DD      0x01
#define PORT_DATA    0x02

#define PORTA_I     (PORTA_BASE + PORT_I)
#define PORTA_DD    (PORTA_BASE + PORT_DD)
#define PORTA_DATA  (PORTA_BASE + PORT_DATA)

This ends up being more typing but it helps you avoid mistakes later.

Different people and companies have their own preferences on how things like this are named and their interfaces, so there is no perfect answer.

As far as byte alignment -- I'm not sure what you are asking about it. The alignment of a memory address has to do with the remainder of the address divided by the alignment size (in bytes) being 0. Many systems can either only load and store at addresses evenly divisible by 2, 4, or 8 (or do so much more quickly to addresses that meet the requirement). Additionally, CPU cache performance is effected by alignment (having some needed memory only half in cache may be as bad as not having it at all).

Answer 2

This is similar to a question that came up a couple of days ago at http://stackoverflow.com/questions/3970876/define-vs-enums-for-addressing-peripherals. I think the accepted answer to that is the best way to go with defining the interfaces for embedded devices. I also recommend reading the Dan Saks column referenced in that answer.