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
32MAP header fields are in big endian format.
33
34Packet 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
42Command (1)/ Data (0) bit value is to indicate if the packet is a MAP command
43or data packet. Command packet is used for transport level flow control. Data
44packets are standard IP packets.
45
46Reserved bits must be zero when sent and ignored when received.
47
48Padding is the number of bytes to be appended to the payload to
49ensure 4 byte alignment.
50
51Multiplexer ID is to indicate the PDN on which data has to be sent.
52
53Payload length includes the padding length but does not include MAP header
54length.
55
56b. Map packet v4 (data / control)
57
58MAP header fields are in big endian format.
59
60Packet 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
68Command (1)/ Data (0) bit value is to indicate if the packet is a MAP command
69or data packet. Command packet is used for transport level flow control. Data
70packets are standard IP packets.
71
72Reserved bits must be zero when sent and ignored when received.
73
74Padding is the number of bytes to be appended to the payload to
75ensure 4 byte alignment.
76
77Multiplexer ID is to indicate the PDN on which data has to be sent.
78
79Payload length includes the padding length but does not include MAP header
80length.
81
82Checksum offload header, has the information about the checksum processing done
83by the hardware.Checksum offload header fields are in big endian format.
84
85Packet 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
93Reserved bits must be zero when sent and ignored when received.
94
95Valid bit indicates whether the partial checksum is calculated and is valid.
96Set to 1, if its is valid. Set to 0 otherwise.
97
98Padding is the number of bytes to be appended to the payload to
99ensure 4 byte alignment.
100
101Checksum start offset, Indicates the offset in bytes from the beginning of the
102IP header, from which modem computed checksum.
103
104Checksum length is the Length in bytes starting from CKSUM_START_OFFSET,
105over which checksum is computed.
106
107Checksum value, indicates the checksum computed.
108
109c. MAP packet v5 (data / control)
110
111MAP header fields are in big endian format.
112
113Packet 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
121Command (1)/ Data (0) bit value is to indicate if the packet is a MAP command
122or data packet. Command packet is used for transport level flow control. Data
123packets are standard IP packets.
124
125Next header is used to indicate the presence of another header, currently is
126limited to checksum header.
127
128Padding is the number of bytes to be appended to the payload to
129ensure 4 byte alignment.
130
131Multiplexer ID is to indicate the PDN on which data has to be sent.
132
133Payload length includes the padding length but does not include MAP header
134length.
135
136d. Checksum offload header v5
137
138Checksum 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
143Header Type is to indicate the type of header, this usually is set to CHECKSUM
144
145Header types
146= ==========================================
1470 Reserved
1481 Reserved
1492 checksum header
150
151Checksum Valid is to indicate whether the header checksum is valid. Value of 1
152implies that checksum is calculated on this packet and is valid, value of 0
153indicates that the calculated packet checksum is invalid.
154
155Reserved bits must be zero when sent and ignored when received.
156
157e. 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
168Command 1 indicates disabling flow while 2 is enabling flow
169
170Command types
171
172= ==========================================
1730 for MAP command request
1741 is to acknowledge the receipt of a command
1752 is for unsupported commands
1763 is for error during processing of commands
177= ==========================================
178
179f. Aggregation
180
181Aggregation is multiple MAP packets (can be data or command) delivered to
182rmnet in a single linear skb. rmnet will process the individual
183packets and either ACK the MAP command or deliver the IP packet to the
184network stack as needed
185
186MAP header|IP Packet|Optional padding|MAP header|IP Packet|Optional padding....
187
188MAP header|IP Packet|Optional padding|MAP header|Command Packet|Optional pad...
189
1903. Userspace configuration
191==========================
192
193rmnet userspace configuration is done through netlink library librmnetctl
194and command line utility rmnetcli. Utility is hosted in codeaurora forum git.
195The driver uses rtnl_link_ops for communication.
196
197https://source.codeaurora.org/quic/la/platform/vendor/qcom-opensource/dataservices/tree/rmnetctl
198