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