OSE Epsilon for ARM

Board Support Package

ARM BSP

Users Manual

Enea Embedded Technology

Copyright
Copyright (C) 2005 by Enea Embedded Technology. All rights reserved. No part of this publication may be reproduced, transmitted, stored in a retrieval system, or translated into any language or computer language, in any form or by any means, electronic, mechanical, optical, chemical or otherwise, without the prior written permission of Enea Embedded Technology. If, however, your only means of access is electronic, permission to print one paper hard copy is hereby granted. The software described in this document is furnished under a licence agreement or a non-disclosure agreement. The software may be used or copied only in accordance with terms of agreement.

Disclaimer
Enea Embedded Technology makes no representations or warranties with respect to the contents hereof and specifically disclaims any implied warranties of merchantability or fitness for any particular purpose. Further, Enea Embedded Technology reserves the right to revise this publication and to make changes from time to time in the contents hereof without obligation to Enea Embedded Technology to notify any person of such revision or changes.

Trademarks

ARM BSP

OSE is a registered trademark of Enea Embedded Technology.

EArmBspUG 4.6
OSE /OSE Epsilon for ARM - BSP Users Manual

Content
1 Introduction 2 BSP Concept
2.1 Board setup 8 2.2 Timer for BSP 8 2.3 OSE BIOS for BSP 8 2.3.1 biosInstall 9 2.3.2 biosOpen 9 2.3.3 biosCall 9 2.3.4 biosInit 9 2.4 Device drivers for BSP 9

5 7

Board Support Package

3 Device Driver
3.1 Device Driver usage 12 3.2 Device Driver Functions 12 3.3 Device Driver Public Functions 13 3.3.1 <deviceName>_biosentry 14 3.3.2 <deviceName>_functions 15 3.3.3 <deviceName>_init 16 3.3.4 <deviceName>_intr 16 3.4 Device Driver Static Functions 17 3.4.1 ddDevClass 18 3.4.2 ddDevInfo 19 3.4.3 ddUnitInfo 20 3.4.4 ddOpen 21 3.4.5 ddStart 23 3.4.6 ddClose 24 3.4.7 ddGetConf 24 3.4.8 ddSetConf 25 3.4.9 ddWrite 27 3.4.10 ddRead 28 3.4.11 ddSimInt 29 3.4.12 ddAbortWrite 30 3.4.13 ddAbortRead 31 3.5 Device Driver Client Call Back Functions 32 3.5.1 dcAlloc 33 3.5.2 dcFree 33 3.5.3 dcHandleEX 33 3.5.4 dcHandleRX 34 3.5.5 dcHandleTX 35

11

4 Supported Boards
4.1 ARM Evaluator-7T Board 38 4.1.1 Board Setup 40 4.1.1.1 Files 40 4.1.1.2 Processes 40 4.1.1.3 Start Handlers 40

37

Users Manual / 4.6

Content 3

ARM BSP

4.1.1.4 Configuration 40 4.1.2 ELDM Serial Driver 41 4.1.2.1 Files 41 4.1.3 On-Chip PPP Serial Driver 41 4.1.3.1 Files 41 4.1.3.2 Processes 41 4.1.3.3 Start Handlers 41 4.1.3.4 Configuration 41 4.1.4 LED Driver 42 4.1.4.1 Description 42 4.1.4.2 Files 42 4.2 Atmel AT91EB01 43 4.2.1 Board Setup 43 4.2.1.1 Files 43 4.2.1.2 Processes 44 4.2.1.3 Start Handlers 44 4.2.1.4 Configuration 44 4.2.2 ELDM Serial Driver 44 4.2.2.1 Files 44 4.2.3 LED Driver 44 4.2.3.1 Files 44 4.3 Atmel AT91EB55 45 4.3.1 Board Setup 45 4.3.1.1 Files 45 4.3.1.2 Processes 46 4.3.1.3 Start Handlers 46 4.3.1.4 Configuration 46 4.3.2 ELDM Serial Driver 46 4.3.2.1 Files 46 4.3.3 LED Driver 46 4.3.3.1 Files 46

Index

47

4 Content

Users Manual / 4.6

1 Introduction
OSE Epsilon for ARM includes Board Support Packages (BSPs) for numerous boards in order to simplify development and decrease start-up times. The BSP includes various general components such as timer support (where needed by the kernel), interrupt handling and device drivers. All BSPs contain at least one serial driver and, for boards having an ethernet controller, a corresponding ethernet driver. All drivers included in the BSP are delivered in full source code and must be compiled by the customer. When writing a BSP for a board not supported by OSE, it is recommended to carefully study the header files of the delivered BSP. This manual is primarily intended for system designers and application developers who are implementing board setup and device drivers or writing applications that use the BSP. To be able to follow the configuration syntax in this manual the reader should have knowledge of C programming. This manual describes:

ARM BSP

BSP Concept on page 7 gives an introduction into OSE Epsilon for ARM, BSP concept. Device Driver on page 11 gives a detailed description of the OSE Epsilon for ARM device driver architecture. Supported Boards on page 37 describes the boards supported by the OSE Epsilon for ARM board support package.

For specific information about the actual release of OSE Epsilon for ARM, see the Release Notes. For applications based on the OSE Epsilon for ARM system, the reader is referred to the OSE Epsilon for ARM, kernel manuals. Reading these manuals will give an understanding of realtime system design in general and the different mechanisms of the OSE concept in particular. If you are not familiar with the OSE Epsilon for ARM kernel, it is recommended that the OSE Epsilon for ARM Kernel product manuals be read first.

Users Manual / 4.6

Introduction 5

ARM BSP
6 Introduction

Users Manual / 4.6

2 BSP Concept
The OSE Epsilon for ARM BSP concept is designed to give software engineers a head start for developing software for standard hardware, as well as to provide a platform for those who will write a BSP for hardware that is not currently supported by OSE Epsilon for ARM. To create a BSP with OSE Epsilon for ARM, you need to include four system components described in the following sections:

Board setup on page 8describes board setup and initialization, executed normally in the context of the OSE Epsilon for ARM start handlers. These functions are called before the kernel has started. Timer for BSP on page 8 describes the timer for boards where there is no internal system timer implemented in the CPU. OSE BIOS for BSP on page 8 describes the OSE BIOS concept Device drivers for BSP on page 9

Board Support Package

All of these components are necessary to start OSE and to support I/O for on-board devices. Since the BSP is delivered as source files, the application writer is given full control to over the code to customize the BSP if so desired.

Users Manual / 4.6

BSP Concept 7

2.1 Board setup

This is some of the first code executed after a board reset. The purpose of this code is to bring the board to a state where OSE can access memory and devices. On most boards this includes setting up caches/memory, initiating the interrupt controller, masking all interrupts and initiating the on-board devices. This part of a BSP is highly board dependent.

2.2 Timer for BSP

When the OSE kernel has started, it requires a system timer in order to do pre-emptive multitasking and handle delays. Some CPUs have their own internal system timers, which OSE supports. Where such isnt present, the BSP sets up a timer that generates an interrupt at a regular time interval, called the system tick. When the interrupt is generated, the interrupt service routine makes a system call to tick().

2.3 OSE BIOS for BSP

