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.