Loading...
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
12struct cflayer;
13struct cfpkt;
14struct cfpktq;
15struct caif_payload_info;
16struct 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) \
28do { \
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 */
66enum 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 */
96enum 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 */
109enum 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 * @prio: Priority of this layer.
125 * @id: The identity of this layer
126 * @type: The type of this layer
127 * @name: Name of the layer.
128 *
129 * This structure defines the layered structure in CAIF.
130 *
131 * It defines CAIF layering structure, used by all CAIF Layers and the
132 * layers interfacing CAIF.
133 *
134 * In order to integrate with CAIF an adaptation layer on top of the CAIF stack
135 * and PHY layer below the CAIF stack
136 * must be implemented. These layer must follow the design principles below.
137 *
138 * Principles for layering of protocol layers:
139 * - All layers must use this structure. If embedding it, then place this
140 * structure first in the layer specific structure.
141 *
142 * - Each layer should not depend on any others layer's private data.
143 *
144 * - In order to send data upwards do
145 * layer->up->receive(layer->up, packet);
146 *
147 * - In order to send data downwards do
148 * layer->dn->transmit(layer->dn, info, packet);
149 */
150struct cflayer {
151 struct cflayer *up;
152 struct cflayer *dn;
153 struct list_head node;
154
155 /*
156 * receive() - Receive Function (non-blocking).
157 * Contract: Each layer must implement a receive function passing the
158 * CAIF packets upwards in the stack.
159 * Packet handling rules:
160 * - The CAIF packet (cfpkt) ownership is passed to the
161 * called receive function. This means that the the
162 * packet cannot be accessed after passing it to the
163 * above layer using up->receive().
164 *
165 * - If parsing of the packet fails, the packet must be
166 * destroyed and negative error code returned
167 * from the function.
168 * EXCEPTION: If the framing layer (cffrml) returns
169 * -EILSEQ, the packet is not freed.
170 *
171 * - If parsing succeeds (and above layers return OK) then
172 * the function must return a value >= 0.
173 *
174 * Returns result < 0 indicates an error, 0 or positive value
175 * indicates success.
176 *
177 * @layr: Pointer to the current layer the receive function is
178 * implemented for (this pointer).
179 * @cfpkt: Pointer to CaifPacket to be handled.
180 */
181 int (*receive)(struct cflayer *layr, struct cfpkt *cfpkt);
182
183 /*
184 * transmit() - Transmit Function (non-blocking).
185 * Contract: Each layer must implement a transmit function passing the
186 * CAIF packet downwards in the stack.
187 * Packet handling rules:
188 * - The CAIF packet (cfpkt) ownership is passed to the
189 * transmit function. This means that the the packet
190 * cannot be accessed after passing it to the below
191 * layer using dn->transmit().
192 *
193 * - Upon error the packet ownership is still passed on,
194 * so the packet shall be freed where error is detected.
195 * Callers of the transmit function shall not free packets,
196 * but errors shall be returned.
197 *
198 * - Return value less than zero means error, zero or
199 * greater than zero means OK.
200 *
201 * Returns result < 0 indicates an error, 0 or positive value
202 * indicates success.
203 *
204 * @layr: Pointer to the current layer the receive function
205 * isimplemented for (this pointer).
206 * @cfpkt: Pointer to CaifPacket to be handled.
207 */
208 int (*transmit) (struct cflayer *layr, struct cfpkt *cfpkt);
209
210 /*
211 * cttrlcmd() - Control Function upwards in CAIF Stack (non-blocking).
212 * Used for signaling responses (CAIF_CTRLCMD_*_RSP)
213 * and asynchronous events from the modem (CAIF_CTRLCMD_*_IND)
214 *
215 * @layr: Pointer to the current layer the receive function
216 * is implemented for (this pointer).
217 * @ctrl: Control Command.
218 */
219 void (*ctrlcmd) (struct cflayer *layr, enum caif_ctrlcmd ctrl,
220 int phyid);
221
222 /*
223 * modemctrl() - Control Function used for controlling the modem.
224 * Used to signal down-wards in the CAIF stack.
225 * Returns 0 on success, < 0 upon failure.
226 *
227 * @layr: Pointer to the current layer the receive function
228 * is implemented for (this pointer).
229 * @ctrl: Control Command.
230 */
231 int (*modemcmd) (struct cflayer *layr, enum caif_modemcmd ctrl);
232
233 unsigned short prio;
234 unsigned int id;
235 unsigned int type;
236 char name[CAIF_LAYER_NAME_SZ];
237};
238
239/**
240 * layer_set_up() - Set the up pointer for a specified layer.
241 * @layr: Layer where up pointer shall be set.
242 * @above: Layer above.
243 */
244#define layer_set_up(layr, above) ((layr)->up = (struct cflayer *)(above))
245
246/**
247 * layer_set_dn() - Set the down pointer for a specified layer.
248 * @layr: Layer where down pointer shall be set.
249 * @below: Layer below.
250 */
251#define layer_set_dn(layr, below) ((layr)->dn = (struct cflayer *)(below))
252
253/**
254 * struct dev_info - Physical Device info information about physical layer.
255 * @dev: Pointer to native physical device.
256 * @id: Physical ID of the physical connection used by the
257 * logical CAIF connection. Used by service layers to
258 * identify their physical id to Caif MUX (CFMUXL)so
259 * that the MUX can add the correct physical ID to the
260 * packet.
261 */
262struct dev_info {
263 void *dev;
264 unsigned int id;
265};
266
267/**
268 * struct caif_payload_info - Payload information embedded in packet (sk_buff).
269 *
270 * @dev_info: Information about the receiving device.
271 *
272 * @hdr_len: Header length, used to align pay load on 32bit boundary.
273 *
274 * @channel_id: Channel ID of the logical CAIF connection.
275 * Used by mux to insert channel id into the caif packet.
276 */
277struct caif_payload_info {
278 struct dev_info *dev_info;
279 unsigned short hdr_len;
280 unsigned short channel_id;
281};
282
283#endif /* CAIF_LAYER_H_ */
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
12struct cflayer;
13struct cfpkt;
14struct 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 fails. Normally this will do a stack up at the current location.
24 */
25#define caif_assert(assert) \
26do { \
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 */
64enum 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 */
94enum 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 */
107enum 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 function.
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 */
146struct 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 */
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_ */