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 fails. 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 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 */ 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