The OSE BIOS is a mechanism that makes it possible to register software modules with the kernel that can later be accessed by the user. In the BSP concept the BIOS is used to attach device drivers to the kernel at start-up. A BIOS is needed to let the device drivers execute in supervisor mode, thus gaining full access to the CPU, even if the user application runs in user mode. When using the BIOS calls, a transfer to supervisor mode is done. If the calling application process itself is running in supervisor mode, it can call device driver functions directly, thus gaining performance. The OSE BIOS is totally implemented outside the kernel, and the user is free to use it or not. It is however important to note at this point that some OSE Epsilon products, like the INET TCP/IP stack, use the BIOS concept. Device drivers for INET must therefore be designed accordingly. The BIOS mechanism can be described as follows: The BIOS architecture is built with a table in which each device driver installs itself. Each element in the table consists of a string containing the device name and a pointer to the drivers entry point.
biosInit: biosInstall: biosOpen: biosCall: Clear the table content Append a new driver to the table Search for the corresponding driver in the table and return the index Call the drivers entry function.

ARM BSP

The bios functions are defined in the files bios.c and bios.h placed in the source and include directory of the bsp delivery.

8 Board setup

Users Manual / 4.6

2.3.1 biosInstall
BiosInstall is used by a BSP to install device drivers into the BIOS. A string is used as an identifier. This identifier should be used when later accessing the driver. A call to biosInstall has the following appearance:
/* Install device driver for DEC21140 in BIOS. */ long err; err = biosInstall( "DEC21140", DEC21140_biosentry, 0); if (err != 0) error(OSE_BSP_EBIOSINSTALL_FAILED);

Board Support Package

The first parameter to biosInstall is the identifier string and the second is an entry point (a function) that the BIOS should use when calling the driver. The last parameter is a flag that specifies if a client executing in user mode is allowed to open the driver and that this driver supports the OSE device driver specifications. biosInstall may only be called by supervisor processes.

2.3.2 biosOpen
When an application wants to use the driver, it must first obtain a handle. A call to biosOpen will return a handle. The call can look like this:
handle = biosOpen("DEC21140");

This call returns a handle to the driver.

2.3.3 biosCall
The next step is probably to access the driver. This is done through calls to biosCall:
err = biosCall (handle, DEVICE_FCOPEN, dco.unit, DEVICE_TSERIAL_PACKET, &dco, &dcf, &isri);

The call to biosCall takes at least two parameters, the first is the handle returned by biosOpen and the second is the function code for the function you want the driver to perform. The rest of the parameters are passed as parameters to the drivers function.

2.3.4 biosInit
biosInit() sets up the BIOS module.

2.4 Device drivers for BSP

A device driver consists of a group of functions used to implement a physical or virtual devices functionality for the benefit of a higher level device client (typically an application process or the OS itself). A BSP usually has a serial device driver and an ethernet device driver. For a detailed description of the OSE device driver architecture, see Device Driver on page 11.

Users Manual / 4.6

Device drivers for BSP 9

ARM BSP
10 Device drivers for BSP

Users Manual / 4.6

3 Device Driver
A device driver consists of a group of functions used to implement a physical or virtual devices functionality for the benefit of a higher level device client (typically an application process or the OS itself). A BSP usually has a serial device driver and an ethernet device driver. All OSE drivers share a standardized device driver interface, plus a device type specific interface add-on. The functions in all network device drivers (e.g. serial and ethernet) share the same syntax, and even the same semantics if used in automatic mode. Please consult the source code of the delivered device driver files to get information about using the device driver functions. See also:

Device Driver usage on page 12 Device Driver Functions on page 12 Device Driver Public Functions on page 13 Device Driver Static Functions on page 17 Device Driver Client Call Back Functions on page 32

ARM BSP

Users Manual / 4.6

Device Driver 11

3.1 Device Driver usage

In order to use the device drivers, you must first compile them since they are delivered as source code. Note that many of the interesting settings are configurable at runtime. Once compiled, the module can be linked together to your system. To register the driver module, you must install it in BIOS by issuing a biosInstall(<driver_name>) call. Example:
long err = biosInstall(<driver_name>,<driver_name>_biosentry, <bios_install_flags>); if(err != 0) error(OSE_BSP_BIOSINSTALL_FAILED);

The device driver modules can now be opened with a call to biosOpen() with the devicename as argument. Example:
long handle = biosOpen(<driver_name>); if (handle != 0) /* device opened. */

ARM BSP

The biosCall function is then used together with the function codes and error codes specified in the file, device.h. Example:
int err = biosCall(handle, DEVICE_FCOPEN, <parameters>); if (err == DEVICE_SUCCESS) /* Open call was successful. */

3.2 Device Driver Functions

Technically the device driver is just a collection of OS independent functions used to handle the device hardware. The device driver functions can be divided into two categories: public and static functions. Public functions can be called directly using the function symbol and some may be called through the BIOS. In order not to get symbol collisions the public functions must be uniquely named. As a result, the public functions are prepended with the name of the device driver followed by an underscore. For example, the function <deviceName>_functions() would be named Am79c970a_functions() for the AMD 79c970a Ethernet driver. Static functions can only be called through the BIOS or, if the device client executes in supervisor mode, a function pointer received from the public function <deviceName>_functions().

12 Device Driver usage

Users Manual / 4.6

3.3 Device Driver Public Functions

There are four types of public functions in the device driver (all with the prefix <deviceName> which should be replaced by the name of the device). The public functions are used in the initialization of the driver, interfacing to the BIOS and as interrupt service routines. Please note that though there are only four types of public functions there may be multiple <deviceName>_i<unit> functions. For a detailed description of the types of public functions, see:

<deviceName>_biosentry on page 14 <deviceName>_functions on page 15 <deviceName>_init on page 16 <deviceName>_intr on page 16

The two functions <deviceName>_init() and <deviceName>_functions() must be directly accessible or the device driver could only be used through the BIOS. The ISR entry point <deviceName>_i<unit> function(s) must be public for those operating systems that cannot dynamically create interrupt processes. Finally, the <deviceName>_biosentry() must also be directly accessible since the symbol is referenced in order to install the driver with the BIOS biosInstall(). Once the device driver is installed it can be initialized by calling <deviceName>_init() through the BIOS.

ARM BSP

Users Manual / 4.6

Device Driver Public Functions 13

3.3.1 <deviceName>_biosentry
Syntax long <deviceName>_biosentry (long arg1, long, arg2, long, arg3, long, arg4, long, arg5, long, arg6, long, arg7,);

Description

<deviceName>_biosentry() is the device driver BIOS handler entry point and is used to access the static functions. The first argument, arg1, is referred to as the function code and contains a constant specifying which function to call in the device driver. The remaining six arguments, arg2-arg7, are used to pass the arguments to the device driver function. <deviceName>_biosentry() must support the following device driver function codes: Tags with a value of 0x4000_0000 and up to 0x7FFF_FFFF are reserved for customer additions.
Function code DEVICE_FCDEVCLASS ddDevClass <deviceName>_init <deviceName>_functions ddDevInfo ddUnitInfo ddOpen ddStart ddClose ddGetConf ddSetConf ddWrite ddRead ddSimInt ddAbortWrite ddAbortRead Function

ARM BSP

DEVICE_FCINIT DEVICE_FCFUNCTIONS DEVICE_FCDEVINFO DEVICE_FCUNITINFO DEVICE_FCOPEN DEVICE_FCSTART DEVICE_FCCLOSE DEVICE_FCGETCONF DEVICE_FCSETCONF DEVICE_FCWRITE DEVICE_FCREAD DEVICE_FCSIMINT DEVICE_FCABORTWRITE DEVICE_FCABORTREAD

Parameters

arg1 arg2-arg7

