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