IOH: Getting started with IOH in custom projects (Keil MDK)

[#1]

Introduction

This page gives more detailed information on how to use the IOH libraries in custom projects when using the Keil MDK IDE. For more general information regarding using IOH libraries in custom project or for detailed instructions for LPCXpresso and IAR EWARM, 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_*_keil.lib) to the project

The first step is to configure the Keil project to link against the IOH library. This can be done by simply adding the .lib 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 tab 'C/C++'. Add the location of the header file to the 'Include Paths'.

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 keil project by opening the projects options and browsing to the 'Linker' tab. First uncheck the 'Use memory Layout from Target Dialog' checkbox, then add the file location to the 'Scatter file' box.

Following is the linker script used for the LPC11U37H, placing the IOH sections in the SRAM1 region (IOH SRAM):

LR_IROM1 0x00000000 0x00020000  {    ; load region size_region

  ER_IROM1 0x00000000 0x00020000  {  ; load address = execution address

   *.o (RESET, +First)

   *(InRoot$$Sections)

   .ANY (+RO)

      }

  RW_IRAM1 0x10000000 0x00002000  {  ; RW data

   .ANY (+RW +ZI)

  }

  RW_IRAM2 0x20004000 0x00000800  {  ; RW data

   .ANY (+RW +ZI)

  }

  RW_IRAM3 0x20000000 0x00000800  {  ; RW data

   .ANY(.ioh_text)

   .ANY(.ioh_constdata)

   .ANY(.ioh_bss)

   .ANY(.ioh_data)

  }

}

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 Keil startup file:

Reset_Handler   PROC

EXPORT  Reset_Handler             [WEAK]

IMPORT  SystemInit

IMPORT  __main

LDR     R0, =SystemInit

BLX     R0

LDR     R0, =__main

BX      R0

ENDP

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.