Device driver function code (DEVICE_FCXXX) signifying which device driver function is being called. These six arguments are parameters to the specified device driver function.

14 Device Driver Public Functions

Users Manual / 4.6

Return Value Errors Restrictions

The return value of the device driver or DEVICE_EUNKNOWN if the BIOS handle or function code was invalid. DEVICE_EUNKNOWN Invalid BIOS handle or function code (arg1) is unknown. None.

3.3.2 <deviceName>_functions
Syntax const structs DdFuncs <deviceName>_functions (void);

Description

<deviceName>_functions() is used to retrieve a set of function pointers from the device driver in order to access the static functions directly. The return value is a pointer to a structure containing pointers to the static functions.
struct DdFuncs { DevErr(*ddDevInfo) (DevTag * tagdList); DevErr(*ddUnitInfo) (U32 unit, DevTag * taguList); DevErr(*ddOpen) (U32 unit, U32 deviceType, void *dcObjects, const structDcFuncs * dcFuncs, struct ISRInfo *isrInfo); DevErr(*ddStart) (U32 unit); DevErr(*ddClose) (U32 unit); DevErr(*ddGetConf) (U32 unit, DevTag * tagcList); DevErr(*ddSetConf) (U32 unit, DevTag * tagcList); DevErr(*ddWrite) (U32 unit, void *buf, U32 * buflen); DevErr(*ddRead) (U32 unit, void *buf, U32 * buflen); DevErr(*ddSimInt) (U32 unit); DevErr(*ddAbortWrite) (U32 unit); DevErr(*ddAbortRead) (U32 unit); };

ARM BSP

Note that the device client must be in supervisor mode not only when calling <deviceName>_functions() but also to directly call any of the device driver functions. However, if the BIOS interface is used the device client does not need to be in supervisor mode since the process enters supervisor mode during the BIOS call. Parameters Return Value Errors Restrictions None. A pointer to a structure containing device driver function pointers. None. None.

Users Manual / 4.6

Device Driver Public Functions 15

3.3.3 <deviceName>_init
Syntax void <deviceName>_init (void);

Description

<deviceName>_init() initializes the hardware and disables the device hardware interrupts for the unit(s) that the driver supports. <deviceName>_init() is normally called in the boot phase (start handler) when interrupts are disabled. At a later stage, external interrupts will be enabled in the cpu, so its important to make sure all potential interrupt requesters have been disabled. Note that this function initializes all the units, i.e. it only has to be called once per driver. Calling <deviceName>_init() an additional time will completely and instantly reset the driver, i.e. any memory allocated by open units is lost. Therefore, repeated calling of this function is only useful for complete system reboots. This function could also be used to clear and set necessary global device driver variables. Typically <deviceName>_init() may only initialize variables and stop ongoing interrupts and DMA transfers. No other device driver functions may be used before this function has been called.

Parameters Return Value Errors

None. None. None. Since the driver is not opened, no device client call-back functions may be used.

ARM BSP

Restrictions

3.3.4 <deviceName>_intr
Syntax void <deviceName>_intr (void);

Description

<deviceName>_i<unit>() is the device driver interrupt service routine. Device drivers that are going to be used in interrupt mode must have one <deviceName>_intr() function per interrupt vector the hardware can generate interrupt on. The number of ISRs depends on the hardware and number of units that the driver supports. Some devices have one vector per unit and others have only one vector servicing multiple units. The receive and transmit done interrupt may have the same (combined) interrupt service routine or different, again depending on the hardware. None. None. None. None.

Parameters Return Value Errors Restrictions

16 Device Driver Public Functions

Users Manual / 4.6

3.4 Device Driver Static Functions

The static functions form the main body of the device driver. The reason they are called static is because they cannot be accessed directly. In order to call a static device driver function the client has to either use the BIOS or function pointers retrieved by the public function <deviceName>_functions(). If the device client calls the static functions directly it has to execute in supervisor mode to be able to access the memory properly. For a detailed description of each static function, see:

ddDevClass on page 18 ddDevInfo on page 19 ddUnitInfo on page 20 ddOpen on page 21 ddStart on page 23 ddClose on page 24 ddGetConf on page 24 ddSetConf on page 25 ddWrite on page 27 ddRead on page 28 ddSimInt on page 29 ddAbortWrite on page 30 ddAbortRead on page 31

ARM BSP

Static functions are declared in the DdFuncs structure (see <deviceName>_functions on page 15) except for ddDevClass(), which verifies that a BIOS module is a device driver according to this API. Two functions, ddDevInfo() and ddUnitInfo() are used to retrieve information about the device driver. A device driver is opened with ddOpen() and started with ddStart(). The driver can only be stopped by closing it with ddClose(). Before starting a driver, it may have to be configured with ddGetConf() and ddSetConf(). Five functions deal with reading and writing data, most are only needed in manual mode. ddWrite() is used in all modes to write data to the link. In manual mode, ddRead() has to be used to request incoming packets. ddSimInt() is used in polled mode to simulate an interrupt since no interrupts are generated by the device. Finally, input and output may be aborted with ddAbortRead() and ddAbortWrite() respectively.

Users Manual / 4.6

Device Driver Static Functions 17

Static functions are usually executed in the device client's context, except for the code, including call-back functions (e.g.dcHandleTX()) that is executed in the device driver's interrupt context. None of the static functions may be called unless the device driver has been initialized with <deviceName>_init() first. Furthermore, the device client should call the device driver functions with interrupts enabled in the cpu. The static functions can disable interrupts internally at the source if needed.

3.4.1 ddDevClass
Syntax U32 ddDevClass(void);

Description

This function is used to verify that a BIOS module is a device driver compliant with this API. ddDevClass() returns a constant which was initially set to a random value. The return value should be compared to the current DEVICE_CLASS constant (defined in device.h). None. The DEVICE_CLASS constant. None. This function is only accessible using biosCall().

Parameters Return Value Errors Restrictions

ARM BSP
18 Device Driver Static Functions

Users Manual / 4.6

3.4.2 ddDevInfo
Syntax DevErr ddDevInfo (DevTag *tagdList);

Description

ddDevInfo() is used to retrieve information about a device driver. The caller must specify which information should be retrieved by supplying corresponding tags. Each tag specifies which option to retrieve and is followed by extra storage for the return value of the option, a tag parameter. tagdList points to an array of tags, which must be terminated with the terminator tag DEVICE_TAGEND. Valid device information tags: DEVICE_TAGD_NAME Return the device name in the specified buffer. The buffer must be minimum 32 characters large. DEVICE_TAGD_VERSION Returns the device version constant DEVICE_VERSION which is used to identify which interface version the driver supports. DEVICE_TAGD_UNITLO

ARM BSP

Returns the lowest numbered unit. DEVICE_TAGD_UNITHI Returns the highest numbered unit. DEVICE_TAGD_OPENALL Returns 1 if the client must open all units at once. This might be needed by some old hardware where the units cannot be operated separately. If the units may be opened independently of each other then 0 is returned. DEVICE_TAGERRPTR This tag's parameter is a pointer to a DevTag variable that will contain a pointer to the tag that was unknown or had an invalid value. If no invalid tag was detected in the tag list, the variable will be untouched. DEVICE_TAGEND This tag signifies the end of the taglist. Tags with a value of 0x80000000 and above are reserved for customer additions. Parameters Return Value tagdList Pointer to an array of tags.

DEVICE_SUCCESS if device information taglist was successfully parsed else an error code.

Errors

