naves-thiago/ehal

Runtime Embedded Hardware Abstraction Layer or simply eHAL

eHAL

Introduction

• eHAL stands for embedded hardware abstraction layer. The idea is to create an API as simple but versatile enought to run on many diferent MCUs 8, 16, 32 bits with diferent needs.

• This file contains a brief on the organization of the repository and some general info, take your time to read it. If there are any questions just ring a bell at http://groups.google.com/group/embedded_hal that surely someone will answer it.

Doc

The documentation of the implementation, that means (not tutorials) is provided by Doxygen. Doxygen is a way to embed documentation on the comments of source code. In .h on this case. More info at: http://www.stack.nl/~dimitri/doxygen/index.html

doxygen

After installing it, you can generate a local html or pdf version. For this: On the project root folder, a pages/ folder will be created with the doc. Again, this doc is intended to be a manual and API reference, not a tutorial.

How to help

• Providing any idea that may sound neat.

• Providing bug reports with details about version, MCU used, and the simplest possible test case that generated the bug.

How to make a huge contribution :)

• API specification. If you think the current API is doesn’t expose correctly the hardware please tell us how to improve it.

• Provide full or partial code/lib to a MCU of a new port.

• Create a testing suit for the the existing modules, specifying in which tests it failed.

• Create a new port.

New Port

• When creating a new port, a new supported platform, the user must implement the API specifyed in the .h from ehal folder and a MODULE_specific.h inside the port folder. Besides those rules, the implementation is free.

• The makefile Must implement: all, install and clean. Like in Make all, Make install and make clean. All of them will receive an argument MCU=name and F_CPU=freq. so a tipical call to the Makefile is ‘make -f Makefile.port MCU=name F_CPU=freq’.

General Thumb rule for Already writen Libs:

• If there are already .h files you’ve found on the net defining structs mapping the peripherals, you should go that way, just make sure it is FreeBSD compliant. If not check if it is possible to create such a mapping, if it is impossible, well…​ just do it the way you see fit.

  • As an example you can check for ehal/avr/port_internal.h for a mapping;

  • In the case of a third party lib that does it, use it directly. Like in the lpc17xx port.

  • There are cases it is just impossible to do a mapping, atmega8 uart is one of those. If this happens to you, just just do it without a mapping. The important thing here is to respect the API, the rest is just to make it as fast as possible.

• If you face a functionality that is not in the .h Create a function for it and put it in the _specific.h for the module. If possible ask why the functionality is not in the normal .h for a rationale and also for a possible inclusion.

• If you face some impossible task, like pulldown functions on a MCU that don’t have a pulldown, Don’t stub it, let the user know as soon as possible that some smelly thing happened. "sory mate, can’t do it" in compilation time is specialy important on embedded libs since its a pain to debug them.

Some Observations

• The Makefile generates .a files, that are suffix for static libs of gcc. You may use eHAL by linking your project against one of the generated .a files or copying the .c and .h files to your project and recompiling them there.

• The output is per MCU and is in the format: libehal-$(MCU)-$(F_CPU).a

• Good practices: The tabulation/identation is in TABs, not spaces and the coding style is the K&R. VIM users can add this to their ~/.vimrc:

au filetype c set cindent
au filetype c set incsearch
au filetype c set cinoptions=:0,p0,t0
au filetype c set cinwords=if,else,while,do,for,switch,case
au filetype c set formatoptions=tcqr

Note	If source code is in other format, please folow that code format including spaces and tabs.

Planned Architectures

Modules	cpu	port	uart	spi	i2c
avr	P	P	P	X	X
msp430	X	P	X	X	X
hcs08	X	X	X	X	X
8051	X	X	X	X	X
arm7	X	X	X	X	X
arm9	X	X	X	X	X
lpc17xx (cortex-m3)	X	P	X	X	X

V - for supported, P - for partial support (working on it.) X - no support. I - for impossible, not present on architecture.

Folders Organization:

EHAL

• Makefiles

• LICENCE

• README

• LOG

• Doxyfile

• dox/

  • main.dox

  • examples.dox

• ehal/

  • <headers>

  • portable/

    • queue_init.c

    • …​

    • pin_init.c

    • …​

  • avr/

    • port.c

    • twi.c

    • spi.c

    • …​

  • lpc21xx/

    • …​

  • lpc1768/

    • …​

  • msp430/

    • …​

  • …​