Introduction
This page gives more detailed information on how to use the IOH libraries in custom projects when using the IAR EWARM IDE. For more general information regarding using IOH libraries in custom project or for detailed instructions for LPCXpresso and Keil, visit IOH: Getting started with IOH in custom projects.
Ready-to-use examples can be found at the main I/O Handler page.
Note: This guide assumes the IOH I2S library is to be added to a project, hence the 'I2S' references. For other IOH libraries, 'I2S' should be replaced with the library name.
1. Add the IOH library (ioh_*_iar.a) to the project
The first step is to configure the IAR project to link against the IOH library. This can be done by simply adding the .a file to the project.
2. Add the path where the library's header file resides to the project’s include path
The next step is to add the file location of the library's header file to the include path of the project. Open the project options and browse to the category 'C/C++ Compiler', then to the tab 'Preprocessor'. Add the location of the header file to the 'Additional include directories'.
3. #include the IOH header file in the source code of the application
The IOH header file must be included in the source code of the project (e.g. main.c) by using the following preprocessor directive:
#include "IOH_I2S.h"
4. Configure the linker to place the IOH related sections in the IOH SRAM
All IOH parts have an SRAM region reserved for I/O Handler. When starting IOH, usually by calling the library's init() function, I/O Handler expects this memory region to be loaded with the IOH data provided by the IOH library. This means this data must be stored in Flash and copied to the IOH SRAM upon startup. A convenient way to do this, is by using scatter loading. With scatter loading, the linker and c-library are instructed to program certain data sections (IOH data) into Flash, and copy it to the specifed region (IOH SRAM) upon start up. This requires a linker script.
The linker script can be added to the IARproject by opening the projects options and browsing to the 'Linker' category. First check the 'Override default' checkbox, then add the file location to the 'Linker configuration file' box.
Following is the part of the linker script used for the LPC11U37H, responisble for placing the IOH sections in the SRAM1 region (IOH SRAM):
define symbol __IOHRAM_start__ = 0x20000000;
define symbol __IOHRAM_end__ = 0x200007FF;
define region IOHRAM_region = mem:[from __IOHRAM_start__ to __IOHRAM_end__];
initialize by copy { section .ioh_text };
initialize by copy { section .ioh_constdata };
initialize by copy { section .ioh_data };
place in ROM_region { section .ioh_text_init };
place in ROM_region { section .ioh_constdata_init };
place in ROM_region { section .ioh_data_init };
place in IOHRAM_region { rw section .ioh_text};
place in IOHRAM_region { rw section .ioh_constdata };
place in IOHRAM_region { rw section .ioh_data };
place in IOHRAM_region { rw section .ioh_bss };
5. Enable the IOH SRAM (SRAM1) before C-library initialization
The copying of data from the 'load region' to the 'execution region' when using scatter loading (explained above) is executed by the c-library just before main() gets called. It's important that both regions are enabled when the copying is initiated. After power-on, the IOH SRAM on the LPC11E/U37H is disabled (clock disabled in the SYSAHBCLKCTRL register), so it must be enabled before the scatter loading is initiated.
The right place (assuming the CMSIS standard is followed) to enable the IOH SRAM, is in the SystemInit function. SystemInit() is called just before the C-enviroment is initialized as can been seen from the following snippet from the LPC11xx IAR startup file:
PUBWEAK Reset_Handler
SECTION .text:CODE:REORDER(2)
Reset_Handler
LDR R0, =SystemInit
BLX R0
LDR R0, =__iar_program_start
BX R0
Therefore the SystemInit() function should contain the code for enabling the IOH SRAM block, e.g. by adding the following line to the SystemInit() function (assuming the LPC11E/U37H):
LPC_SYSCON->SYSAHBCLKCTRL |= (1<<26);
6. Interact with IOH via the library's API
The final step is to interact from the application with IOH. This can be done through the library's API. Each library comes with an application note explaining how to use the library and what data structures and functions are available, and with one or more application examples showing how to use the library. This application note and application example provide an easy way to get started. They can be downloaded from the main I/O Handler page.