DEVICE_EINVALID_TAG

Users Manual / 4.6

Device Driver Static Functions 19

Unknown device information tag. If an error pointer was supplied by the tag DEVICE_TAGERRPTR it's value is set to point to the erroneous tag field. Restrictions None.

3.4.3 ddUnitInfo
Syntax DevErr ddUnitInfo (U32 unit, DevTag * tagdList);

Description

ddUnitInfo() is used to retrieve information about a specific device driver. The caller must, in addition to the unit number, specify which information should be retrieved by supplying corresponding tags. Each tag specifies which option to retrieve and is followed by extra storage for the value of the option. taguList points to an array of tags, which ends with the terminator tag - DEVICE_TAGEND. Valid unit information tags: DEVICE_TAGU_DEVTYPES Returns a U32 with the supported driver type (DEVICE_TXXX). This option is used to identify that the unit is a driver of the desired type. If the unit supports more than one device type these types will be returned in different tags.

ARM BSP

DEVICE_TAGU_INUSE Returns a non zero value if the unit is open else zero. A unit may not be opened again without closing it first. DEVICE_TAGU_MAX_MTU Return the hardware limitation on maximum transfer unit - MTU (in bytes). DEVICE_TAGU_MAX_MRU Return the hardware limitation on maximum receive unit - MRU (in bytes).

DEVICE_TAGU_NUMDEVTYPES Return the number of supported device types. DEVICE_TAGERRPTR This tag's parameter is a pointer to a DevTag variable where the driver will put the pointer to any tag that is unknown or has an invalid value. If no invalid tag is detected in the tag list, the variable will be untouched. DEVICE_TAGEND This tag signifies the end of the taglist. Tags with a value of 0x80000000 and above are reserved for customer additions.

20 Device Driver Static Functions

Users Manual / 4.6

Parameters

unit taguList

Which unit to retrieve information from. Pointer to an array of tags.

Return Value

DEVICE_SUCCESS if device information taglist was successfully parsed else an error code.

Errors

DEVICE_EILLEGAL_UNIT An illegal unit number was specified.

DEVICE_EINVALID_TAG Unknown unit information tag. If an error pointer variable was supplied by the tag DEVICE_TAGERRPTR it is set to point to the erroneous tag field.

Restrictions

None.

3.4.4 ddOpen
Syntax DevErr ddOpen void *dcObjects, (U32 unit, U32 deviceType, const struct DcFuncs *dcFuncs, struct ISRInfo *isrInpfo);

ARM BSP

Description

A device driver unit must be opened before it can be started. ddOpen() opens one unit and initializes it. The function call argument unit specifies which unit to open and deviceType the desired device type. Valid device types are defined in the device specific header files, e.g. serdev.h, ethdev.h. ddOpen() may use the call-back function dcAlloc() if memory is needed for buffer descriptors etc. A device client opening a device driver must implement up to five call-back functions (dcAlloc, dcFree, dcHandleEX, dcHandleRX and dcHandleTX). The functions are used by the device driver to allocate and free memory dynamically, report errors and asynchronously deliver input and output packets to the device client. Pointers to the callback functions must be saved in a DcFuncs structure which is passed on to ddOpen. In polled mode will no interrupts be generated by the device. By calling ddSimInt the dcHandleEX and dcHandleTX will be executed and any outstanding events will be handled.
struct DcFuncs { void *(*dcAlloc)(void *dcObjects, U32 buflen); void (*dcFree) (void *dcObjects, void *buf); void (*dcHandleEX) (void *dcObjects, DevErr errorCode); void (*dcHandleRX) (void *dcObjects, void *buf, U32 buflen, U32 numFR); void (*dcHandleTX) (void *dcObjects, void *buf, U32 buflen, U32 numFW); };

Users Manual / 4.6

Device Driver Static Functions 21

dcObjects is a void pointer which is passed on to ddOpen() only to be returned in all of the call-back functions. This may be very handy when handling multiple units with the same call-back functions etc. The last argument to ddOpen() is a pointer to an ISRInfo structure that is filled in by the device driver. The device driver returns information about each interrupt service routine and it is then up to the device client to decide what to do with the information. If the device client is using OSE Delta, it can create interrupt process(es) which will handle the device interrupts.
struct ISRInfo { /* Number of elements valid in the */ /* ISR array below. */ U32 numISRs; struct { /* Entrypoint for the Interrupt */ /* Service Routine. */ void (*entrypoint) (void); /* Priority this interrupt operates */ /* on. */ U32 priority; /* 0 highest. */

ARM BSP

/* The stack size (in bytes) that */ /* this ISR needs. */ U32 stacksize; /* The hardware interrupt vector */ /* number. */ S32 vector; } ISR[4]; /* A maximum of four ISR's */ /* per unit. */ };

If a NULL pointer is passed instead of isrInfo pointing to a structure, then the device is opened in polled mode, i.e. no ISRs are needed. Parameters unitWhich unit to open. deviceType dcObjects dcFuncs isrInfo Return Value The desired device type of the unit. A pointer to client specific object which is passed on to the call-back functions unmodified. A pointer to a structure containing pointers to the device client functions. A pointer to an ISR information structure that is filled in by the driver.

DEVICE_SUCCESS if the unit was successfully opened or else an error code giving an indication why the open failed.

Errors

DEVICE_EILLEGAL_UNIT

22 Device Driver Static Functions

Users Manual / 4.6

An illegal unit number was specified. DEVICE_EILLEGAL_DEVTYPE An illegal device type was specified. The device does either not support or implement the specified device type. DEVICE_EALREADY_OPENED The unit is already opened. An opened unit may not be reopened unless it is closed first. DEVICE_EFUNCTION_NOT_AVAILABLE This obscure error code is used when the driver does not implement a functionality that the device client requested. For example, if the driver does not support polled mode and ddOpen requests polled mode this error code is returned. DEVICE_EDEVICE_NOT_FOUND No hardware device was found when the driver was initialized. DEVICE_EHARDWARE_ERROR

ARM BSP

Hardware did not perform as expected. DEVICE_ENO_BUFFERS Driver cannot be started because no buffers are available, i.e. dcAlloc() returned NULL. Restrictions ISRInfo structure supports a maximum of four ISRs per unit. ddOpen may not change ddSetConf parameters.

3.4.5 ddStart
Syntax DevErr ddStart (U32 unit);

Description

A device driver must first be opened and then started before it can be used. The function call ddStart() starts a device driver unit. Once started, ddWrite() may be used to write data to the device and the call-back functions dcHandleRX() and dcHandleTX() will be called as data is received or transmitted (interrupt mode only). There is no function ddStop() to stop a device driver. The only way to stop a device is to use ddClose() which will automatically stop it. Then when the driver shall be restarted, it has to be opened and started once more.

Parameters Return Value

unitWhich unit to start. DEVICE_SUCCESS if the unit was successfully started or else an error code giving an indication why start failed.

Errors

DEVICE_EILLEGAL_UNIT

Users Manual / 4.6

Device Driver Static Functions 23

An illegal unit number was specified. DEVICE_ENOT_OPENED Device is not opened and cannot be used until opened. DEVICE_EALREADY_STARTED The unit is already started. A started unit may not be started again unless it is closed and reopened first. DEVICE_ENO_BUFFERS Driver cannot be started because no buffers are available, i.e. dcAlloc() returned NULL. Restrictions None.

3.4.6 ddClose
Syntax DevErr ddClose (U32 unit);

Description

ARM BSP

