1 /*
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 
12 struct cflayer;
13 struct cfpkt;
14 struct cfpktq;
15 struct caif_payload_info;
16 struct caif_packet_funcs;
17 
18 
19 #define CAIF_LAYER_NAME_SZ 16
20 
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)					\
29 do {								\
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  */
68 enum 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  */
98 enum 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  */
111 enum 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  */
152 struct 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  */
256 struct 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  */
271 struct 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_ */
278