rmnet.rst

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