]>
Commit | Line | Data |
---|---|---|
09009f30 SB |
1 | /* |
2 | * Copyright (C) ST-Ericsson AB 2010 | |
26ee65e6 | 3 | * Author: Sjur Brendeland |
09009f30 SB |
4 | * License terms: GNU General Public License (GPL) version 2 |
5 | */ | |
6 | ||
7 | #ifndef CAIF_LAYER_H_ | |
8 | #define CAIF_LAYER_H_ | |
9 | ||
10 | #include <linux/list.h> | |
11 | ||
12 | struct cflayer; | |
13 | struct cfpkt; | |
14 | struct cfpktq; | |
15 | struct caif_payload_info; | |
16 | struct caif_packet_funcs; | |
17 | ||
09009f30 | 18 | #define CAIF_LAYER_NAME_SZ 16 |
09009f30 SB |
19 | |
20 | /** | |
21 | * caif_assert() - Assert function for CAIF. | |
22 | * @assert: expression to evaluate. | |
23 | * | |
24 | * This function will print a error message and a do WARN_ON if the | |
25 | * assertion failes. Normally this will do a stack up at the current location. | |
26 | */ | |
27 | #define caif_assert(assert) \ | |
28 | do { \ | |
29 | if (!(assert)) { \ | |
30 | pr_err("caif:Assert detected:'%s'\n", #assert); \ | |
31 | WARN_ON(!(assert)); \ | |
32 | } \ | |
33 | } while (0) | |
34 | ||
09009f30 SB |
35 | /** |
36 | * enum caif_ctrlcmd - CAIF Stack Control Signaling sent in layer.ctrlcmd(). | |
37 | * | |
38 | * @CAIF_CTRLCMD_FLOW_OFF_IND: Flow Control is OFF, transmit function | |
39 | * should stop sending data | |
40 | * | |
41 | * @CAIF_CTRLCMD_FLOW_ON_IND: Flow Control is ON, transmit function | |
42 | * can start sending data | |
43 | * | |
44 | * @CAIF_CTRLCMD_REMOTE_SHUTDOWN_IND: Remote end modem has decided to close | |
45 | * down channel | |
46 | * | |
47 | * @CAIF_CTRLCMD_INIT_RSP: Called initially when the layer below | |
48 | * has finished initialization | |
49 | * | |
50 | * @CAIF_CTRLCMD_DEINIT_RSP: Called when de-initialization is | |
51 | * complete | |
52 | * | |
53 | * @CAIF_CTRLCMD_INIT_FAIL_RSP: Called if initialization fails | |
54 | * | |
55 | * @_CAIF_CTRLCMD_PHYIF_FLOW_OFF_IND: CAIF Link layer temporarily cannot | |
56 | * send more packets. | |
57 | * @_CAIF_CTRLCMD_PHYIF_FLOW_ON_IND: Called if CAIF Link layer is able | |
58 | * to send packets again. | |
59 | * @_CAIF_CTRLCMD_PHYIF_DOWN_IND: Called if CAIF Link layer is going | |
60 | * down. | |
61 | * | |
62 | * These commands are sent upwards in the CAIF stack to the CAIF Client. | |
63 | * They are used for signaling originating from the modem or CAIF Link Layer. | |
64 | * These are either responses (*_RSP) or events (*_IND). | |
65 | */ | |
66 | enum caif_ctrlcmd { | |
67 | CAIF_CTRLCMD_FLOW_OFF_IND, | |
68 | CAIF_CTRLCMD_FLOW_ON_IND, | |
69 | CAIF_CTRLCMD_REMOTE_SHUTDOWN_IND, | |
70 | CAIF_CTRLCMD_INIT_RSP, | |
71 | CAIF_CTRLCMD_DEINIT_RSP, | |
72 | CAIF_CTRLCMD_INIT_FAIL_RSP, | |
73 | _CAIF_CTRLCMD_PHYIF_FLOW_OFF_IND, | |
74 | _CAIF_CTRLCMD_PHYIF_FLOW_ON_IND, | |
75 | _CAIF_CTRLCMD_PHYIF_DOWN_IND, | |
76 | }; | |
77 | ||
78 | /** | |
79 | * enum caif_modemcmd - Modem Control Signaling, sent from CAIF Client | |
80 | * to the CAIF Link Layer or modem. | |
81 | * | |
82 | * @CAIF_MODEMCMD_FLOW_ON_REQ: Flow Control is ON, transmit function | |
83 | * can start sending data. | |
84 | * | |
85 | * @CAIF_MODEMCMD_FLOW_OFF_REQ: Flow Control is OFF, transmit function | |
86 | * should stop sending data. | |
87 | * | |
88 | * @_CAIF_MODEMCMD_PHYIF_USEFULL: Notify physical layer that it is in use | |
89 | * | |
90 | * @_CAIF_MODEMCMD_PHYIF_USELESS: Notify physical layer that it is | |
91 | * no longer in use. | |
92 | * | |
93 | * These are requests sent 'downwards' in the stack. | |
94 | * Flow ON, OFF can be indicated to the modem. | |
95 | */ | |
96 | enum caif_modemcmd { | |
97 | CAIF_MODEMCMD_FLOW_ON_REQ = 0, | |
98 | CAIF_MODEMCMD_FLOW_OFF_REQ = 1, | |
99 | _CAIF_MODEMCMD_PHYIF_USEFULL = 3, | |
100 | _CAIF_MODEMCMD_PHYIF_USELESS = 4 | |
101 | }; | |
102 | ||
103 | /** | |
104 | * enum caif_direction - CAIF Packet Direction. | |
105 | * Indicate if a packet is to be sent out or to be received in. | |
106 | * @CAIF_DIR_IN: Incoming packet received. | |
107 | * @CAIF_DIR_OUT: Outgoing packet to be transmitted. | |
108 | */ | |
109 | enum caif_direction { | |
110 | CAIF_DIR_IN = 0, | |
111 | CAIF_DIR_OUT = 1 | |
112 | }; | |
113 | ||
114 | /** | |
115 | * struct cflayer - CAIF Stack layer. | |
116 | * Defines the framework for the CAIF Core Stack. | |
117 | * @up: Pointer up to the layer above. | |
118 | * @dn: Pointer down to the layer below. | |
119 | * @node: List node used when layer participate in a list. | |
120 | * @receive: Packet receive function. | |
121 | * @transmit: Packet transmit funciton. | |
122 | * @ctrlcmd: Used for control signalling upwards in the stack. | |
123 | * @modemcmd: Used for control signaling downwards in the stack. | |
09009f30 | 124 | * @id: The identity of this layer |
09009f30 SB |
125 | * @name: Name of the layer. |
126 | * | |
127 | * This structure defines the layered structure in CAIF. | |
128 | * | |
129 | * It defines CAIF layering structure, used by all CAIF Layers and the | |
130 | * layers interfacing CAIF. | |
131 | * | |
132 | * In order to integrate with CAIF an adaptation layer on top of the CAIF stack | |
133 | * and PHY layer below the CAIF stack | |
134 | * must be implemented. These layer must follow the design principles below. | |
135 | * | |
136 | * Principles for layering of protocol layers: | |
137 | * - All layers must use this structure. If embedding it, then place this | |
138 | * structure first in the layer specific structure. | |
139 | * | |
138eded8 | 140 | * - Each layer should not depend on any others layer's private data. |
09009f30 SB |
141 | * |
142 | * - In order to send data upwards do | |
143 | * layer->up->receive(layer->up, packet); | |
144 | * | |
145 | * - In order to send data downwards do | |
146 | * layer->dn->transmit(layer->dn, info, packet); | |
147 | */ | |
148 | struct cflayer { | |
149 | struct cflayer *up; | |
150 | struct cflayer *dn; | |
151 | struct list_head node; | |
152 | ||
153 | /* | |
138eded8 | 154 | * receive() - Receive Function (non-blocking). |
09009f30 SB |
155 | * Contract: Each layer must implement a receive function passing the |
156 | * CAIF packets upwards in the stack. | |
157 | * Packet handling rules: | |
138eded8 | 158 | * - The CAIF packet (cfpkt) ownership is passed to the |
159 | * called receive function. This means that the the | |
160 | * packet cannot be accessed after passing it to the | |
161 | * above layer using up->receive(). | |
162 | * | |
09009f30 | 163 | * - If parsing of the packet fails, the packet must be |
138eded8 | 164 | * destroyed and negative error code returned |
165 | * from the function. | |
166 | * EXCEPTION: If the framing layer (cffrml) returns | |
167 | * -EILSEQ, the packet is not freed. | |
168 | * | |
09009f30 | 169 | * - If parsing succeeds (and above layers return OK) then |
138eded8 | 170 | * the function must return a value >= 0. |
09009f30 SB |
171 | * |
172 | * Returns result < 0 indicates an error, 0 or positive value | |
173 | * indicates success. | |
174 | * | |
175 | * @layr: Pointer to the current layer the receive function is | |
176 | * implemented for (this pointer). | |
177 | * @cfpkt: Pointer to CaifPacket to be handled. | |
178 | */ | |
179 | int (*receive)(struct cflayer *layr, struct cfpkt *cfpkt); | |
180 | ||
181 | /* | |
138eded8 | 182 | * transmit() - Transmit Function (non-blocking). |
09009f30 SB |
183 | * Contract: Each layer must implement a transmit function passing the |
184 | * CAIF packet downwards in the stack. | |
185 | * Packet handling rules: | |
186 | * - The CAIF packet (cfpkt) ownership is passed to the | |
187 | * transmit function. This means that the the packet | |
188 | * cannot be accessed after passing it to the below | |
189 | * layer using dn->transmit(). | |
190 | * | |
138eded8 | 191 | * - Upon error the packet ownership is still passed on, |
192 | * so the packet shall be freed where error is detected. | |
193 | * Callers of the transmit function shall not free packets, | |
194 | * but errors shall be returned. | |
09009f30 SB |
195 | * |
196 | * - Return value less than zero means error, zero or | |
197 | * greater than zero means OK. | |
198 | * | |
138eded8 | 199 | * Returns result < 0 indicates an error, 0 or positive value |
200 | * indicates success. | |
09009f30 SB |
201 | * |
202 | * @layr: Pointer to the current layer the receive function | |
203 | * isimplemented for (this pointer). | |
204 | * @cfpkt: Pointer to CaifPacket to be handled. | |
205 | */ | |
206 | int (*transmit) (struct cflayer *layr, struct cfpkt *cfpkt); | |
207 | ||
208 | /* | |
138eded8 | 209 | * cttrlcmd() - Control Function upwards in CAIF Stack (non-blocking). |
09009f30 SB |
210 | * Used for signaling responses (CAIF_CTRLCMD_*_RSP) |
211 | * and asynchronous events from the modem (CAIF_CTRLCMD_*_IND) | |
212 | * | |
213 | * @layr: Pointer to the current layer the receive function | |
214 | * is implemented for (this pointer). | |
215 | * @ctrl: Control Command. | |
216 | */ | |
217 | void (*ctrlcmd) (struct cflayer *layr, enum caif_ctrlcmd ctrl, | |
218 | int phyid); | |
219 | ||
220 | /* | |
221 | * modemctrl() - Control Function used for controlling the modem. | |
222 | * Used to signal down-wards in the CAIF stack. | |
223 | * Returns 0 on success, < 0 upon failure. | |
224 | * | |
225 | * @layr: Pointer to the current layer the receive function | |
226 | * is implemented for (this pointer). | |
227 | * @ctrl: Control Command. | |
228 | */ | |
229 | int (*modemcmd) (struct cflayer *layr, enum caif_modemcmd ctrl); | |
230 | ||
09009f30 | 231 | unsigned int id; |
09009f30 SB |
232 | char name[CAIF_LAYER_NAME_SZ]; |
233 | }; | |
234 | ||
235 | /** | |
236 | * layer_set_up() - Set the up pointer for a specified layer. | |
237 | * @layr: Layer where up pointer shall be set. | |
238 | * @above: Layer above. | |
239 | */ | |
240 | #define layer_set_up(layr, above) ((layr)->up = (struct cflayer *)(above)) | |
241 | ||
242 | /** | |
243 | * layer_set_dn() - Set the down pointer for a specified layer. | |
244 | * @layr: Layer where down pointer shall be set. | |
245 | * @below: Layer below. | |
246 | */ | |
247 | #define layer_set_dn(layr, below) ((layr)->dn = (struct cflayer *)(below)) | |
248 | ||
249 | /** | |
250 | * struct dev_info - Physical Device info information about physical layer. | |
251 | * @dev: Pointer to native physical device. | |
252 | * @id: Physical ID of the physical connection used by the | |
253 | * logical CAIF connection. Used by service layers to | |
254 | * identify their physical id to Caif MUX (CFMUXL)so | |
255 | * that the MUX can add the correct physical ID to the | |
256 | * packet. | |
257 | */ | |
258 | struct dev_info { | |
259 | void *dev; | |
260 | unsigned int id; | |
261 | }; | |
262 | ||
263 | /** | |
264 | * struct caif_payload_info - Payload information embedded in packet (sk_buff). | |
265 | * | |
266 | * @dev_info: Information about the receiving device. | |
267 | * | |
268 | * @hdr_len: Header length, used to align pay load on 32bit boundary. | |
269 | * | |
270 | * @channel_id: Channel ID of the logical CAIF connection. | |
271 | * Used by mux to insert channel id into the caif packet. | |
272 | */ | |
273 | struct caif_payload_info { | |
274 | struct dev_info *dev_info; | |
275 | unsigned short hdr_len; | |
276 | unsigned short channel_id; | |
277 | }; | |
278 | ||
279 | #endif /* CAIF_LAYER_H_ */ |