ddClose() closes down a device driver unit. In interrupt mode input and output in process is aborted by ddClose() calling ddAbortRead() and ddAbortWrite(). Memory allocated with dcAlloc() is returned to the device client by calling dcFree(). All ddSetConf parameters has to be set to their default value. unit Which unit to close.

Parameters Return Value

DEVICE_SUCCESS if the unit was successfully closed or else an error code giving an indication why close failed.

Errors

DEVICE_EILLEGAL_UNIT An illegal unit number was specified. DEVICE_ENOT_OPENED Device is not open.

Restrictions

None.

3.4.7 ddGetConf
Syntax DevErr ddGetConf (U32 unit, DevTag * tagcList);

Description

ddGetConf() retrieves the current configuration for one unit. The caller must, in addition to the unit number, specify which configuration options should be retrieved by supplying corresponding tags. Each tag specifies which option to retrieve and is followed by extra data storage for the value of the option. tagcList points to an array of tags, which must be terminated with the terminator tag DEVICE_TAGEND. Valid configuration tags depend on the type of device. Tags with a value of 0x80000000 and above are reserved for customer additions.

24 Device Driver Static Functions

Users Manual / 4.6

This function can be called at any time by all processes. Standard tags: DEVICE_TAGERRPTR This tag's parameter is a pointer to a DevTag variable that will contain a pointer to the tag that was unknown or had an invalid value. If no invalid tag was detected in the tag list, the variable will be untouched. DEVICE_TAGEND This tag signifies the end of the taglist. Tags with a value of 0x80000000 and above are reserved for customer additions. Parameters unit tagcList Return Value Which unit to get configuration on. Pointer to an array of tags.

DEVICE_SUCCESS if unit configuration taglist was successfully parsed else an error code.

Errors

DEVICE_EILLEGAL_UNIT An illegal unit number was specified.

DEVICE_ENOT_OPENED Device is not opened. DEVICE_EINVALID_TAG Unknown unit information tag. If an error pointer variable was supplied by the tag DEVICE_TAGERRPTR it is set to point to the erroneous tag field.

ARM BSP

Restrictions

None.

3.4.8 ddSetConf
Syntax DevErr ddSetConf (U32 unit, DevTag * tagcList);

Description

ddSetConf() is used to configure a device driver unit. The caller must, in addition to the unit number, specify which configuration options should be modified by supplying corresponding tags. Each tag specifies which option to modify and is followed by the desired value for that option. tagcList points to an array of tags, which must be terminated with the terminator tag DEVICE_TAGEND. Valid configuration tags depend on the type of device. Tags with a value of 0x80000000 and above are reserved for customer additions. This function can be called at any time by all processes. Standard tags: DEVICE_TAGERRPTR

Users Manual / 4.6

Device Driver Static Functions 25

This tag's parameter is a pointer to a DevTag variable that will contain a pointer to the tag that was unknown or had an invalid value. If no invalid tag was detected in the tag list, the variable will be untouched. DEVICE_TAGEND This tag signifies the end of the taglist. Tags with a value of 0x80000000 and above are reserved for customer additions. Parameters unit tagcList Return Value Which unit to get configuration on. Pointer to an array of tags.

DEVICE_SUCCESS if unit configuration taglist was successfully parsed else an error code.

Errors

DEVICE_EILLEGAL_UNIT An illegal unit number was specified.

DEVICE_ENOT_OPENED Device is not opened.

ARM BSP

DEVICE_EALREADY_STARTED The unit is already started. A unit may not be configured once started. DEVICE_EINVALID_TAG Unknown configuration tag. If an error pointer was supplied by the tag DEVICE_TAGERRPTR it's value is set to point to the erroneous tag field. DEVICE_EINVALID_VALUE Invalid configuration value. If an error pointer was supplied by the tag DEVICE_TAGERRPTR it's value is set to point to the erroneous tag field. Restrictions None.

26 Device Driver Static Functions

Users Manual / 4.6

3.4.9 ddWrite
Syntax DevErr ddWrite (U32 unit, void *buf, U32 *buflen);

Description

ddWrite() attempts to write *buflen bytes of data to the unit referenced by unit from the buffer pointed to by buf. On return *buflen contains the actual number of bytes written. Most drivers have several buffer descriptors forming a ring that can be used to place transmit and receive buffers in queue. If there is a unused buffer descriptor at the moment ddWrite() is called, the data buffer information (pointer and length) is stored by the device driver and placed in queue to be written as soon as the link permits. Post transmit processing will be called when transmission is finished. If the driver works in interrupt mode, ddWrite() returns directly and an interrupt will be generated when the package has been sent. Otherwise, the driver polls the devices status until the package has been sent, and calls for post-transmit processing after that. It is important to note that updating of the buffer descriptor is done in an atomic manner, and that ddWrite() is fully pre-emptive. In interrupt mode ddWrite() returns directly after buffer descriptor updating and interrupt enabling, and in polled mode ddWrite may be pre-empted by a higher priority process under the potentially more time costly poll I/O-accesses. Post transmit processing is needed to update the buffer descriptor list, and to let the Device Client free the used data buffer, which was "borrowed" by the driver to avoid time costly memory copying.

ARM BSP

In interrupt mode, ddWrite() either succeeds in writing the whole buffer or not, i.e. it never writes partial buffers. Only in polled mode may partial writes occur depending on the MTU and internal buffering. Parameters unit buf buflen Which unit to write on. Pointer to output data. The U32 pointed to by the buflen parameter should be initialized to the number of bytes to write. On return it contains the actual number of bytes written.

Return Value

DEVICE_SUCCESS if *buflen (actual number of bytes written) was written else an error code giving an indication why write failed.

Errors

DEVICE_EILLEGAL_UNIT An illegal unit number was specified. DEVICE_ENOT_OPENED Device is not opened. DEVICE_ENOT_STARTED Device is not started. DEVICE_EINVALID_LENGTH Invalid length. It is not valid to write 0 bytes or a buffer larger than maximum transmit unit.

Users Manual / 4.6

Device Driver Static Functions 27

DEVICE_EQUEUE_FULL The internal output queue in the device driver is full and write failed. For each failed write, the device driver will increment a 'number of times write failed' counter which will be passed to the device client (using dcHandleTX()) next time a transmit done interrupt is serviced. The internal counter is set to zero after dcHandleTX() is called. Restrictions None.

3.4.10ddRead
Syntax DevErr ddRead (U32 unit, void *buf, U32 *buflen);

Description

ddRead() is only used in polled mode, since interrupt mode automatically delivers data to the device client by calling dcHandleRX(). In polled mode ddRead() is used to request incoming data. After calling ddRead() the buffer is owned by the device driver. Once a terminator or *buflen bytes of data is received, input is disabled and the buffer is returned with the dcHandleRX(). The device client then has to call ddRead() once again to request another packet.

Parameters

unit buf buflen

Which unit to read from. Pointer to data storage. The U32 pointed to by the buflen parameter should be initialized to the number of bytes to read. On return it contains the actual number of bytes read.

ARM BSP

Return Value

DEVICE_SUCCESS if ddRead was successfully called else an error code giving an indication what error occurred.

Errors

DEVICE_EILLEGAL_UNIT An illegal unit number was specified. DEVICE_ENOT_OPENED Device is not opened. DEVICE_ENOT_STARTED Device is not started. DEVICE_EINVALID_LENGTH Invalid length. It is not valid to read 0 bytes or more bytes than the maximum receive unit. DEVICE_EQUEUE_FULL

