AT: Better failure handling and removed wrong unlock
[hayes-ril.git] / device / DEVICE_API.txt
1 Hayes RIL Device API
2 ====================
3
4 This file is part of hayes-ril.
5
6 Copyright (C) 2012 Paul Kocialkowski <contact@paulk.fr>
7
8 Licensed under the Apache License, Version 2.0 (the "License");
9 you may not use this file except in compliance with the License.
10 You may obtain a copy of the License at
11
12     http://www.apache.org/licenses/LICENSE-2.0
13
14 Unless required by applicable law or agreed to in writing, software
15 distributed under the License is distributed on an "AS IS" BASIS,
16 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
17 See the License for the specific language governing permissions and
18 limitations under the License.
19
20 Purpose of this document
21 ------------------------
22
23 This document is a guide to add support for a new device in Hayes RIL.
24 It explains how to use the device API.
25
26 Files
27 -----
28
29 The files for a new device must be placed in a specific folder contained in
30 the "device" folder, on the source tree root. The name of this folder depends
31 on the device.
32
33 Please, make it the same as the TARGET_DEVICE var in the device config files.
34
35 The source can be split in several files, though, there must be a C code file
36 with the same name as the folder holding the main structures for the device.
37
38 Log tag
39 -------
40
41 The log tag to use on device-specific code is "RIL-DEV". Please use:
42 #define LOG_TAG "RIL-DEV"
43
44 Structures
45 ----------
46
47 The device structures are described in hayes-ril.h, on the source tree root.
48 The main structure for the device API is: "struct ril_device"
49 The fields you can set on this are:
50
51 .name   : The name of the new device.
52           This is usually the human-readable name of the device.
53
54 .sdata  : Some shared data for the device you can specify.
55           Give that the use you want, but it's not passed as argument to
56           the handlers functions.
57
58 .type   : The device type (GSM, CDMA).
59
60 The handlers field is a pointer to the device handlers structure.
61
62 Handlers
63 --------
64
65 Handlers are functions and data designed to control input/output interactions
66 with the device. The handlers structure is: "struct ril_device_handlers"
67
68 The handlers are categorized that way:
69 * power handlers (power on, power off, suspend, resume, boot)
70 * transport handlers (open, close, send, recv, poll)
71
72 Each handler has shared data (sdata) that can be used by any function of the
73 handlers set. This data is created with the sdata_create function and destroyed
74 with the sdata_destroy function, which are part of any handler category.
75
76 Return codes
77 ------------
78
79 Any function returning success must return an integer equal or greater than 0.
80 Any function returning failure must return an integer lower than 0.
81
82 Registering
83 -----------
84
85 The device files must provide a ril_device_register following the prototype
86 described in hayes-ril.h, on the source tree root.
87
88 On this function, you must register the pointer to the main structure of your
89 device on the memory zone identified by the given pointer.