Skip to content

Commit edc7616

Browse files
Sjur Braendelanddavem330
Sjur Braendeland
authored and
davem330
committed
net-caif: add CAIF documentation
Documentation of the CAIF Protocol. Signed-off-by: Sjur Braendeland <[email protected]> Signed-off-by: David S. Miller <[email protected]>
1 parent 3908c69 commit edc7616

File tree

2 files changed

+321
-0
lines changed

2 files changed

+321
-0
lines changed

‎Documentation/networking/caif/Linux-CAIF.txt

Lines changed: 212 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,212 @@
1+
Linux CAIF
2+
===========
3+
copyright (C) ST-Ericsson AB 2010
4+
Author: Sjur Brendeland/ [email protected]
5+
License terms: GNU General Public License (GPL) version 2
6+
7+
8+
Introduction
9+
------------
10+
CAIF is a MUX protocol used by ST-Ericsson cellular modems for
11+
communication between Modem and host. The host processes can open virtual AT
12+
channels, initiate GPRS Data connections, Video channels and Utility Channels.
13+
The Utility Channels are general purpose pipes between modem and host.
14+
15+
ST-Ericsson modems support a number of transports between modem
16+
and host. Currently, UART and Loopback are available for Linux.
17+
18+
19+
Architecture:
20+
------------
21+
The implementation of CAIF is divided into:
22+
* CAIF Socket Layer, Kernel API, and Net Device.
23+
* CAIF Core Protocol Implementation
24+
* CAIF Link Layer, implemented as NET devices.
25+
26+
27+
RTNL
28+
!
29+
! +------+ +------+ +------+
30+
! +------+! +------+! +------+!
31+
! ! Sock !! !Kernel!! ! Net !!
32+
! ! API !+ ! API !+ ! Dev !+ <- CAIF Client APIs
33+
! +------+ +------! +------+
34+
! ! ! !
35+
! +----------!----------+
36+
! +------+ <- CAIF Protocol Implementation
37+
+-------> ! CAIF !
38+
! Core !
39+
+------+
40+
+--------!--------+
41+
! !
42+
+------+ +-----+
43+
! ! ! TTY ! <- Link Layer (Net Devices)
44+
+------+ +-----+
45+
46+
47+
Using the Kernel API
48+
----------------------
49+
The Kernel API is used for accessing CAIF channels from the
50+
kernel.
51+
The user of the API has to implement two callbacks for receive
52+
and control.
53+
The receive callback gives a CAIF packet as a SKB. The control
54+
callback will
55+
notify of channel initialization complete, and flow-on/flow-
56+
off.
57+
58+
59+
struct caif_device caif_dev = {
60+
.caif_config = {
61+
.name = "MYDEV"
62+
.type = CAIF_CHTY_AT
63+
}
64+
.receive_cb = my_receive,
65+
.control_cb = my_control,
66+
};
67+
caif_add_device(&caif_dev);
68+
caif_transmit(&caif_dev, skb);
69+
70+
See the caif_kernel.h for details about the CAIF kernel API.
71+
72+
73+
I M P L E M E N T A T I O N
74+
===========================
75+
===========================
76+
77+
CAIF Core Protocol Layer
78+
=========================================
79+
80+
CAIF Core layer implements the CAIF protocol as defined by ST-Ericsson.
81+
It implements the CAIF protocol stack in a layered approach, where
82+
each layer described in the specification is implemented as a separate layer.
83+
The architecture is inspired by the design patterns "Protocol Layer" and
84+
"Protocol Packet".
85+
86+
== CAIF structure ==
87+
The Core CAIF implementation contains:
88+
- Simple implementation of CAIF.
89+
- Layered architecture (a la Streams), each layer in the CAIF
90+
specification is implemented in a separate c-file.
91+
- Clients must implement PHY layer to access physical HW
92+
with receive and transmit functions.
93+
- Clients must call configuration function to add PHY layer.
94+
- Clients must implement CAIF layer to consume/produce
95+
CAIF payload with receive and transmit functions.
96+
- Clients must call configuration function to add and connect the
97+
Client layer.
98+
- When receiving / transmitting CAIF Packets (cfpkt), ownership is passed
99+
to the called function (except for framing layers' receive functions
100+
or if a transmit function returns an error, in which case the caller
101+
must free the packet).
102+
103+
Layered Architecture
104+
--------------------
105+
The CAIF protocol can be divided into two parts: Support functions and Protocol
106+
Implementation. The support functions include:
107+
108+
- CFPKT CAIF Packet. Implementation of CAIF Protocol Packet. The
109+
CAIF Packet has functions for creating, destroying and adding content
110+
and for adding/extracting header and trailers to protocol packets.
111+
112+
- CFLST CAIF list implementation.
113+
114+
- CFGLUE CAIF Glue. Contains OS Specifics, such as memory
115+
allocation, endianness, etc.
116+
117+
The CAIF Protocol implementation contains:
118+
119+
- CFCNFG CAIF Configuration layer. Configures the CAIF Protocol
120+
Stack and provides a Client interface for adding Link-Layer and
121+
Driver interfaces on top of the CAIF Stack.
122+
123+
- CFCTRL CAIF Control layer. Encodes and Decodes control messages
124+
such as enumeration and channel setup. Also matches request and
125+
response messages.
126+
127+
- CFSERVL General CAIF Service Layer functionality; handles flow
128+
control and remote shutdown requests.
129+
130+
- CFVEI CAIF VEI layer. Handles CAIF AT Channels on VEI (Virtual
131+
External Interface). This layer encodes/decodes VEI frames.
132+
133+
- CFDGML CAIF Datagram layer. Handles CAIF Datagram layer (IP
134+
traffic), encodes/decodes Datagram frames.
135+
136+
- CFMUX CAIF Mux layer. Handles multiplexing between multiple
137+
physical bearers and multiple channels such as VEI, Datagram, etc.
138+
The MUX keeps track of the existing CAIF Channels and
139+
Physical Instances and selects the apropriate instance based
140+
on Channel-Id and Physical-ID.
141+
142+
- CFFRML CAIF Framing layer. Handles Framing i.e. Frame length
143+
and frame checksum.
144+
145+
- CFSERL CAIF Serial layer. Handles concatenation/split of frames
146+
into CAIF Frames with correct length.
147+
148+
149+
150+
+---------+
151+
| Config |
152+
| CFCNFG |
153+
+---------+
154+
!
155+
+---------+ +---------+ +---------+
156+
| AT | | Control | | Datagram|
157+
| CFVEIL | | CFCTRL | | CFDGML |
158+
+---------+ +---------+ +---------+
159+
\_____________!______________/
160+
!
161+
+---------+
162+
| MUX |
163+
| |
164+
+---------+
165+
_____!_____
166+
/ \
167+
+---------+ +---------+
168+
| CFFRML | | CFFRML |
169+
| Framing | | Framing |
170+
+---------+ +---------+
171+
! !
172+
+---------+ +---------+
173+
| | | Serial |
174+
| | | CFSERL |
175+
+---------+ +---------+
176+
177+
178+
In this layered approach the following "rules" apply.
179+
- All layers embed the same structure "struct cflayer"
180+
- A layer does not depend on any other layer's private data.
181+
- Layers are stacked by setting the pointers
182+
layer->up , layer->dn
183+
- In order to send data upwards, each layer should do
184+
layer->up->receive(layer->up, packet);
185+
- In order to send data downwards, each layer should do
186+
layer->dn->transmit(layer->dn, packet);
187+
188+
189+
Linux Driver Implementation
190+
===========================
191+
192+
Linux GPRS Net Device and CAIF socket are implemented on top of the
193+
CAIF Core protocol. The Net device and CAIF socket have an instance of
194+
'struct cflayer', just like the CAIF Core protocol stack.
195+
Net device and Socket implement the 'receive()' function defined by
196+
'struct cflayer', just like the rest of the CAIF stack. In this way, transmit and
197+
receive of packets is handled as by the rest of the layers: the 'dn->transmit()'
198+
function is called in order to transmit data.
199+
200+
The layer on top of the CAIF Core implementation is
201+
sometimes referred to as the "Client layer".
202+
203+
204+
Configuration of Link Layer
205+
---------------------------
206+
The Link Layer is implemented as Linux net devices (struct net_device).
207+
Payload handling and registration is done using standard Linux mechanisms.
208+
209+
The CAIF Protocol relies on a loss-less link layer without implementing
210+
retransmission. This implies that packet drops must not happen.
211+
Therefore a flow-control mechanism is implemented where the physical
212+
interface can initiate flow stop for all CAIF Channels.

