Documentation/networking/device_drivers/cellular/qualcomm/rmnet.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 ============
   4 Rmnet Driver
   5 ============
   6
   7 1. Introduction
   8 ===============
   9
  10 rmnet driver is used for supporting the Multiplexing and aggregation
  11 Protocol (MAP). This protocol is used by all recent chipsets using Qualcomm
  12 Technologies, Inc. modems.
  13
  14 This driver can be used to register onto any physical network device in
  15 IP mode. Physical transports include USB, HSIC, PCIe and IP accelerator.
  16
  17 Multiplexing allows for creation of logical netdevices (rmnet devices) to
  18 handle multiple private data networks (PDN) like a default internet, tethering,
  19 multimedia messaging service (MMS) or IP media subsystem (IMS). Hardware sends
  20 packets with MAP headers to rmnet. Based on the multiplexer id, rmnet
  21 routes to the appropriate PDN after removing the MAP header.
  22
  23 Aggregation is required to achieve high data rates. This involves hardware
  24 sending aggregated bunch of MAP frames. rmnet driver will de-aggregate
  25 these MAP frames and send them to appropriate PDN's.
  26
  27 2. Packet format
  28 ================
  29
  30 a. MAP packet v1 (data / control)
  31
  32 MAP header fields are in big endian format.
  33
  34 Packet format::
  35
  36   Bit             0             1           2-7      8-15           16-31
  37   Function   Command / Data   Reserved     Pad   Multiplexer ID    Payload length
  38
  39   Bit            32-x
  40   Function      Raw bytes
  41
  42 Command (1)/ Data (0) bit value is to indicate if the packet is a MAP command
  43 or data packet. Command packet is used for transport level flow control. Data
  44 packets are standard IP packets.
  45
  46 Reserved bits must be zero when sent and ignored when received.
  47
  48 Padding is the number of bytes to be appended to the payload to
  49 ensure 4 byte alignment.
  50
  51 Multiplexer ID is to indicate the PDN on which data has to be sent.
  52
  53 Payload length includes the padding length but does not include MAP header
  54 length.
  55
  56 b. Map packet v4 (data / control)
  57
  58 MAP header fields are in big endian format.
  59
  60 Packet format::
  61
  62   Bit             0             1           2-7      8-15           16-31
  63   Function   Command / Data   Reserved     Pad   Multiplexer ID    Payload length
  64
  65   Bit            32-(x-33)      (x-32)-x
  66   Function      Raw bytes      Checksum offload header
  67
  68 Command (1)/ Data (0) bit value is to indicate if the packet is a MAP command
  69 or data packet. Command packet is used for transport level flow control. Data
  70 packets are standard IP packets.
  71
  72 Reserved bits must be zero when sent and ignored when received.
  73
  74 Padding is the number of bytes to be appended to the payload to
  75 ensure 4 byte alignment.
  76
  77 Multiplexer ID is to indicate the PDN on which data has to be sent.
  78
  79 Payload length includes the padding length but does not include MAP header
  80 length.
  81
  82 Checksum offload header, has the information about the checksum processing done
  83 by the hardware.Checksum offload header fields are in big endian format.
  84
  85 Packet format::
  86
  87   Bit             0-14        15              16-31
  88   Function      Reserved   Valid     Checksum start offset
  89
  90   Bit                31-47                    48-64
  91   Function      Checksum length           Checksum value
  92
  93 Reserved bits must be zero when sent and ignored when received.
  94
  95 Valid bit indicates whether the partial checksum is calculated and is valid.
  96 Set to 1, if its is valid. Set to 0 otherwise.
  97
  98 Padding is the number of bytes to be appended to the payload to
  99 ensure 4 byte alignment.
 100
 101 Checksum start offset, Indicates the offset in bytes from the beginning of the
 102 IP header, from which modem computed checksum.
 103
 104 Checksum length is the Length in bytes starting from CKSUM_START_OFFSET,
 105 over which checksum is computed.
 106
 107 Checksum value, indicates the checksum computed.
 108
 109 c. MAP packet v5 (data / control)
 110
 111 MAP header fields are in big endian format.
 112
 113 Packet format::
 114
 115   Bit             0             1         2-7      8-15           16-31
 116   Function   Command / Data  Next header  Pad   Multiplexer ID   Payload length
 117
 118   Bit            32-x
 119   Function      Raw bytes
 120
 121 Command (1)/ Data (0) bit value is to indicate if the packet is a MAP command
 122 or data packet. Command packet is used for transport level flow control. Data
 123 packets are standard IP packets.
 124
 125 Next header is used to indicate the presence of another header, currently is
 126 limited to checksum header.
 127
 128 Padding is the number of bytes to be appended to the payload to
 129 ensure 4 byte alignment.
 130
 131 Multiplexer ID is to indicate the PDN on which data has to be sent.
 132
 133 Payload length includes the padding length but does not include MAP header
 134 length.
 135
 136 d. Checksum offload header v5
 137
 138 Checksum offload header fields are in big endian format.
 139
 140   Bit            0 - 6          7               8-15              16-31
 141   Function     Header Type    Next Header     Checksum Valid    Reserved
 142
 143 Header Type is to indicate the type of header, this usually is set to CHECKSUM
 144
 145 Header types
 146 = ==========================================
 147 0 Reserved
 148 1 Reserved
 149 2 checksum header
 150
 151 Checksum Valid is to indicate whether the header checksum is valid. Value of 1
 152 implies that checksum is calculated on this packet and is valid, value of 0
 153 indicates that the calculated packet checksum is invalid.
 154
 155 Reserved bits must be zero when sent and ignored when received.
 156
 157 e. MAP packet v1/v5 (command specific)::
 158
 159     Bit             0             1         2-7      8 - 15           16 - 31
 160     Function   Command         Reserved     Pad   Multiplexer ID    Payload length
 161     Bit          32 - 39        40 - 45    46 - 47       48 - 63
 162     Function   Command name    Reserved   Command Type   Reserved
 163     Bit          64 - 95
 164     Function   Transaction ID
 165     Bit          96 - 127
 166     Function   Command data
 167
 168 Command 1 indicates disabling flow while 2 is enabling flow
 169
 170 Command types
 171
 172 = ==========================================
 173 0 for MAP command request
 174 1 is to acknowledge the receipt of a command
 175 2 is for unsupported commands
 176 3 is for error during processing of commands
 177 = ==========================================
 178
 179 f. Aggregation
 180
 181 Aggregation is multiple MAP packets (can be data or command) delivered to
 182 rmnet in a single linear skb. rmnet will process the individual
 183 packets and either ACK the MAP command or deliver the IP packet to the
 184 network stack as needed
 185
 186 MAP header|IP Packet|Optional padding|MAP header|IP Packet|Optional padding....
 187
 188 MAP header|IP Packet|Optional padding|MAP header|Command Packet|Optional pad...
 189
 190 3. Userspace configuration
 191 ==========================
 192
 193 rmnet userspace configuration is done through netlink library librmnetctl
 194 and command line utility rmnetcli. Utility is hosted in codeaurora forum git.
 195 The driver uses rtnl_link_ops for communication.
 196
 197 https://source.codeaurora.org/quic/la/platform/vendor/qcom-opensource/dataservices/tree/rmnetctl