28 Device Driver Static Functions

Users Manual / 4.6

The internal queue of pending ddRead() requests is full. For each failed read, the device driver will increment a 'number of times read failed' counter which will be passed to the device client (using dcHandleRX()) next time a receive interrupt is serviced. This counter is set to zero after dcHandleRX() is called. DEVICE_EFUNCTION_NOT_AVAILABLE ddRead() was called when in interrupt mode (not valid). Restrictions None.

3.4.11ddSimInt
Syntax DevErr ddSimInt (U32 unit);

Description

ddSimInt() is used in polled mode only. The function is used to simulate an interrupt for a device. This is done by checking for new TX and RX events and calling the ISR for the unit. unit Which unit to read from.

Parameters Return Value

DEVICE_SUCCESS if ddSimInt was successfully called else an error code explaining the cause of error.

ARM BSP

Errors

DEVICE_EILLEGAL_UNIT An illegal unit number was specified. DEVICE_ENOT_OPENED Device is not opened. DEVICE_ENOT_STARTED Device is not started. DEVICE_EFUNCTION_NOT_AVAILABLE Returned if device driver is not opened in polled mode and ddSimInt() therefore is not supported.

Restrictions

Device clients may only call ddSimInt() when the unit is opened in polled mode.

Users Manual / 4.6

Device Driver Static Functions 29

3.4.12ddAbortWrite
Syntax DevErr ddAbortWrite (U32 unit);

Description

ddAbortWrite() aborts the current write and returns the buffer by calling dcHandleTX with buflen set to the number of bytes that was written before abort. When ddClose() is called in interrupt mode ddAbortWrite() is automatically called on all pending writes.

Parameters Return Value

unit

Which unit to abort write on.

DEVICE_SUCCESS if ddAbortWrite was successfully called else an error code explaining the cause of error.

Errors

DEVICE_EILLEGAL_UNIT An illegal unit number was specified. DEVICE_ENOT_OPENED Device is not opened. DEVICE_ENOT_STARTED

ARM BSP

Device is not started. DEVICE_EFUNCTION_NOT_AVAILABLE ddAbortWrite() was called in polled mode. Restrictions Device clients may only call ddAbortWrite() when the unit is opened in interrupt mode.

30 Device Driver Static Functions

Users Manual / 4.6

3.4.13ddAbortRead
Syntax DevErr ddAbortRead (U32 unit);

Description

ddAbortRead() aborts the currently pending read requests and returns the buffers by calling dcHandleRX() with buflen set to the number of bytes that was read before abort. This function is only needed in manual interrupt mode. It is neither valid nor needed to call ddAbortRead() when in automatic mode since there can be no pending ddRead() requests. When ddClose() is called in interrupt mode ddAbortRead() is automatically called on all pending read requests.

Parameters Return Value

unit

Which unit to abort read on.

DEVICE_SUCCESS if ddAbortRead was successfully called else an error code explaining the cause of error.

Errors

DEVICE_EILLEGAL_UNIT An illegal unit number was specified. DEVICE_ENOT_OPENED

ARM BSP

Device is not opened. DEVICE_ENOT_STARTED Device is not started. DEVICE_EFUNCTION_NOT_AVAILABLE ddAbortRead() was called in polled or automatic mode. Restrictions Device clients may only call ddAbortRead() when the unit is opened in manual mode.

Users Manual / 4.6

Device Driver Static Functions 31

3.5 Device Driver Client Call Back Functions

The device client, which is the application that uses a device driver, must implement up to five call-back functions in order to successfully use the driver. Two of the functions, dcAlloc and dcFree, are needed to dynamically allocate and free memory independently of the operating system whereas the other three are implemented for maximum performance. The three dcHandle<E | R | T>X() functions are used to report errors, return transmitted packets, and asynchronously deliver incoming packets to the device client. Even if polled mode is used, the dcHandle<E | R | T>X() functions must be implemented since they are called when using the function ddSimInt. The device client call-back functions may be called in the device client's own context or in the context of any the device driver's interrupt processes. As a result care should be taken when handling buffers and their process ownership.When using OSE, the system call restore() will most likely be needed in order to send or free a buffer since it may be owned by the device driver or the device client. For a detailed description of the call-back functions, see:

dcAlloc on page 33 dcFree on page 33 dcHandleEX on page 33 dcHandleRX on page 34 dcHandleTX on page 35

ARM BSP

32 Device Driver Client Call Back Functions

Users Manual / 4.6

3.5.1 dcAlloc
Syntax void dcAlloc (void *dcObjects, U32 buflen);

Description

dcAlloc() is used by the device driver to request a block of memory of size buflen. Depending on the system used to allocate the memory, dcAlloc() may fail if there is no more memory, or buflen exceeds the maximum allocation size. dcAlloc() is normally called from either ddOpen() or ddStart() to allocate memory for buffer descriptors or from interrupt context to allocate memory storage for input packets. Since dcAlloc() executes in the context of the calling process, the buffers may be allocated by different processes. The buffer returned must be long word (U32) aligned. dcObjects buflen Pointer to client specific object. Number of bytes to allocate.

Parameters

Return Value Restrictions

Pointer to a buffer of minimum size buflen or NULL if no memory is available or buflen is too large. None.

3.5.2 dcFree
Syntax void dcAlloc (void *dcObjects, void *buf);

ARM BSP

Description

dcFree() releases a previously allocated block. The second argument buf is a pointer to a block previously allocated by dcAlloc(). When using OSE, dcFree() probably has to call restore() before free_buf() to guarantee buffer ownership before returning the buffer to the operative system. When a device driver is closed with ddClose, it will return all allocated memory by calling dcFree(). dcObjects buf Pointer to client specific object. Pointer to a buffer previously allocated by dcAlloc().

Parameters

Return Value Restrictions

None. None.

3.5.3 dcHandleEX
Syntax void dcHandleEX (void *dcObjects, DevErr errorCode);

Description

When an error is discovered during interrupt processing dcHandleEX() is used to asynchronously report this error to the device client. After receiving an asynchronous error report, the device client must close and reopen the driver to assure that it is working properly. The error codes are defined in device.h. This function may also be used to report status changes. dcObjects errorCode Pointer to client specific object. Error code.

Parameters

Return Value Restrictions

None. dcHandleEX() may not call any of the device driver functions (ddXXX()).

Users Manual / 4.6

Device Driver Client Call Back Functions 33

3.5.4 dcHandleRX
Syntax void dcHandleRX (void *dcObjects, void *buf, U32 buflen, U32 numFailedReads);

Description

dcHandleRX() is used in interrupt mode to asynchronously deliver incoming packets to the device client. The first argument dcObjects is the same dcObjects pointer that the device driver received when it was opened with ddOpen(). buf points to the incoming packet and buflen is equal to the number of bytes received. The buffer that buf points to was allocated by the driver using the dcAlloc() call-back. The last argument, numFailedReads, is a counter equal to the number of times ddRead() failed since the last dcHandleRX() call. The device driver clears its numFailedReads counter after each dcHandleRX() call. Note that in manual mode dcHandleRX() will not be called automatically, i.e. each successful ddRead() request results in one dcHandleRX() being called when data arrives.

Parameters

dcObjects buf buflen

Pointer to client specific object. Pointer to a buffer (retrieved either from ddRead() or dcAlloc()) containing the received data. Number of bytes received.

ARM BSP

numFailedReadsThe current number of failed read requests. Return Value Restrictions None. None.

