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_MAX_FRAMESIZE 4096 19 #define CAIF_MAX_PAYLOAD_SIZE (4096 - 64) 20 #define CAIF_NEEDED_HEADROOM (10) 21 #define CAIF_NEEDED_TAILROOM (2) 22 23 #define CAIF_LAYER_NAME_SZ 16 24 #define CAIF_SUCCESS 1 25 #define CAIF_FAILURE 0 26 27 /** 28 * caif_assert() - Assert function for CAIF. 29 * @assert: expression to evaluate. 30 * 31 * This function will print a error message and a do WARN_ON if the 32 * assertion failes. Normally this will do a stack up at the current location. 33 */ 34 #define caif_assert(assert) \ 35 do { \ 36 if (!(assert)) { \ 37 pr_err("caif:Assert detected:'%s'\n", #assert); \ 38 WARN_ON(!(assert)); \ 39 } \ 40 } while (0) 41 42 43 /** 44 * enum caif_ctrlcmd - CAIF Stack Control Signaling sent in layer.ctrlcmd(). 45 * 46 * @CAIF_CTRLCMD_FLOW_OFF_IND: Flow Control is OFF, transmit function 47 * should stop sending data 48 * 49 * @CAIF_CTRLCMD_FLOW_ON_IND: Flow Control is ON, transmit function 50 * can start sending data 51 * 52 * @CAIF_CTRLCMD_REMOTE_SHUTDOWN_IND: Remote end modem has decided to close 53 * down channel 54 * 55 * @CAIF_CTRLCMD_INIT_RSP: Called initially when the layer below 56 * has finished initialization 57 * 58 * @CAIF_CTRLCMD_DEINIT_RSP: Called when de-initialization is 59 * complete 60 * 61 * @CAIF_CTRLCMD_INIT_FAIL_RSP: Called if initialization fails 62 * 63 * @_CAIF_CTRLCMD_PHYIF_FLOW_OFF_IND: CAIF Link layer temporarily cannot 64 * send more packets. 65 * @_CAIF_CTRLCMD_PHYIF_FLOW_ON_IND: Called if CAIF Link layer is able 66 * to send packets again. 67 * @_CAIF_CTRLCMD_PHYIF_DOWN_IND: Called if CAIF Link layer is going 68 * down. 69 * 70 * These commands are sent upwards in the CAIF stack to the CAIF Client. 71 * They are used for signaling originating from the modem or CAIF Link Layer. 72 * These are either responses (*_RSP) or events (*_IND). 73 */ 74 enum caif_ctrlcmd { 75 CAIF_CTRLCMD_FLOW_OFF_IND, 76 CAIF_CTRLCMD_FLOW_ON_IND, 77 CAIF_CTRLCMD_REMOTE_SHUTDOWN_IND, 78 CAIF_CTRLCMD_INIT_RSP, 79 CAIF_CTRLCMD_DEINIT_RSP, 80 CAIF_CTRLCMD_INIT_FAIL_RSP, 81 _CAIF_CTRLCMD_PHYIF_FLOW_OFF_IND, 82 _CAIF_CTRLCMD_PHYIF_FLOW_ON_IND, 83 _CAIF_CTRLCMD_PHYIF_DOWN_IND, 84 }; 85 86 /** 87 * enum caif_modemcmd - Modem Control Signaling, sent from CAIF Client 88 * to the CAIF Link Layer or modem. 89 * 90 * @CAIF_MODEMCMD_FLOW_ON_REQ: Flow Control is ON, transmit function 91 * can start sending data. 92 * 93 * @CAIF_MODEMCMD_FLOW_OFF_REQ: Flow Control is OFF, transmit function 94 * should stop sending data. 95 * 96 * @_CAIF_MODEMCMD_PHYIF_USEFULL: Notify physical layer that it is in use 97 * 98 * @_CAIF_MODEMCMD_PHYIF_USELESS: Notify physical layer that it is 99 * no longer in use. 100 * 101 * These are requests sent 'downwards' in the stack. 102 * Flow ON, OFF can be indicated to the modem. 103 */ 104 enum caif_modemcmd { 105 CAIF_MODEMCMD_FLOW_ON_REQ = 0, 106 CAIF_MODEMCMD_FLOW_OFF_REQ = 1, 107 _CAIF_MODEMCMD_PHYIF_USEFULL = 3, 108 _CAIF_MODEMCMD_PHYIF_USELESS = 4 109 }; 110 111 /** 112 * enum caif_direction - CAIF Packet Direction. 113 * Indicate if a packet is to be sent out or to be received in. 114 * @CAIF_DIR_IN: Incoming packet received. 115 * @CAIF_DIR_OUT: Outgoing packet to be transmitted. 116 */ 117 enum caif_direction { 118 CAIF_DIR_IN = 0, 119 CAIF_DIR_OUT = 1 120 }; 121 122 /** 123 * struct cflayer - CAIF Stack layer. 124 * Defines the framework for the CAIF Core Stack. 125 * @up: Pointer up to the layer above. 126 * @dn: Pointer down to the layer below. 127 * @node: List node used when layer participate in a list. 128 * @receive: Packet receive function. 129 * @transmit: Packet transmit funciton. 130 * @ctrlcmd: Used for control signalling upwards in the stack. 131 * @modemcmd: Used for control signaling downwards in the stack. 132 * @prio: Priority of this layer. 133 * @id: The identity of this layer 134 * @type: The type of this layer 135 * @name: Name of the layer. 136 * 137 * This structure defines the layered structure in CAIF. 138 * 139 * It defines CAIF layering structure, used by all CAIF Layers and the 140 * layers interfacing CAIF. 141 * 142 * In order to integrate with CAIF an adaptation layer on top of the CAIF stack 143 * and PHY layer below the CAIF stack 144 * must be implemented. These layer must follow the design principles below. 145 * 146 * Principles for layering of protocol layers: 147 * - All layers must use this structure. If embedding it, then place this 148 * structure first in the layer specific structure. 149 * 150 * - Each layer should not depend on any others layer private data. 151 * 152 * - In order to send data upwards do 153 * layer->up->receive(layer->up, packet); 154 * 155 * - In order to send data downwards do 156 * layer->dn->transmit(layer->dn, info, packet); 157 */ 158 struct cflayer { 159 struct cflayer *up; 160 struct cflayer *dn; 161 struct list_head node; 162 163 /* 164 * receive() - Receive Function. 165 * Contract: Each layer must implement a receive function passing the 166 * CAIF packets upwards in the stack. 167 * Packet handling rules: 168 * - The CAIF packet (cfpkt) cannot be accessed after 169 * passing it to the next layer using up->receive(). 170 * - If parsing of the packet fails, the packet must be 171 * destroyed and -1 returned from the function. 172 * - If parsing succeeds (and above layers return OK) then 173 * the function must return a value > 0. 174 * 175 * Returns result < 0 indicates an error, 0 or positive value 176 * indicates success. 177 * 178 * @layr: Pointer to the current layer the receive function is 179 * implemented for (this pointer). 180 * @cfpkt: Pointer to CaifPacket to be handled. 181 */ 182 int (*receive)(struct cflayer *layr, struct cfpkt *cfpkt); 183 184 /* 185 * transmit() - Transmit Function. 186 * Contract: Each layer must implement a transmit function passing the 187 * CAIF packet downwards in the stack. 188 * Packet handling rules: 189 * - The CAIF packet (cfpkt) ownership is passed to the 190 * transmit function. This means that the the packet 191 * cannot be accessed after passing it to the below 192 * layer using dn->transmit(). 193 * 194 * - If transmit fails, however, the ownership is returned 195 * to thecaller. The caller of "dn->transmit()" must 196 * destroy or resend packet. 197 * 198 * - Return value less than zero means error, zero or 199 * greater than zero means OK. 200 * 201 * result < 0 indicates an error, 0 or positive value 202 * indicate 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. 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