include/net/caif/caif_layer.h

   1 /*
   2  * Copyright (C) ST-Ericsson AB 2010
   3  * Author:      Sjur Brendeland
   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  * @id:         The identity of this layer
 125  * @name:       Name of the layer.
 126  *
 127  *  This structure defines the layered structure in CAIF.
 128  *
 129  *  It defines CAIF layering structure, used by all CAIF Layers and the
 130  *  layers interfacing CAIF.
 131  *
 132  *  In order to integrate with CAIF an adaptation layer on top of the CAIF stack
 133  *  and PHY layer below the CAIF stack
 134  *  must be implemented. These layer must follow the design principles below.
 135  *
 136  *  Principles for layering of protocol layers:
 137  *    - All layers must use this structure. If embedding it, then place this
 138  *      structure first in the layer specific structure.
 139  *
 140  *    - Each layer should not depend on any others layer's private data.
 141  *
 142  *    - In order to send data upwards do
 143  *      layer->up->receive(layer->up, packet);
 144  *
 145  *    - In order to send data downwards do
 146  *      layer->dn->transmit(layer->dn, info, packet);
 147  */
 148 struct cflayer {
 149         struct cflayer *up;
 150         struct cflayer *dn;
 151         struct list_head node;
 152
 153         /*
 154          *  receive() - Receive Function (non-blocking).
 155          *  Contract: Each layer must implement a receive function passing the
 156          *  CAIF packets upwards in the stack.
 157          *      Packet handling rules:
 158          *            - The CAIF packet (cfpkt) ownership is passed to the
 159          *              called receive function. This means that the the
 160          *              packet cannot be accessed after passing it to the
 161          *              above layer using up->receive().
 162          *
 163          *            - If parsing of the packet fails, the packet must be
 164          *              destroyed and negative error code returned
 165          *              from the function.
 166          *              EXCEPTION: If the framing layer (cffrml) returns
 167          *                      -EILSEQ, the packet is not freed.
 168          *
 169          *            - If parsing succeeds (and above layers return OK) then
 170          *                    the function must return a value >= 0.
 171          *
 172          *  Returns result < 0 indicates an error, 0 or positive value
 173          *           indicates success.
 174          *
 175          *  @layr: Pointer to the current layer the receive function is
 176          *              implemented for (this pointer).
 177          *  @cfpkt: Pointer to CaifPacket to be handled.
 178          */
 179         int (*receive)(struct cflayer *layr, struct cfpkt *cfpkt);
 180
 181         /*
 182          *  transmit() - Transmit Function (non-blocking).
 183          *  Contract: Each layer must implement a transmit function passing the
 184          *      CAIF packet downwards in the stack.
 185          *      Packet handling rules:
 186          *            - The CAIF packet (cfpkt) ownership is passed to the
 187          *              transmit function. This means that the the packet
 188          *              cannot be accessed after passing it to the below
 189          *              layer using dn->transmit().
 190          *
 191          *            - Upon error the packet ownership is still passed on,
 192          *              so the packet shall be freed where error is detected.
 193          *              Callers of the transmit function shall not free packets,
 194          *              but errors shall be returned.
 195          *
 196          *            - Return value less than zero means error, zero or
 197          *              greater than zero means OK.
 198          *
 199          *  Returns result < 0 indicates an error, 0 or positive value
 200          *              indicates success.
 201          *
 202          *  @layr:      Pointer to the current layer the receive function
 203          *              isimplemented for (this pointer).
 204          *  @cfpkt:      Pointer to CaifPacket to be handled.
 205          */
 206         int (*transmit) (struct cflayer *layr, struct cfpkt *cfpkt);
 207
 208         /*
 209          *  cttrlcmd() - Control Function upwards in CAIF Stack  (non-blocking).
 210          *  Used for signaling responses (CAIF_CTRLCMD_*_RSP)
 211          *  and asynchronous events from the modem  (CAIF_CTRLCMD_*_IND)
 212          *
 213          *  @layr:      Pointer to the current layer the receive function
 214          *              is implemented for (this pointer).
 215          *  @ctrl:      Control Command.
 216          */
 217         void (*ctrlcmd) (struct cflayer *layr, enum caif_ctrlcmd ctrl,
 218                          int phyid);
 219
 220         /*
 221          *  modemctrl() - Control Function used for controlling the modem.
 222          *  Used to signal down-wards in the CAIF stack.
 223          *  Returns 0 on success, < 0 upon failure.
 224          *
 225          *  @layr:      Pointer to the current layer the receive function
 226          *              is implemented for (this pointer).
 227          *  @ctrl:  Control Command.
 228          */
 229         int (*modemcmd) (struct cflayer *layr, enum caif_modemcmd ctrl);
 230
 231         unsigned int id;
 232         char name[CAIF_LAYER_NAME_SZ];
 233 };
 234
 235 /**
 236  * layer_set_up() - Set the up pointer for a specified layer.
 237  *  @layr: Layer where up pointer shall be set.
 238  *  @above: Layer above.
 239  */
 240 #define layer_set_up(layr, above) ((layr)->up = (struct cflayer *)(above))
 241
 242 /**
 243  *  layer_set_dn() - Set the down pointer for a specified layer.
 244  *  @layr:  Layer where down pointer shall be set.
 245  *  @below: Layer below.
 246  */
 247 #define layer_set_dn(layr, below) ((layr)->dn = (struct cflayer *)(below))
 248
 249 /**
 250  * struct dev_info - Physical Device info information about physical layer.
 251  * @dev:        Pointer to native physical device.
 252  * @id:         Physical ID of the physical connection used by the
 253  *              logical CAIF connection. Used by service layers to
 254  *              identify their physical id to Caif MUX (CFMUXL)so
 255  *              that the MUX can add the correct physical ID to the
 256  *              packet.
 257  */
 258 struct dev_info {
 259         void *dev;
 260         unsigned int id;
 261 };
 262
 263 /**
 264  * struct caif_payload_info - Payload information embedded in packet (sk_buff).
 265  *
 266  * @dev_info:   Information about the receiving device.
 267  *
 268  * @hdr_len:    Header length, used to align pay load on 32bit boundary.
 269  *
 270  * @channel_id: Channel ID of the logical CAIF connection.
 271  *              Used by mux to insert channel id into the caif packet.
 272  */
 273 struct caif_payload_info {
 274         struct dev_info *dev_info;
 275         unsigned short hdr_len;
 276         unsigned short channel_id;
 277 };
 278
 279 #endif  /* CAIF_LAYER_H_ */