34 Device Driver Client Call Back Functions

Users Manual / 4.6

3.5.5 dcHandleTX
Syntax void dcHandleRX (void *dcObjects, void *buf, U32 buflen, U32 numFailedWrites);

Description

dcHandleTX() is used in interrupt mode to asynchronously return packets sent with ddWrite() to the device client after the packet is written to the link. The first argument dcObjects is the same dcObjects pointer that the device driver received when it was opened with ddOpen(). buf points to the written packet (the same buffer that was delivered with ddWrite()) and buflen is equal to the number of bytes that were written. Since dcHandleTX() is only used in interrupt mode where no partial writes are possible buflen will always be equal to the buflen ddWrite() was called with. The last argument, numFailedWrites, is a counter equal to the number of times ddWrite() failed since the last dcHandleTX()call. The device driver clears its numFailedWrites counter after each dcHandleTX() call.

Parameters

dcObjects buf buflen

Pointer to client specific object. Pointer to the buffer previously supplied in ddWrite(). Number of bytes transmitted.

ARM BSP

numFailedWritesThe current number of failed write requests. Return Value Restrictions None. None.

Users Manual / 4.6

Device Driver Client Call Back Functions 35

ARM BSP
36 Device Driver Client Call Back Functions

Users Manual / 4.6

4 Supported Boards
Boards supported are described in the following sections:

ARM Evaluator-7T Board on page 38 Atmel AT91EB01 on page 43 Atmel AT91EB55 on page 45

Board Support Package

Users Manual / 4.6

Supported Boards 37

4.1 ARM Evaluator-7T Board

Evaluator-7T offers an easy, affordable introduction to the ARM family of processor related products. It is ideal for new customers and students who want to evaluate and get acquainted with an ARM CPU and its software tools. Based on the ARM7TDMI microcontroller the Evaluator-7T supports the full range of ARM 7 instructions including THUMB instructions and can operate at speed of up to 50 MHZ. Features of the ARM Evaluator-7T Evaluation Board:

Easy to set-up and use Compact and affordable Supports ARM. Multi-ICE, JTAG debugger Extendable as all the microcontroller signals are accessible

ARM BSP
38 ARM Evaluator-7T Board

Users Manual / 4.6

Evaluator-7T Board Spec:

Samsung KS32C50100 Microcontroller 512K FLASH EEPROM boot ROM 512K+ 32bit wide SRAM Up to 50 MHZ operation 4 individual LED's Four dip switches 7-Segment LED display 2 9-pin D-Sub serial connector System reset switch Core reset switch Interrupt switch Bootstrap loader in FLASH Boot ROM Angel debug monitor in FLASH Boot ROM MicroHAL in FLASH Boot ROM JTAG connector that is fully MultiICE compatible including reset and hot-swap capability. Board Setup on page 40 ELDM Serial Driver on page 41 On-Chip PPP Serial Driver on page 41 LED Driver on page 42

Board Support Package

See also:

Users Manual / 4.6

ARM Evaluator-7T Board 39

4.1.1 Board Setup

This is some of the first code executed after a board reset. The purpose of this code is to bring the board to a state where OSE Epsilon for ARM can access memory and devices. On most boards this includes setting up memory, initiating the interrupt controller, masking all interrupts and initiating the on-board devices.

4.1.1.1 Files Linker Command Files evaluator7T.txt evaluator7T.lnk evaluator7T.xcl ARM ADS/RCVT GNU GCC IAR Embedded Workbench

System and Board Initialization Files crt0.s crt0.S crt0.s79 ARM ADS/RCVT GNU GCC IAR Embedded Workbench

Interrupt Handler Files

ARM BSP

inthdlr.s inthdlr.S inthdlr.s79

ARM ADS/RCVT GNU GCC IAR Embedded Workbench

Timer Initialization Files timer_setup.s timer_setup.S timer_setup.s79 ARM ADS1.1 and GNU GCC GNU GCC IAR Embedded Workbench

4.1.1.2 Processes

There are no OSE processes used in the board setup.

4.1.1.3 Start Handlers Timer Initialization

The following start handler is included in the timer initialization file:

TimerSetup 4.1.1.4 Configuration

There is no need for any entry in the osarm.con configuration file for the board setup. All initialization is done in the startup functions and handlers.

40 ARM Evaluator-7T Board

Users Manual / 4.6

4.1.2 ELDM Serial Driver

These are very simple straight forward serial drivers used mainly for the Epsilon Local Debug Module (eldm). This eldm allows you to connect the OSE Illuminator system level debugger to an OSE Epsilon system. This driver does not follow the OSE Epsilon device driver concept.
4.1.2.1 Files File Name eldm_uart.s eldm_uart.S eldm_uart.s79 Development Environment ARM ADS1.1 and GNU GCC GNU GCC IAR Embedded Workbench

Board Support Package

4.1.3 On-Chip PPP Serial Driver

This is a serial drivers for the on-chip serial controller following the OSE Epsilon device driver concept used mainly for INET PPP.
4.1.3.1 Files File Name devuart.h devuart.c devuart.sig uart.c Development Environment All All All All

4.1.3.2 Processes

The following interrupt processes are included in uart.c:

uart0_rxirq uart1_rxirq gdma0_irq 4.1.3.3 Start Handlers

The following start handler is included in devuart.c:

devuart_init 4.1.3.4 Configuration

You have to define the following lines in the configuration file osarm.con for this driver: Interrupt processes:
INT_PROC INT_PROC INT_PROC uart0_rxirq uart1_rxirq gdma0_irq

Start handlers:
START_HANDLER devuart_init

Users Manual / 4.6

ARM Evaluator-7T Board 41

4.1.4 LED Driver

4.1.4.1 Description

Some boards have an LEDs or an array of LEDs which can be controlled by the user software.
4.1.4.2 Files File Name led.h led.c Development Environment All All

ARM BSP
42 ARM Evaluator-7T Board

Users Manual / 4.6

4.2 Atmel AT91EB01

The Atmel AT91EB01 board is replaced by the Atmel AT91EB40 board which is fully supported by this OSE Epsilon for ARM board support package. The AT91EB40 Evaluation Board enables real-time code development and evaluation. It supports the AT91x40 series with its various memory options. The board consists of an AT91R40807 (ARM7TDMI) processor together with several peripherals:

Two serial ports Reset button Three applicative buttons (FIQ, TIOB0, IRQ0) Three LEDs (TIOA0, TIOA1, TIOB0) 512K bytes 16-bit SRAM (upgradable to 2048K bytes) 128K bytes 16-bit Flash (of which 64K bytes is available for user software) 20-pin JTAG interface connector

Board Support Package

4.2.1 Board Setup

This is some of the first code executed after a board reset. The purpose of this code is to bring the board to a state where OSE Epsilon for ARM can access memory and devices. On most boards this includes setting up memory, initiating the interrupt controller, masking all interrupts and initiating the on-board devices.
4.2.1.1 Files File Name Development Environment

Linker Command Files

at91eb01.txt at91eb01.lnk at91eb01.xcl cstartup.s cstartup.s79 crt0.S ARM ADS1.1 GNU GCC IAR Embedded Workbench ARM ADS1.1 IAR Embedded Workbench GNU GCC

System and Board Initialization Files

Interrupt Handler Files inthdlr.s inthdlr.s79 inthdlr.S ARM ADS1.1 IAR Embedded Workbench GNU GCC

Timer Initialization Files timer_setup.s timer_setup.s79 timer_setup.S ARM ADS1.1 IAR Embedded Workbench GNU GCC

