Commit | Line | Data |
---|---|---|
edc7616c SB |
1 | Linux CAIF |
2 | =========== | |
3 | copyright (C) ST-Ericsson AB 2010 | |
4 | Author: Sjur Brendeland/ sjur.brandeland@stericsson.com | |
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 | |
25985edc | 139 | Physical Instances and selects the appropriate instance based |
edc7616c SB |
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. |