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 caif_payload_info;
15
16 #define CAIF_LAYER_NAME_SZ 16
17
18 /**
19 * caif_assert() - Assert function for CAIF.
20 * @assert: expression to evaluate.
21 *
22 * This function will print a error message and a do WARN_ON if the
23 * assertion failes. Normally this will do a stack up at the current location.
24 */
25 #define caif_assert(assert) \
26 do { \
27 if (!(assert)) { \
28 pr_err("caif:Assert detected:'%s'\n", #assert); \
29 WARN_ON(!(assert)); \
30 } \
31 } while (0)
32
33 /**
34 * enum caif_ctrlcmd - CAIF Stack Control Signaling sent in layer.ctrlcmd().
35 *
36 * @CAIF_CTRLCMD_FLOW_OFF_IND: Flow Control is OFF, transmit function
37 * should stop sending data
38 *
39 * @CAIF_CTRLCMD_FLOW_ON_IND: Flow Control is ON, transmit function
40 * can start sending data
41 *
42 * @CAIF_CTRLCMD_REMOTE_SHUTDOWN_IND: Remote end modem has decided to close
43 * down channel
44 *
45 * @CAIF_CTRLCMD_INIT_RSP: Called initially when the layer below
46 * has finished initialization
47 *
48 * @CAIF_CTRLCMD_DEINIT_RSP: Called when de-initialization is
49 * complete
50 *
51 * @CAIF_CTRLCMD_INIT_FAIL_RSP: Called if initialization fails
52 *
53 * @_CAIF_CTRLCMD_PHYIF_FLOW_OFF_IND: CAIF Link layer temporarily cannot
54 * send more packets.
55 * @_CAIF_CTRLCMD_PHYIF_FLOW_ON_IND: Called if CAIF Link layer is able
56 * to send packets again.
57 * @_CAIF_CTRLCMD_PHYIF_DOWN_IND: Called if CAIF Link layer is going
58 * down.
59 *
60 * These commands are sent upwards in the CAIF stack to the CAIF Client.
61 * They are used for signaling originating from the modem or CAIF Link Layer.
62 * These are either responses (*_RSP) or events (*_IND).
63 */
64 enum caif_ctrlcmd {
65 CAIF_CTRLCMD_FLOW_OFF_IND,
66 CAIF_CTRLCMD_FLOW_ON_IND,
67 CAIF_CTRLCMD_REMOTE_SHUTDOWN_IND,
68 CAIF_CTRLCMD_INIT_RSP,
69 CAIF_CTRLCMD_DEINIT_RSP,
70 CAIF_CTRLCMD_INIT_FAIL_RSP,
71 _CAIF_CTRLCMD_PHYIF_FLOW_OFF_IND,
72 _CAIF_CTRLCMD_PHYIF_FLOW_ON_IND,
73 _CAIF_CTRLCMD_PHYIF_DOWN_IND,
74 };
75
76 /**
77 * enum caif_modemcmd - Modem Control Signaling, sent from CAIF Client
78 * to the CAIF Link Layer or modem.
79 *
80 * @CAIF_MODEMCMD_FLOW_ON_REQ: Flow Control is ON, transmit function
81 * can start sending data.
82 *
83 * @CAIF_MODEMCMD_FLOW_OFF_REQ: Flow Control is OFF, transmit function
84 * should stop sending data.
85 *
86 * @_CAIF_MODEMCMD_PHYIF_USEFULL: Notify physical layer that it is in use
87 *
88 * @_CAIF_MODEMCMD_PHYIF_USELESS: Notify physical layer that it is
89 * no longer in use.
90 *
91 * These are requests sent 'downwards' in the stack.
92 * Flow ON, OFF can be indicated to the modem.
93 */
94 enum caif_modemcmd {
95 CAIF_MODEMCMD_FLOW_ON_REQ = 0,
96 CAIF_MODEMCMD_FLOW_OFF_REQ = 1,
97 _CAIF_MODEMCMD_PHYIF_USEFULL = 3,
98 _CAIF_MODEMCMD_PHYIF_USELESS = 4
99 };
100
101 /**
102 * enum caif_direction - CAIF Packet Direction.
103 * Indicate if a packet is to be sent out or to be received in.
104 * @CAIF_DIR_IN: Incoming packet received.
105 * @CAIF_DIR_OUT: Outgoing packet to be transmitted.
106 */
107 enum caif_direction {
108 CAIF_DIR_IN = 0,
109 CAIF_DIR_OUT = 1
110 };
111
112 /**
113 * struct cflayer - CAIF Stack layer.
114 * Defines the framework for the CAIF Core Stack.
115 * @up: Pointer up to the layer above.
116 * @dn: Pointer down to the layer below.
117 * @node: List node used when layer participate in a list.
118 * @receive: Packet receive function.
119 * @transmit: Packet transmit funciton.
120 * @ctrlcmd: Used for control signalling upwards in the stack.
121 * @modemcmd: Used for control signaling downwards in the stack.
122 * @id: The identity of this layer
123 * @name: Name of the layer.
124 *
125 * This structure defines the layered structure in CAIF.
126 *
127 * It defines CAIF layering structure, used by all CAIF Layers and the
128 * layers interfacing CAIF.
129 *
130 * In order to integrate with CAIF an adaptation layer on top of the CAIF stack
131 * and PHY layer below the CAIF stack
132 * must be implemented. These layer must follow the design principles below.
133 *
134 * Principles for layering of protocol layers:
135 * - All layers must use this structure. If embedding it, then place this
136 * structure first in the layer specific structure.
137 *
138 * - Each layer should not depend on any others layer's private data.
139 *
140 * - In order to send data upwards do
141 * layer->up->receive(layer->up, packet);
142 *
143 * - In order to send data downwards do
144 * layer->dn->transmit(layer->dn, info, packet);
145 */
146 struct cflayer {
147 struct cflayer *up;
148 struct cflayer *dn;
149 struct list_head node;
150
151 /*
152 * receive() - Receive Function (non-blocking).
153 * Contract: Each layer must implement a receive function passing the
154 * CAIF packets upwards in the stack.
155 * Packet handling rules:
156 * - The CAIF packet (cfpkt) ownership is passed to the
157 * called receive function. This means that the
158 * packet cannot be accessed after passing it to the
159 * above layer using up->receive().
160 *
161 * - If parsing of the packet fails, the packet must be
162 * destroyed and negative error code returned
163 * from the function.
164 * EXCEPTION: If the framing layer (cffrml) returns
165 * -EILSEQ, the packet is not freed.
166 *
167 * - If parsing succeeds (and above layers return OK) then
168 * the function must return a value >= 0.
169 *
170 * Returns result < 0 indicates an error, 0 or positive value
171 * indicates success.
172 *
173 * @layr: Pointer to the current layer the receive function is
174 * implemented for (this pointer).
175 * @cfpkt: Pointer to CaifPacket to be handled.
176 */
177 int (*receive)(struct cflayer *layr, struct cfpkt *cfpkt);
178
179 /*
180 * transmit() - Transmit Function (non-blocking).
181 * Contract: Each layer must implement a transmit function passing the
182 * CAIF packet downwards in the stack.
183 * Packet handling rules:
184 * - The CAIF packet (cfpkt) ownership is passed to the
185 * transmit function. This means that the packet
186 * cannot be accessed after passing it to the below
187 * layer using dn->transmit().
188 *
189 * - Upon error the packet ownership is still passed on,
190 * so the packet shall be freed where error is detected.
191 * Callers of the transmit function shall not free packets,
192 * but errors shall be returned.
193 *
194 * - Return value less than zero means error, zero or
195 * greater than zero means OK.
196 *
197 * Returns result < 0 indicates an error, 0 or positive value
198 * indicates success.
199 *
200 * @layr: Pointer to the current layer the receive function
201 * isimplemented for (this pointer).
202 * @cfpkt: Pointer to CaifPacket to be handled.
203 */
204 int (*transmit) (struct cflayer *layr, struct cfpkt *cfpkt);
205
206 /*
207 * cttrlcmd() - Control Function upwards in CAIF Stack (non-blocking).
208 * Used for signaling responses (CAIF_CTRLCMD_*_RSP)
209 * and asynchronous events from the modem (CAIF_CTRLCMD_*_IND)
210 *
211 * @layr: Pointer to the current layer the receive function
212 * is implemented for (this pointer).
213 * @ctrl: Control Command.
214 */
215 void (*ctrlcmd) (struct cflayer *layr, enum caif_ctrlcmd ctrl,
216 int phyid);
217
218 /*
219 * modemctrl() - Control Function used for controlling the modem.
220 * Used to signal down-wards in the CAIF stack.
221 * Returns 0 on success, < 0 upon failure.
222 *
223 * @layr: Pointer to the current layer the receive function
224 * is implemented for (this pointer).
225 * @ctrl: Control Command.
226 */
227 int (*modemcmd) (struct cflayer *layr, enum caif_modemcmd ctrl);
228
229 unsigned int id;
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
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.