Users Manual / 4.6

Atmel AT91EB01 43

4.2.1.2 Processes

There are no OSE processes used in the board setup.

4.2.1.3 Start Handlers Timer Initialization

The following start handler is included in the timer initialization file:

TimerSetup 4.2.1.4 Configuration

There is no need for any entry in the osarm.con configuration file for the board setup. All initialization is done in the startup funcions and handlers.

4.2.2 ELDM Serial Driver

These are very simple straight forward serial drivers used mainly for the Epsilon Local Debug Module (eldm). This eldm allows to connect the OSE Illuminator system level debugger to an OSE Epsilon system. This driver is not following the OSE Epsilon device driver concept.

ARM BSP

4.2.2.1 Files File Name eldm_uart.s eldm_uart.s79 eldm_uart.S Development Environment ARM ADS1.1 IAR Embedded Workbench GNU GCC

4.2.3 LED Driver

Some boards have a LEDs or an array of LEDs which can be controlled by the user software.
4.2.3.1 Files File Name led.h led.c Development Environment All All

44 Atmel AT91EB01

Users Manual / 4.6

4.3 Atmel AT91EB55

The AT91EB55 Evaluation Board enables real-time code development and evaluation. It supports the AT91M55800A. The board consists of an AT91M55800A (ARM7TDMI), together with several peripherals:

Two serial ports Reset push button An indicator which memorizes a reset appearance Memory clear for the reset indicator Four user-defined push buttons Eight LEDs 256K byte of 16-bit SRAM (upgradable to 1 MB) 2M bytes of 16-bit Flash (of which 1 MB is available for user software) 4M bytes of Serial Data Flash (upgradeable to 16 MB) 64K bytes of E 2 PROM with I 2 C access 32K bytes of SPI E 2 PROM 2 x 32 pin EBI expansion connector 3 x 32 pin I/O expansion connector 20-pin JTAG interface connector

Board Support Package

4.3.1 Board Setup

This is some of the first code executed after a board reset. The purpose of this code is to bring the board to a state where OSE Epsilon for ARM can access memory and devices. On most boards this includes setting up memory, initiating the interrupt controller, masking all interrupts and initiating the on-board devices.
4.3.1.1 Files File Name Development Environment

Linker Command Files

at91eb01.txt at91eb01.lnk at91eb01.xcl cstartup.s cstartup.s79 crt0.S ARM ADS1.1 GNU GCC IAR Embedded Workbench ARM ADS1.1 IAR Embedded Workbench GNU GCC

System and Board Initialization Files

Interrupt Handler Files Users Manual / 4.6 Atmel AT91EB55 45

inthdlr.s inthdlr.s79 inthdlr.S

ARM ADS1.1 IAR Embedded Workbench GNU GCC

Timer Initialization Files timer_setup.s timer_setup.s79 timer_setup.S ARM ADS1.1 IAR Embedded Workbench GNU GCC

4.3.1.2 Processes

There are no OSE processes used in the board setup.

4.3.1.3 Start Handlers Timer Initialization

The following start handler is included in the timer initialization file:

TimerSetup 4.3.1.4 Configuration

ARM BSP

There is no need for any entry in the osarm.con configuration file for the board setup. All initialization is done in the startup funcions and handlers.

4.3.2 ELDM Serial Driver

These are very simple straight forward serial drivers used mainly for the Epsilon Local Debug Module (eldm). This eldm allows to connect the OSE Illuminator system level debugger to an OSE Epsilon system. This driver is not following the OSE Epsilon device driver concept.
4.3.2.1 Files File Name eldm_uart.s eldm_uart.s79 eldm_uart.S Development Environment ARM ADS1.1 IAR Embedded Workbench GNU GCC

4.3.3 LED Driver

Some boards have a LEDs or an array of LEDs which can be controlled by the user software.
4.3.3.1 Files File Name led.h led.c Development Environment All All

46 Atmel AT91EB55

Users Manual / 4.6

Index
Symbols
_biosentry _functions _init _intr 14 15 16 16

A
ARM Evaluator-7T Board AT91EB40 AT91M55800A AT91R40807 Atmel AT91EB01 Atmel AT91EB55 38 43 45 43 43 45 12 12 12 7, 8 7

B
BIOS biosInstall biosOpen() Board setup BSP Concept

C
Call Back Functions 32

D
dcAlloc dcFree dcHandle dcHandleEX dcHandleRX dcHandleTX ddAbortRead ddAbortWrite ddClose ddDevClass ddDevInfo ddGetConf ddOpen ddRead ddSetConf ddSimInt ddStart ddUnitInfo ddWrite Device driver Device Driver Functions Device driver interface Device hardware 33 33 32 33 34 35 31 30 24 18 19 24 21 28 25 29 23 20 27 7, 11 12 11 12

18 DEVICE_CLASS 23 DEVICE_EALREADY_OPENED DEVICE_EALREADY_STARTED 24, 26 23 DEVICE_EDEVICE_NOT_FOUND DEVICE_EFUNCTION_NOT_AVAILABLE 23, 29, 30, 31 DEVICE_EHARDWARE_ERROR 23 23 DEVICE_EILLEGAL_DEVTYPE DEVICE_EILLEGAL_UNIT 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31 27, 28 DEVICE_EINVALID_LENGTH DEVICE_EINVALID_TAG 19, 21, 25, 26 26 DEVICE_EINVALID_VALUE 23, 24 DEVICE_ENO_BUFFERS DEVICE_ENOT_OPENED 24, 25, 26, 27, 28, 29, 30, 31 DEVICE_ENOT_STARTED 27, 28, 29, 30, 31 28 DEVICE_EQUEUE_FULL DEVICE_EUNKNOWN 15 14 DEVICE_FCABORTREAD 14 DEVICE_FCABORTWRITE DEVICE_FCCLOSE 14 14, 18 DEVICE_FCDEVCLASS 14 DEVICE_FCDEVINFO DEVICE_FCFUNCTIONS 14 14 DEVICE_FCGETCONF 14 DEVICE_FCINIT DEVICE_FCOPEN 14 14 DEVICE_FCREAD 14 DEVICE_FCSETCONF DEVICE_FCSIMINT 14 14 DEVICE_FCSTART 14 DEVICE_FCUNITINFO DEVICE_FCWRITE 14 14 DEVICE_FCXXX DEVICE_SUCCESS 19, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31 19 DEVICE_TAGD_NAME 19 DEVICE_TAGD_OPENALL DEVICE_TAGD_UNITHI 19 19 DEVICE_TAGD_UNITLO 19 DEVICE_TAGD_VERSION DEVICE_TAGEND 19, 20, 25, 26 19, 20, 25 DEVICE_TAGERRPTR 20 DEVICE_TAGU_DEVTYPES DEVICE_TAGU_INUSE 20 20 DEVICE_TAGU_MAX_MRU DEVICE_TAGU_MAX_MTU 20
Index 47

ARM BSP

Users Manual / 4.6

DEVICE_TAGU_NUMDEVTYPES DEVICE_VERSION

20 19 7 13 8 8 7 13 16 23

I
I/O Initialization Internal system timer Interrupt controller Interrupt handling Interrupt service routine ISR

N
NULL

P
Public functions 12

R
Register the driver Reset 12 8

ARM BSP

start handler Static functions Supported Boards System tick System timer

7 12 37 8 7

T
Timer 7, 8

Users Manual / 4.6

Index 48