Chapter 1. Overview
Prev | RISC OS USB C API | Next

## Chapter 1. Overview

## 1. Introduction

The C API is provided to enable the rapid development of device drivers. It may be used to write application based drivers using either Norcroft or GCC compilers. There is a limitation with GCC however that currently precludes it use creating module based drivers.

Several example drivers have been written with this API and are available in source form as examples of intended use.

## 2. Initialization

Before use the library must be initialized, this is achieved simply by calling the usblib_init() function call. Similarly usblib_stop() should be called to free any allocated resources and cleanly shutdown the library.

In addition to these calls module drivers which may be instantiated before the core usb modules have started may use the Service_USB 16 - USB system module started to detect the USB system starting, they should use usblib_core_start() to start the parts of the library associated with the core starting and usblib_core_stop() when receiving the Service_USB 17 - USB system module stopped service call.

## 3. Support Functions

In addition to the core API, which is analogous to the SWI API, the C API provides a number of "support" functions which provide useful and common routines for writing device drivers.

These functions definitions are generally in headers in the /usb/lib include directory.

## 4. Includes

There are four main include paths all relative to <USB$Include>. These are:

"usb" - non system specific headers.
"usb/sys" - system specific headers.
"usb/lib" - non core defines and library helper functions.
"usb/hid" - HID defines and function definitions.

## 5. Linking

Binary library objects are provided for both application and module linking. Libraries intended to be linked with modules have the standard "zM" suffix. The libraries can be referenced using <usb$link> environment variable.

Two versions of the library have been provided, the first "std-lib" uses standard SWI calls to communicate with the USB stack with all the associated overheads this version is usable either from application code or module code. The second type "fast-lib" allows module drivers to avoid the overhead of the SWI calls and use a direct calling interface which give a performance increase. Provided the driver is well behaved and calls the library initialization calls there is no difference between these two libraries from an API point of view, simply linking against the appropriate library will work.

Prev | Up | Next
RISC OS USB C API | Home | Chapter 2. C A.P.I.