include/net/caif/caif_layer.h

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