1 /* SPDX-License-Identifier: GPL-2.0-only */
2 /*
3 * Copyright (C) ST-Ericsson AB 2010
4 * Author: Sjur Brendeland
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 #define CAIF_LAYER_NAME_SZ 16
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
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.
124 * @id: The identity of this layer
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 *
140 * - Each layer should not depend on any others layer's private data.
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 /*
154 * receive() - Receive Function (non-blocking).
155 * Contract: Each layer must implement a receive function passing the
156 * CAIF packets upwards in the stack.
157 * Packet handling rules:
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 *
163 * - If parsing of the packet fails, the packet must be
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 *
169 * - If parsing succeeds (and above layers return OK) then
170 * the function must return a value >= 0.
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 /*
182 * transmit() - Transmit Function (non-blocking).
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 *
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.
195 *
196 * - Return value less than zero means error, zero or
197 * greater than zero means OK.
198 *
199 * Returns result < 0 indicates an error, 0 or positive value
200 * indicates success.
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 /*
209 * cttrlcmd() - Control Function upwards in CAIF Stack (non-blocking).
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
231 unsigned int id;
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_ */