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