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 |
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 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_ */ |
280 | |