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 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 * @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 */ 150 struct 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 */ 262 struct 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 */ 277 struct 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_ */ 284