net/caif/caif_layer.h

0001 /* SPDX-License-Identifier: GPL-2.0-only */
0002 /*
0003  * Copyright (C) ST-Ericsson AB 2010
0004  * Author:  Sjur Brendeland
0005  */
0006
0007 #ifndef CAIF_LAYER_H_
0008 #define CAIF_LAYER_H_
0009
0010 #include <linux/list.h>
0011
0012 struct cflayer;
0013 struct cfpkt;
0014 struct cfpktq;
0015 struct caif_payload_info;
0016 struct caif_packet_funcs;
0017
0018 #define CAIF_LAYER_NAME_SZ 16
0019
0020 /**
0021  * caif_assert() - Assert function for CAIF.
0022  * @assert: expression to evaluate.
0023  *
0024  * This function will print a error message and a do WARN_ON if the
0025  * assertion failes. Normally this will do a stack up at the current location.
0026  */
0027 #define caif_assert(assert)                 \
0028 do {                                \
0029     if (!(assert)) {                    \
0030         pr_err("caif:Assert detected:'%s'\n", #assert); \
0031         WARN_ON(!(assert));             \
0032     }                           \
0033 } while (0)
0034
0035 /**
0036  * enum caif_ctrlcmd - CAIF Stack Control Signaling sent in layer.ctrlcmd().
0037  *
0038  * @CAIF_CTRLCMD_FLOW_OFF_IND:      Flow Control is OFF, transmit function
0039  *                  should stop sending data
0040  *
0041  * @CAIF_CTRLCMD_FLOW_ON_IND:       Flow Control is ON, transmit function
0042  *                  can start sending data
0043  *
0044  * @CAIF_CTRLCMD_REMOTE_SHUTDOWN_IND:   Remote end modem has decided to close
0045  *                  down channel
0046  *
0047  * @CAIF_CTRLCMD_INIT_RSP:      Called initially when the layer below
0048  *                  has finished initialization
0049  *
0050  * @CAIF_CTRLCMD_DEINIT_RSP:        Called when de-initialization is
0051  *                  complete
0052  *
0053  * @CAIF_CTRLCMD_INIT_FAIL_RSP:     Called if initialization fails
0054  *
0055  * @_CAIF_CTRLCMD_PHYIF_FLOW_OFF_IND:   CAIF Link layer temporarily cannot
0056  *                  send more packets.
0057  * @_CAIF_CTRLCMD_PHYIF_FLOW_ON_IND:    Called if CAIF Link layer is able
0058  *                  to send packets again.
0059  * @_CAIF_CTRLCMD_PHYIF_DOWN_IND:   Called if CAIF Link layer is going
0060  *                  down.
0061  *
0062  * These commands are sent upwards in the CAIF stack to the CAIF Client.
0063  * They are used for signaling originating from the modem or CAIF Link Layer.
0064  * These are either responses (*_RSP) or events (*_IND).
0065  */
0066 enum caif_ctrlcmd {
0067     CAIF_CTRLCMD_FLOW_OFF_IND,
0068     CAIF_CTRLCMD_FLOW_ON_IND,
0069     CAIF_CTRLCMD_REMOTE_SHUTDOWN_IND,
0070     CAIF_CTRLCMD_INIT_RSP,
0071     CAIF_CTRLCMD_DEINIT_RSP,
0072     CAIF_CTRLCMD_INIT_FAIL_RSP,
0073     _CAIF_CTRLCMD_PHYIF_FLOW_OFF_IND,
0074     _CAIF_CTRLCMD_PHYIF_FLOW_ON_IND,
0075     _CAIF_CTRLCMD_PHYIF_DOWN_IND,
0076 };
0077
0078 /**
0079  * enum caif_modemcmd -  Modem Control Signaling, sent from CAIF Client
0080  *           to the CAIF Link Layer or modem.
0081  *
0082  * @CAIF_MODEMCMD_FLOW_ON_REQ:      Flow Control is ON, transmit function
0083  *                  can start sending data.
0084  *
0085  * @CAIF_MODEMCMD_FLOW_OFF_REQ:     Flow Control is OFF, transmit function
0086  *                  should stop sending data.
0087  *
0088  * @_CAIF_MODEMCMD_PHYIF_USEFULL:   Notify physical layer that it is in use
0089  *
0090  * @_CAIF_MODEMCMD_PHYIF_USELESS:   Notify physical layer that it is
0091  *                  no longer in use.
0092  *
0093  * These are requests sent 'downwards' in the stack.
0094  * Flow ON, OFF can be indicated to the modem.
0095  */
0096 enum caif_modemcmd {
0097     CAIF_MODEMCMD_FLOW_ON_REQ = 0,
0098     CAIF_MODEMCMD_FLOW_OFF_REQ = 1,
0099     _CAIF_MODEMCMD_PHYIF_USEFULL = 3,
0100     _CAIF_MODEMCMD_PHYIF_USELESS = 4
0101 };
0102
0103 /**
0104  * enum caif_direction - CAIF Packet Direction.
0105  * Indicate if a packet is to be sent out or to be received in.
0106  * @CAIF_DIR_IN:        Incoming packet received.
0107  * @CAIF_DIR_OUT:       Outgoing packet to be transmitted.
0108  */
0109 enum caif_direction {
0110     CAIF_DIR_IN = 0,
0111     CAIF_DIR_OUT = 1
0112 };
0113
0114 /**
0115  * struct cflayer - CAIF Stack layer.
0116  * Defines the framework for the CAIF Core Stack.
0117  * @up:     Pointer up to the layer above.
0118  * @dn:     Pointer down to the layer below.
0119  * @node:   List node used when layer participate in a list.
0120  * @receive:    Packet receive function.
0121  * @transmit:   Packet transmit funciton.
0122  * @ctrlcmd:    Used for control signalling upwards in the stack.
0123  * @modemcmd:   Used for control signaling downwards in the stack.
0124  * @id:     The identity of this layer
0125  * @name:   Name of the layer.
0126  *
0127  *  This structure defines the layered structure in CAIF.
0128  *
0129  *  It defines CAIF layering structure, used by all CAIF Layers and the
0130  *  layers interfacing CAIF.
0131  *
0132  *  In order to integrate with CAIF an adaptation layer on top of the CAIF stack
0133  *  and PHY layer below the CAIF stack
0134  *  must be implemented. These layer must follow the design principles below.
0135  *
0136  *  Principles for layering of protocol layers:
0137  *    - All layers must use this structure. If embedding it, then place this
0138  *  structure first in the layer specific structure.
0139  *
0140  *    - Each layer should not depend on any others layer's private data.
0141  *
0142  *    - In order to send data upwards do
0143  *  layer->up->receive(layer->up, packet);
0144  *
0145  *    - In order to send data downwards do
0146  *  layer->dn->transmit(layer->dn, info, packet);
0147  */
0148 struct cflayer {
0149     struct cflayer *up;
0150     struct cflayer *dn;
0151     struct list_head node;
0152
0153     /*
0154      *  receive() - Receive Function (non-blocking).
0155      *  Contract: Each layer must implement a receive function passing the
0156      *  CAIF packets upwards in the stack.
0157      *  Packet handling rules:
0158      *        - The CAIF packet (cfpkt) ownership is passed to the
0159      *      called receive function. This means that the
0160      *      packet cannot be accessed after passing it to the
0161      *      above layer using up->receive().
0162      *
0163      *        - If parsing of the packet fails, the packet must be
0164      *      destroyed and negative error code returned
0165      *      from the function.
0166      *      EXCEPTION: If the framing layer (cffrml) returns
0167      *          -EILSEQ, the packet is not freed.
0168      *
0169      *        - If parsing succeeds (and above layers return OK) then
0170      *            the function must return a value >= 0.
0171      *
0172      *  Returns result < 0 indicates an error, 0 or positive value
0173      *       indicates success.
0174      *
0175      *  @layr: Pointer to the current layer the receive function is
0176      *      implemented for (this pointer).
0177      *  @cfpkt: Pointer to CaifPacket to be handled.
0178      */
0179     int (*receive)(struct cflayer *layr, struct cfpkt *cfpkt);
0180
0181     /*
0182      *  transmit() - Transmit Function (non-blocking).
0183      *  Contract: Each layer must implement a transmit function passing the
0184      *  CAIF packet downwards in the stack.
0185      *  Packet handling rules:
0186      *        - The CAIF packet (cfpkt) ownership is passed to the
0187      *      transmit function. This means that the packet
0188      *      cannot be accessed after passing it to the below
0189      *      layer using dn->transmit().
0190      *
0191      *        - Upon error the packet ownership is still passed on,
0192      *      so the packet shall be freed where error is detected.
0193      *      Callers of the transmit function shall not free packets,
0194      *      but errors shall be returned.
0195      *
0196      *        - Return value less than zero means error, zero or
0197      *      greater than zero means OK.
0198      *
0199      *  Returns result < 0 indicates an error, 0 or positive value
0200      *      indicates success.
0201      *
0202      *  @layr:  Pointer to the current layer the receive function
0203      *      isimplemented for (this pointer).
0204      *  @cfpkt:  Pointer to CaifPacket to be handled.
0205      */
0206     int (*transmit) (struct cflayer *layr, struct cfpkt *cfpkt);
0207
0208     /*
0209      *  cttrlcmd() - Control Function upwards in CAIF Stack  (non-blocking).
0210      *  Used for signaling responses (CAIF_CTRLCMD_*_RSP)
0211      *  and asynchronous events from the modem  (CAIF_CTRLCMD_*_IND)
0212      *
0213      *  @layr:  Pointer to the current layer the receive function
0214      *      is implemented for (this pointer).
0215      *  @ctrl:  Control Command.
0216      */
0217     void (*ctrlcmd) (struct cflayer *layr, enum caif_ctrlcmd ctrl,
0218              int phyid);
0219
0220     /*
0221      *  modemctrl() - Control Function used for controlling the modem.
0222      *  Used to signal down-wards in the CAIF stack.
0223      *  Returns 0 on success, < 0 upon failure.
0224      *
0225      *  @layr:  Pointer to the current layer the receive function
0226      *      is implemented for (this pointer).
0227      *  @ctrl:  Control Command.
0228      */
0229     int (*modemcmd) (struct cflayer *layr, enum caif_modemcmd ctrl);
0230
0231     unsigned int id;
0232     char name[CAIF_LAYER_NAME_SZ];
0233 };
0234
0235 /**
0236  * layer_set_up() - Set the up pointer for a specified layer.
0237  *  @layr: Layer where up pointer shall be set.
0238  *  @above: Layer above.
0239  */
0240 #define layer_set_up(layr, above) ((layr)->up = (struct cflayer *)(above))
0241
0242 /**
0243  *  layer_set_dn() - Set the down pointer for a specified layer.
0244  *  @layr:  Layer where down pointer shall be set.
0245  *  @below: Layer below.
0246  */
0247 #define layer_set_dn(layr, below) ((layr)->dn = (struct cflayer *)(below))
0248
0249 /**
0250  * struct dev_info - Physical Device info information about physical layer.
0251  * @dev:    Pointer to native physical device.
0252  * @id:     Physical ID of the physical connection used by the
0253  *      logical CAIF connection. Used by service layers to
0254  *      identify their physical id to Caif MUX (CFMUXL)so
0255  *      that the MUX can add the correct physical ID to the
0256  *      packet.
0257  */
0258 struct dev_info {
0259     void *dev;
0260     unsigned int id;
0261 };
0262
0263 /**
0264  * struct caif_payload_info - Payload information embedded in packet (sk_buff).
0265  *
0266  * @dev_info:   Information about the receiving device.
0267  *
0268  * @hdr_len:    Header length, used to align pay load on 32bit boundary.
0269  *
0270  * @channel_id: Channel ID of the logical CAIF connection.
0271  *      Used by mux to insert channel id into the caif packet.
0272  */
0273 struct caif_payload_info {
0274     struct dev_info *dev_info;
0275     unsigned short hdr_len;
0276     unsigned short channel_id;
0277 };
0278
0279 #endif  /* CAIF_LAYER_H_ */