Wr i t i ng Dr i ver s f or eCOS
Appl i c at i on Not e
V1.0
Publication Release Date: Sep. 2008
Support Chips: Support Platforms:
NUC910A eCOS
NUC920A
NUC960A
NUC950A
NUC710A
NUC740A
NUC745A
APP-201-0011-eCOS
- 2 -
The information in this document is subject to change without notice.
The Nuvoton Technology Corp. shall not be liable for technical or editorial errors or omissions
contained herein; nor for incidental or consequential damages resulting from the furnishing,
performance, or use of this material.
This documentation may not, in whole or in part, be copied, photocopied, reproduced, translated,
or reduced to any electronic medium or machine readable form without prior consent, in writing,
from the Nuvoton Technology Corp.
Nuvoton Technology Corp. All rights reserved.
APP-201-0011-eCOS
- 3 -
Table of Contents
1. Introduction.............................................................................................................4
1.1. Library and Header Files....................................................................................................... 4
1.2. Debugging.............................................................................................................................. 6
1.3. Cache...................................................................................................................................... 6
1.4. Interrupt Service Routine....................................................................................................... 7
1.5. Critical Section Protection..................................................................................................... 7
2. Example....................................................................................................................8
2.1. Header Files........................................................................................................................... 8
2.2. Install ISR and DSR............................................................................................................... 8
2.3. ISR......................................................................................................................................... 9
2.4. DSR...................................................................................................................................... 10
3. Revision History ....................................................................................................11
APP-201-0011-eCOS
- 4 -
1. Introduction
eCOS is an open source, configurable, portable, and royalty-free embedded real-time operating system.
eCOS is provided as an open source runtime system provided by the GNU open source development tools.
Developers have full and unfettered access to all aspect of the runtime system.
We have ported eCOS kernel to Nuvoton ARM7 and ARM9 series chips platform. The eCOS kernel on
Nuvoton platform is build and linked under ARM ADS development environment. The eCOS kernel was
ported in the form of library.
This document will introduce how to write a device driver for Nuvoton ported eCOS kernel. It includes the
following sections:
Library and header files
Debugging
Cache
Interrupt service routines
Critical section protection
1.1. Library and Header Files
The Nuvoton port eCOS library is released with a kernel library (ex. NUC900_eCOS.a), a folder of
header files, and a scatter gather file (eCOS.scf) and a link configuration file (LDFLAGS.CFG).
The eCOS.scf and LDFLAGS.CFG are used to guide ARM ADS linker to link eCOS kernel and the
application. They do not concern with the implementation of device driver at all.
The device drivers should be finally implemented as a single device driver library. The eCOS library
(ex. NUC900_eCOS.a) will be linked with device driver libraries and application to come out the final
executable image.
The device driver access path must contain eCOS library header file path:
APP-201-0011-eCOS
Standard C library is supported in eCOS kernel library. Device driver is free to use these C library
APIs, such as memcpy, strcmp, printf, and so on. To include standard C library header files, the
device driver should use:
#i ncl ude " st di o. h"
#i ncl ude " st r i ng. h"
#i ncl ude " st dl i b. h"
instead of,
#i ncl ude <st di o. h>
#i ncl ude <st r i ng. h>
#i ncl ude <st dl i b. h>
Its recommended to include at least the following header files in your device driver:
#i ncl ude " dr v_api . h"
#i ncl ude " di ag. h"
#i ncl ude " wbt ypes. h"
#i ncl ude " wbi o. h"
- 5 -
APP-201-0011-eCOS
1.2. Debugging
The Nuvoton ported eCOS kernel library was build under ARM ADS. With a Multi-ICE, it can be
debugged under ARM AXD.
If you have no Multi-ICE, printing debug messages through UART port should be a good method.
The eCOS kernel support 115200 baud rate on UART0. You can create a hyper terminal on Windows
PC with 115200 baud rate, no parity check, 8 data bits, 1 stop bit, and no flow control.
To print debug messages though UART0, you can use diag_printf() or printf(). diag_printf() is polling
mode function, while printf() is interrupt mode function. diag_printf() should be useful for program
flow issue case. In time critical case, printf() may be useful. Its important to note that printf() cannot
be used in interrupt service routine, while diag_printf() can be used.
Another useful debugging function is cyg_current_time(). It will return the current kernel time ticks.
1.3. Cache
The eCOS kernel library does not turn on CPU cache. If desired, applications must turn on cache in
main() routine.
- 6 -
APP-201-0011-eCOS
- 7 -
For non-cacheable memory, just like non-OS case, eCOS device driver access the DMA memory with
non-cacheable bit mask. For example, on NUC910 platform, a memory address OR with 0x80000000
means access the memory with non-cacheable.
1.4. Interrupt Service Routine
Device driver uses eCOS kernel APIs to create interrupt, attach interrupt, and enable interrupt. This
involves three APIs: cyg_drv_interrupt_create(),cyg_drv_interrupt_attach(), and
cyg_drv_interrupt_unmask(). Please refer to eCOS kernel reference document.
The interrupt or interrupt group IRQ number is given as the first parameter of
cyg_drv_interrupt_create() and cyg_drv_interrupt_unmask().
Note that Nuvoton port eCOS library did not support group interrupts. If the device driver is working
on a device with group interrupt, for example NUC910 USB Host, it has to write corresponding AIC
group interrupt registers. For example, on NUC910, USB Host has group interrupt number 15. The
USB Host driver gives 15 as the IRQ number to cyg_drv_interrupt_create() and
cyg_drv_interrupt_unmask(). In addition, it also has to program AIC Interrupt Group Enable Control
Register to enable EHCI or OCHI interrupt.
Its not allowed to call eCOS kernel APIs in ISR. If device driver have to notify events or call kernel
APIs, it must create a DSR to do it. DSR is created with ISR at the same time in
cyg_drv_interrupt_create(). In ISR, if device driver has finished all jobs and does not need to call DSR,
it just returns with a CYG_ISR_HANDLED. Otherwise, it should return with a
CYG_ISR_CALL_DSR, and then eCOS kernel will call DSR.
Its very important to call cyg_drv_interrupt_acknowledge() on the end of ISR. Otherwise, eCOS
kernel will not raise any interrupt any more.
1.5. Critical Section Protection
Because eCOS is a multi-thread OS, its possible that device driver was invoked by different thread.
Most of the device drivers are not re-entrantable. For example, in SD driver, if driver did not make
any protections, a SD read processing may be intercepted by another threads SD read/write call.
There are several methods can be used to make protections. Mutexes, Semaphores, or Event Flags can
be used to protect driver critical sections.
APP-201-0011-eCOS
- 8 -
2. Example
This section is an example from NUC910 USB Host driver.
2.1. Header Files
#i f def ECOS
#i ncl ude " st di o. h"
#i ncl ude " st r i ng. h"
#i ncl ude " dr v_api . h"
#i ncl ude " di ag. h"
#i ncl ude " wbt ypes. h"
#i ncl ude " wbi o. h"
#el se
#i ncl ude <st di o. h>
#i ncl ude <st r i ng. h>
#i ncl ude " wbt ypes. h"
#i ncl ude " wbl i b. h"
#endi f
#i ncl ude " NUC900_r eg. h"
#i ncl ude " USB. h"
2.2. Install ISR and DSR
#def i ne I NT_NUM_USBH 15
cyg_i nt er r upt usbh_i nt er r upt ;
cyg_handl e_t usbh_i nt er r upt _handl e;
cyg_dr v_i nt er r upt _cr eat e( I NT_NUM_USBH, 8, 0, usbh_i sr , usbh_dsr ,
&usbh_i nt er r upt _handl e, &usbh_i nt er r upt ) ;
cyg_dr v_i nt er r upt _at t ach( usbh_i nt er r upt _handl e) ;
APP-201-0011-eCOS
- 9 -
cyg_dr v_i nt er r upt _unmask( I NT_NUM_USBH) ;
/ * USBH i nt er r upt gr oup enbal e */
out pw( REG_AI C_GEN, i npw( REG_AI C_GEN) | 0x300) ; / * bot h EHCI and OHCI */
2.3. ISR
st at i c cyg_ui nt 32 usbh_i sr ( cyg_vect or _t vect or , cyg_addr wor d_t dat a)
{
_I sI nUsbI nt er r upt = 1;
i f ( i npw( REG_AI C_GASR) & 0x100)
{
ehci _i r q( ) ;
i f ( _cal l _ehci _dsr )
{
cyg_dr v_i nt er r upt _mask( I NT_NUM_USBH) ;
cyg_dr v_i nt er r upt _acknowl edge( I NT_NUM_USBH) ;
r et ur n CYG_I SR_CALL_DSR;
}
el se
{
cyg_dr v_i nt er r upt _acknowl edge( I NT_NUM_USBH) ;
_I sI nUsbI nt er r upt = 0;
r et ur n CYG_I SR_HANDLED;
}
}
i f ( i npw( REG_AI C_GASR) & 0x200)
{
ohci _i r q( ) ;
i f ( _cal l _ohci _dsr )
{
cyg_dr v_i nt er r upt _acknowl edge( I NT_NUM_USBH) ;
cyg_dr v_i nt er r upt _mask( I NT_NUM_USBH) ;
r et ur n CYG_I SR_CALL_DSR;
APP-201-0011-eCOS
- 10 -
}
el se
{
cyg_dr v_i nt er r upt _acknowl edge( I NT_NUM_USBH) ;
r et ur n CYG_I SR_HANDLED;
}
}
r et ur n CYG_I SR_HANDLED;
}
2.4. DSR
st at i c voi d usbh_dsr ( cyg_vect or _t vect or , cyg_ucount 32 count ,
cyg_addr wor d_t dat a)
{
i f ( _cal l _ohci _dsr )
{
ohci _dsr ( ) ;
}
i f ( _cal l _ehci _dsr )
{
ehci _dsr ( ) ;
}
cyg_dr v_i nt er r upt _unmask( I NT_NUM_USBH) ;
}
APP-201-0011-eCOS
3. Revision History
Version Date Description
V1.0 Sept. 2008 Created
Important Notice
Nuvoton products are not designed, intended, authorized or warranted for use as components in
systems or equipment intended for surgical implantation, atomic energy control instruments, airplane
or spaceship instruments, transportation instruments, traffic signal instruments, combustion control
instruments, or for other applications intended to support or sustain life. Furthermore, Nuvoton
products are not intended for applications wherein failure of Nuvoton products could result or lead to
a situation wherein personal injury, death or severe property or environmental damage could occur.
Nuvoton customers using or selling these products for use in such applications do so at their own risk
and agree to fully indemnify Nuvoton for any damages resulting from such improper use or sales.
- 11 -
