B2G/RIL: Difference between revisions
No edit summary |
No edit summary |
||
Line 1: | Line 1: | ||
= B2G | = B2G RIL = | ||
This page contains information about B2G's interaction with the Radio Interface Layer of Android. The RIL provides access to the radio hardware, which is needed to send/receive calls, SMS | This page contains information about B2G's interaction with the Radio Interface Layer of Android. The RIL provides access to the radio hardware, which is needed to send/receive calls, SMS messages, and other things that require interaction with a cell network. | ||
= Talking to the Radio = | |||
== Low Level Access == | |||
Kernel access for specific phones are vendor specific, included in the | Kernel access for specific phones are vendor specific, included in the | ||
Line 27: | Line 12: | ||
architecture is available at | architecture is available at | ||
[http://www.netmite.com/android/mydroid/development/pdk/docs/telephony.html] | |||
Source code for libril and rild is available in the B2G checkout as | Source code for libril and rild is available in the B2G checkout as | ||
Line 33: | Line 18: | ||
glue/gonk/hardware/ril | glue/gonk/hardware/ril | ||
== Socket Access == | |||
In order to access libril, android uses an ipc socket interface to the | In order to access libril, android uses an ipc socket interface to the | ||
Line 53: | Line 38: | ||
rild). | rild). | ||
== Android Access == | |||
Android code specific to RIL communication is in | Android code specific to RIL communication is in | ||
Line 65: | Line 51: | ||
To access sockets via C, android uses libcutils, also available in | To access sockets via C, android uses libcutils, also available in | ||
glue/gonk/frameworks. | glue/gonk/frameworks. | ||
== Parcel Formats == | |||
Parcels contain information about the transaction that they are a part | Parcels contain information about the transaction that they are a part | ||
of, as well as event data. | of, as well as event data. | ||
Line 71: | Line 59: | ||
Event data will be one of the follow types: | Event data will be one of the follow types: | ||
* Void * No return | |||
* Int List * First int is the number of ints in the list, followed by the ints | |||
** Byte 0x0c - uint32_t - number of ints in the packet | |||
** Byte 0x10 - uint32_t- - list of ints | |||
* String - A single string (16-bit) | |||
** Byte 0x0c - uint32_t - length of string | |||
** Byte 0x10 - wchar_t- - string of length specified | |||
* Strings - An array of strings (16-bit) | |||
** Byte 0x0c - uint32_t - number of strings | |||
** Byte 0x10 - Strings - strings in format listed for single string (size + string) | |||
* Custom Struct * A set of different types specific to the message (SMS messages, call lists, etc...) | |||
=== RIL Parcel - Process -> rild === | |||
Each RIL Socket Write has the following format: | Each RIL Socket Write has the following format: | ||
* Byte 0x00 - uint32_t - Header (Size of Following Parcel) | |||
** PARCEL BEGINS AFTER THIS FIELD | |||
* Byte 0x04 - uint32_t - RIL Event ID (IDs available in glue/gonk/hardware/ril/include/telephony/ril.h) | |||
* Byte 0x08 - uint32_t - Packet Serial Number (Used to track send/receive order) | |||
* Byte 0x0c - void* - Event Data | |||
=== RIL Parcel - rild -> Process (solicited reply) === | |||
Each RIL Socket Read (for a solicited response) has the following format: | Each RIL Socket Read (for a solicited response) has the following format: | ||
* Byte 0x00 - uint32_t - Header (Size of Following Parcel) | |||
** PARCEL BEGINS AFTER THIS FIELD | |||
* Byte 0x04 - uint32_t - 0 (To signify it is a reply to a previously sent solicited request) | |||
* Byte 0x08 - uint32_t - Packet Serial Number (Used to track send/receive order) | |||
* Byte 0x0c - void* - Event Data | |||
It is expected that the client maintains a list of previously made | It is expected that the client maintains a list of previously made | ||
Line 108: | Line 97: | ||
the fields in the ril.h file. | the fields in the ril.h file. | ||
=== RIL Parcel - rild -> Process (unsolicited event) === | |||
Each RIL Socket Read (for a solicited response) has the following format: | Each RIL Socket Read (for a solicited response) has the following format: | ||
* Byte 0x00 - uint32_t - Header (Size of Following Parcel) | |||
** PARCEL BEGINS AFTER THIS FIELD | |||
* Byte 0x04 - uint32_t - 1 (To signify it is a reply to a previously sent solicited request) | |||
* Byte 0x08 - uint32_t - RIL Event ID (IDs available in glue/gonk/hardware/ril/include/telephony/ril.h) | |||
* Byte 0x0c - void* - Event Data | |||
The client responds (as needed) to unsolicited events by sending a | The client responds (as needed) to unsolicited events by sending a | ||
Line 123: | Line 113: | ||
the fields in the ril.h file. | the fields in the ril.h file. | ||
= Phone Workflow = | |||
== Initialization == | |||
The initialization step is required to turn the radio on. | The initialization step is required to turn the radio on. | ||
- Program connects to rild socket | - Program connects to rild socket | ||
Line 130: | Line 122: | ||
- Program: SCREEN_STATE to TRUE | - Program: SCREEN_STATE to TRUE | ||
- Program: RADIO_POWER (Turns radio on, if radio status is RADIO_STATE_OFF) | - Program: RADIO_POWER (Turns radio on, if radio status is RADIO_STATE_OFF) | ||
== Service Status Update == | |||
* Radio: UNSOL_RESPONSE_NETWORK_STATE_CHANGED | |||
* Program: OPERATOR | |||
* Program: REGISTRATION_STATE | |||
* Program: GPRS_REGISTRATION_STATE | |||
== Dialing == | |||
* Go through initialization and Service Status Update steps | |||
* Program: DIAL | |||
== Hanging Up == | |||
- Android app usually sends REQUEST_HANGUP_FOREGROUND_RESUME_BACKGROUND | - Android app usually sends REQUEST_HANGUP_FOREGROUND_RESUME_BACKGROUND | ||
- Continually checks GET_CURRENT_CALLS, which may error the first time around? | - Continually checks GET_CURRENT_CALLS, which may error the first time around? [https://github.com/kmachulis-mozilla/b2g-dialer-test/issues/13] | ||
== Call Receive == | |||
== SMS Receive == | |||
* Radio: UNSOL_RESPONSE_NEW_SMS | |||
For preliminary design documentation of WebTelephony/WebAPI, see | * Program: RIL_REQUEST_SMS_ACKNOWLEDGE | ||
= Gecko Design = | |||
For preliminary design documentation of WebTelephony/WebAPI, see [https://wiki.mozilla.org/WebAPI/WebTelephony] | |||
== Design Overview == | |||
The RIL communications system will consist events in the context of 3 | The RIL communications system will consist events in the context of 3 | ||
threads, as well as a socket proxy daemon: | threads, as well as a socket proxy daemon: | ||
* The IPC Thread, where IO to the Radio Socket will happen | |||
* A JS Worker thread, where low level telephony support (parsing | |||
parcels to/from socket, dealing with GSM/CDMA/SIP and SIM card | parcels to/from socket, dealing with GSM/CDMA/SIP and SIM card | ||
commands, etc...) will be implemented | commands, etc...) will be implemented | ||
* The Main Gecko Thread, where the Telephony DOM will expose high | |||
level commands to the navigator.phone object. | level commands to the navigator.phone object. | ||
== Radio Base Class - IO Thread == | |||
The Radio Base Class declares the basic communication function | The Radio Base Class declares the basic communication function | ||
signatures for radios, as well as managing a queue of binary blobs | signatures for radios, as well as managing a queue of binary blobs | ||
Line 166: | Line 171: | ||
use) creation up into the Telephone class, keeping Radio in its own | use) creation up into the Telephone class, keeping Radio in its own | ||
thread to deal with I/O. | thread to deal with I/O. | ||
== Radio JS Worker Thread == | |||
The Radio Implementation class will handle | The Radio Implementation class will handle | ||
* Providing an interface to phone status (Network Name, Signal | |||
Strength, Current Calls, Radio Events, etc...) | Strength, Current Calls, Radio Events, etc...) | ||
* Creating and Managing data in flight from/to the radio | |||
Radio communication at the parcel level happens in the worker thread, | Radio communication at the parcel level happens in the worker thread, | ||
Line 178: | Line 185: | ||
incoming calls. | incoming calls. | ||
== Telephony DOM == | |||
The Telephone class is responsible for exposing high level functions | The Telephone class is responsible for exposing high level functions | ||
to Javascript (Dial, Hangup, SMS, etc...). More information on this is | to Javascript (Dial, Hangup, SMS, etc...). More information on this is | ||
available as part of the WebTelephony project. | available as part of the WebTelephony project. | ||
* Utilities and Tips | * Utilities and Tips | ||
** Building | ** Building | ||
* Set the path of your local Android NDK and B2G, i.e. export | |||
NDK=/opt/android-ndk-r6b | NDK=/opt/android-ndk-r6b | ||
* Run scripts/android_env.sh | |||
* cmake . | |||
* make | |||
make | |||
== Relevant Websites == | |||
* [[http://i-miss-erin.blogspot.com/2009/11/radio-layer-interface-in-android.html][Hooking up Android to a GSM radio on the BeagleBoard]] | |||
* [[http://www.netmite.com/android/mydroid/development/pdk/docs/telephony.html][libril Documentation]] | |||
* [[https://groups.google.com/forum/#!topic/android-porting/lo90a3Bb1nA][Small thread on ril stuff]] | |||
* [[http://www.slideshare.net/ssusere3af56/android-radio-layer-interface][Android Radio Interface Layer]] | |||
* [[http://www.slideshare.net/dpsmarques/android-telephony-stack][Android Telephony Stack]] | |||
= Relevant Bugs = | = Relevant Bugs = |
Revision as of 22:22, 3 November 2011
B2G RIL
This page contains information about B2G's interaction with the Radio Interface Layer of Android. The RIL provides access to the radio hardware, which is needed to send/receive calls, SMS messages, and other things that require interaction with a cell network.
Talking to the Radio
Low Level Access
Kernel access for specific phones are vendor specific, included in the phone's firmware distribution. To access these drivers, android uses the libril library. Information on libril and android's telephony architecture is available at
Source code for libril and rild is available in the B2G checkout as
glue/gonk/hardware/ril
Socket Access
In order to access libril, android uses an ipc socket interface to the rild daemon. The daemon simply creates a socket named "rild" and manages transfers of ipc parcels (http://developer.android.com/reference/android/os/Parcel.html) through it.
A sample emulator implementation of rild is available alongside the libril source code. Actual rild implementations for phones are proprietary and distributed by the vendor.
Due to wanting a single event source for dealing with events, the rild socket requires exclusive access from a single process. In a normal android installation, this would happen via the com.android.phone process. In order to make our own code talk to the socket, the current strategy is to change the socket name in the RIL.java file to something other than "rild" (since we can't recompile vendor specific rild).
Android Access
Android code specific to RIL communication is in
glue/gonk/frameworks/base/telephony/java/com/android/internal/telephony/RIL.java
The Java code communicates with the rild socket via the Binder IPC system, using objects known as Parcels. Parcels are simply flattened, serialized data structures. libbinder exists for C++ in glue/gonk/frameworks.
To access sockets via C, android uses libcutils, also available in glue/gonk/frameworks.
Parcel Formats
Parcels contain information about the transaction that they are a part of, as well as event data.
Event data will be one of the follow types:
- Void * No return
- Int List * First int is the number of ints in the list, followed by the ints
- Byte 0x0c - uint32_t - number of ints in the packet
- Byte 0x10 - uint32_t- - list of ints
- String - A single string (16-bit)
- Byte 0x0c - uint32_t - length of string
- Byte 0x10 - wchar_t- - string of length specified
- Strings - An array of strings (16-bit)
- Byte 0x0c - uint32_t - number of strings
- Byte 0x10 - Strings - strings in format listed for single string (size + string)
- Custom Struct * A set of different types specific to the message (SMS messages, call lists, etc...)
RIL Parcel - Process -> rild
Each RIL Socket Write has the following format:
- Byte 0x00 - uint32_t - Header (Size of Following Parcel)
- PARCEL BEGINS AFTER THIS FIELD
- Byte 0x04 - uint32_t - RIL Event ID (IDs available in glue/gonk/hardware/ril/include/telephony/ril.h)
- Byte 0x08 - uint32_t - Packet Serial Number (Used to track send/receive order)
- Byte 0x0c - void* - Event Data
RIL Parcel - rild -> Process (solicited reply)
Each RIL Socket Read (for a solicited response) has the following format:
- Byte 0x00 - uint32_t - Header (Size of Following Parcel)
- PARCEL BEGINS AFTER THIS FIELD
- Byte 0x04 - uint32_t - 0 (To signify it is a reply to a previously sent solicited request)
- Byte 0x08 - uint32_t - Packet Serial Number (Used to track send/receive order)
- Byte 0x0c - void* - Event Data
It is expected that the client maintains a list of previously made solicited requests to match the replies to, via the serial field.
The expectations of each RIL event are outlined in the comments for the fields in the ril.h file.
RIL Parcel - rild -> Process (unsolicited event)
Each RIL Socket Read (for a solicited response) has the following format:
- Byte 0x00 - uint32_t - Header (Size of Following Parcel)
- PARCEL BEGINS AFTER THIS FIELD
- Byte 0x04 - uint32_t - 1 (To signify it is a reply to a previously sent solicited request)
- Byte 0x08 - uint32_t - RIL Event ID (IDs available in glue/gonk/hardware/ril/include/telephony/ril.h)
- Byte 0x0c - void* - Event Data
The client responds (as needed) to unsolicited events by sending a solicited event, which follows the outline mentioned above.
The expectations of each RIL event are outlined in the comments for the fields in the ril.h file.
Phone Workflow
Initialization
The initialization step is required to turn the radio on. - Program connects to rild socket - Radio: UNSOL_RESPONSE_RADIO_STATE_CHANGED with radio status - Program: SCREEN_STATE to TRUE - Program: RADIO_POWER (Turns radio on, if radio status is RADIO_STATE_OFF)
Service Status Update
- Radio: UNSOL_RESPONSE_NETWORK_STATE_CHANGED
- Program: OPERATOR
- Program: REGISTRATION_STATE
- Program: GPRS_REGISTRATION_STATE
Dialing
- Go through initialization and Service Status Update steps
- Program: DIAL
Hanging Up
- Android app usually sends REQUEST_HANGUP_FOREGROUND_RESUME_BACKGROUND - Continually checks GET_CURRENT_CALLS, which may error the first time around? [2]
Call Receive
SMS Receive
- Radio: UNSOL_RESPONSE_NEW_SMS
- Program: RIL_REQUEST_SMS_ACKNOWLEDGE
Gecko Design
For preliminary design documentation of WebTelephony/WebAPI, see [3]
Design Overview
The RIL communications system will consist events in the context of 3 threads, as well as a socket proxy daemon:
- The IPC Thread, where IO to the Radio Socket will happen
- A JS Worker thread, where low level telephony support (parsing
parcels to/from socket, dealing with GSM/CDMA/SIP and SIM card commands, etc...) will be implemented
- The Main Gecko Thread, where the Telephony DOM will expose high
level commands to the navigator.phone object.
Radio Base Class - IO Thread
The Radio Base Class declares the basic communication function signatures for radios, as well as managing a queue of binary blobs coming from and going to the radio. It contains no knowledge of the blob structure, just blob length and the blobs themselves. This means we can push the Parcel (or whatever serialization method we decide to use) creation up into the Telephone class, keeping Radio in its own thread to deal with I/O.
Radio JS Worker Thread
The Radio Implementation class will handle
- Providing an interface to phone status (Network Name, Signal
Strength, Current Calls, Radio Events, etc...)
- Creating and Managing data in flight from/to the radio
Radio communication at the parcel level happens in the worker thread, which then queues the serialized binary blobs to the Radio I/O thread. It also reads information sent from the radio, to trigger events like incoming calls.
Telephony DOM
The Telephone class is responsible for exposing high level functions to Javascript (Dial, Hangup, SMS, etc...). More information on this is available as part of the WebTelephony project.
- Utilities and Tips
- Building
- Set the path of your local Android NDK and B2G, i.e. export
NDK=/opt/android-ndk-r6b
- Run scripts/android_env.sh
- cmake .
- make
Relevant Websites
- [[4][Hooking up Android to a GSM radio on the BeagleBoard]]
- [[5][libril Documentation]]
- [[6][Small thread on ril stuff]]
- [[7][Android Radio Interface Layer]]
- [[8][Android Telephony Stack]]
Relevant Bugs
- https://bugzilla.mozilla.org/show_bug.cgi?id=699235 - Main bug for JS RIL Implementation
- https://bugzilla.mozilla.org/show_bug.cgi?id=674726 - WebTelephony
- https://www.github.com/kmachulis-mozilla/b2g-dialer-daemon/issues - Tasks for underlying utilities for accessing radio daemon/socket on phone