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