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