include/net/caif/caif_layer.h

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