‎Documentation/networking/caif/README

Lines changed: 109 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,109 @@
1+
Copyright (C) ST-Ericsson AB 2010
2+
Author: Sjur Brendeland/ [email protected]
3+
License terms: GNU General Public License (GPL) version 2
4+
---------------------------------------------------------
5+
6+
=== Start ===
7+
If you have compiled CAIF for modules do:
8+
9+
$modprobe crc_ccitt
10+
$modprobe caif
11+
$modprobe caif_socket
12+
$modprobe chnl_net
13+
14+
15+
=== Preparing the setup with a STE modem ===
16+
17+
If you are working on integration of CAIF you should make sure
18+
that the kernel is built with module support.
19+
20+
There are some things that need to be tweaked to get the host TTY correctly
21+
set up to talk to the modem.
22+
Since the CAIF stack is running in the kernel and we want to use the existing
23+
TTY, we are installing our physical serial driver as a line discipline above
24+
the TTY device.
25+
26+
To achieve this we need to install the N_CAIF ldisc from user space.
27+
The benefit is that we can hook up to any TTY.
28+
29+
The use of Start-of-frame-extension (STX) must also be set as
30+
module parameter "ser_use_stx".
31+
32+
Normally Frame Checksum is always used on UART, but this is also provided as a
33+
module parameter "ser_use_fcs".
34+
35+
$ modprobe caif_serial ser_ttyname=/dev/ttyS0 ser_use_stx=yes
36+
$ ifconfig caif_ttyS0 up
37+
38+
PLEASE NOTE: There is a limitation in Android shell.
39+
It only accepts one argument to insmod/modprobe!
40+
41+
=== Trouble shooting ===
42+
43+
There are debugfs parameters provided for serial communication.
44+
/sys/kernel/debug/caif_serial/<tty-name>/
45+
46+
* ser_state: Prints the bit-mask status where
47+
- 0x02 means SENDING, this is a transient state.
48+
- 0x10 means FLOW_OFF_SENT, i.e. the previous frame has not been sent
49+
and is blocking further send operation. Flow OFF has been propagated
50+
to all CAIF Channels using this TTY.
51+
52+
* tty_status: Prints the bit-mask tty status information
53+
- 0x01 - tty->warned is on.
54+
- 0x02 - tty->low_latency is on.
55+
- 0x04 - tty->packed is on.
56+
- 0x08 - tty->flow_stopped is on.
57+
- 0x10 - tty->hw_stopped is on.
58+
- 0x20 - tty->stopped is on.
59+
60+
* last_tx_msg: Binary blob Prints the last transmitted frame.
61+
This can be printed with
62+
$od --format=x1 /sys/kernel/debug/caif_serial/<tty>/last_rx_msg.
63+
The first two tx messages sent look like this. Note: The initial
64+
byte 02 is start of frame extension (STX) used for re-syncing
65+
upon errors.
66+
67+
- Enumeration:
68+
0000000 02 05 00 00 03 01 d2 02
69+
| | | | | |
70+
STX(1) | | | |
71+
Length(2)| | |
72+
Control Channel(1)
73+
Command:Enumeration(1)
74+
Link-ID(1)
75+
Checksum(2)
76+
- Channel Setup:
77+
0000000 02 07 00 00 00 21 a1 00 48 df
78+
| | | | | | | |
79+
STX(1) | | | | | |
80+
Length(2)| | | | |
81+
Control Channel(1)
82+
Command:Channel Setup(1)
83+
Channel Type(1)
84+
Priority and Link-ID(1)
85+
Endpoint(1)
86+
Checksum(2)
87+
88+
* last_rx_msg: Prints the last transmitted frame.
89+
The RX messages for LinkSetup look almost identical but they have the
90+
bit 0x20 set in the command bit, and Channel Setup has added one byte
91+
before Checksum containing Channel ID.
92+
NOTE: Several CAIF Messages might be concatenated. The maximum debug
93+
buffer size is 128 bytes.
94+
95+
== Error Scenarios:
96+
- last_tx_msg contains channel setup message and last_rx_msg is empty ->
97+
The host seems to be able to send over the UART, at least the CAIF ldisc get
98+
notified that sending is completed.
99+
100+
- last_tx_msg contains enumeration message and last_rx_msg is empty ->
101+
The host is not able to send the message from UART, the tty has not been
102+
able to complete the transmit operation.
103+
104+
- if /sys/kernel/debug/caif_serial/<tty>/tty_status is non-zero there
105+
might be problems transmitting over UART.
106+
E.g. host and modem wiring is not correct you will typically see
107+
tty_status = 0x10 (hw_stopped) and ser_state = 0x10 (FLOW_OFF_SENT).
108+
You will probably see the enumeration message in last_tx_message
109+
and empty last_rx_message.

0 commit comments

Comments
 (0)