Hayes RIL Device API
====================

This file is part of hayes-ril.

Copyright (C) 2012 Paul Kocialkowski <contact@paulk.fr>

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

Purpose of this document
------------------------

This document is a guide to add support for a new device in Hayes RIL.
It explains how to use the device API.

Files
-----

The files for a new device must be placed in a specific folder contained in
the "device" folder, on the source tree root. The name of this folder depends
on the device.

Please, make it the same as the TARGET_DEVICE var in the device config files.

The source can be split in several files, though, there must be a C code file
with the same name as the folder holding the main structures for the device.

Log tag
-------

The log tag to use on device-specific code is "RIL-DEV". Please use:
#define LOG_TAG "RIL-DEV"

Structures
----------

The device structures are described in hayes-ril.h, on the source tree root.
The main structure for the device API is: "struct ril_device"
The fields you can set on this are:

.name	: The name of the new device.
	  This is usually the human-readable name of the device.

.sdata	: Some shared data for the device you can specify.
	  Give that the use you want, but it's not passed as argument to
	  the handlers functions.

.type	: The device type (GSM, CDMA).

The handlers field is a pointer to the device handlers structure.

Handlers
--------

Handlers are functions and data designed to control input/output interactions
with the device. The handlers structure is: "struct ril_device_handlers"

The handlers are categorized that way:
* power handlers (power on, power off, suspend, resume, boot)
* transport handlers (open, close, send, recv, poll)

Each handler has shared data (sdata) that can be used by any function of the
handlers set. This data is created with the sdata_create function and destroyed
with the sdata_destroy function, which are part of any handler category.

Return codes
------------

Any function returning success must return an integer equal or greater than 0.
Any function returning failure must return an integer lower than 0.

Registering
-----------

The device files must provide a ril_device_register following the prototype
described in hayes-ril.h, on the source tree root.

On this function, you must register the pointer to the main structure of your
device on the memory zone identified by the given pointer.