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