← Documents Documentation/networking/cdc_mbim.rst GitHub 원문 ↗

Linux 6.18.37 · Networking

cdc_mbim - CDC MBIM Mobile Broadband 모뎀 드라이버

CDC MBIM 모뎀의 control·data ABI, IP/DSS session의 VLAN mapping, session 0 처리와 user space 책임을 설명합니다.

Source pathDocumentation/networking/cdc_mbim.rst
Source versionLinux v6.18.37
TranslationDUJINLABS 전문 번역 + 해설

요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.

1. 요약·해설

원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.

요약·해설

cdc_mbim.rst:1-355

`cdc_mbim`은 MBIM USB 모뎀의 kernel data path와 user space ABI만 제공합니다. 연결 설정과 control message의 생성·분할·협상은 `libmbim` 또는 `ModemManager` 같은 관리 application이 맡습니다. 하나의 `wwanY` data channel에서 IPS와 DSS를 함께 운반하기 위해 VLAN ID를 session selector로 사용하는 점이 이 문서의 핵심입니다.

NCM/MBIM driver 선택
NCM/MBIM USB function`prefer_mbim=Y``cdc_mbim`
NCM/MBIM USB function`prefer_mbim=N``cdc_ncm`
Runtime 값 변경수동 unbind다시 bind새 정책 적용

`prefer_mbim`이 하위 호환 function을 어느 드라이버가 맡을지 결정합니다.

MBIM IP session 수립
`/dev/cdc-wdmX` 열기Network connection 설정Mobile network 연결IP interface 구성`wwanY` traffic

드라이버가 자동으로 수행하지 않는 user space 관리 순서입니다.

Control channel 책임 경계
MBIM management applicationFragment·defragment`/dev/cdc-wdmX``cdc-wdm` subdriverMBIM control interface
USB descriptor`wMaxControlMessage`크기 협상`read()`·`write()` 한도

`cdc-wdm` pipe는 message를 그대로 전달하며 protocol 처리는 user space에 남습니다.

Control message 크기 책임
항목제공자책임
`wMaxControlMessage`USB functional descriptorDevice 최대값 제시
`IOCTL_WDM_MAX_COMMAND``cdc-wdm` ABIDescriptor 값을 편리하게 반환
협상 크기관리 application + MBIM device[1] 9.3.1 준수
`write()`관리 application협상 크기 초과 금지
`read()`관리 application협상 크기까지 수용

Descriptor, ioctl, read와 write가 공유하는 상한을 정리합니다.

IPS VLAN mapping
MBIM sessionVLAN ID예시 interface생성 주체
0untagged 또는 4094`wwan0` 또는 `wwan0.0`User space
11`wwan0.1`User space
33`wwan0.3`User space
255255`wwan0.255`User space

IP session 1-255는 같은 번호의 VLAN subdevice로 나타납니다.

DSS frame 경로
Service applicationTX dummy Ethernet header 추가DSS VLAN 256+A`wwanY`USB MBIM data channel
USB MBIM data channel`ETH_P_802_3` RX frameDSS VLAN 256+ARX dummy header 제거Service stream

DSS payload를 network ABI로 운반할 때 dummy Ethernet header를 처리하는 경로입니다.

DSS Ethernet header 규칙
방향Field·조건동작
TXEthertype `0x0800` 또는 `0x86dd`Drop
TX그 밖의 header 내용임의 값 허용
RXProtocol`ETH_P_802_3`으로 설정
RXDestinationMaster device hardware address
User spaceHeaderTX 추가, RX 제거

Dummy header라도 protocol과 destination에는 명시적인 제약이 있습니다.

DSS packet socket filter
`SKF_AD_VLAN_TAG_PRESENT`Tag 존재 확인`SKF_AD_VLAN_TAG`256 <= VLAN < 512`ETH_P_802_3`Accept
조건 불일치Ignore

Master device에 직접 bind할 때 unrelated IPS traffic을 제외합니다.

전체 VLAN ID 공간
VLAN ID용도Session 계산상태
untaggedIPS04094 link가 없을 때만
1-255IPS`SessionID = VLANID`지원
256-511DSS`SessionID = VLANID - 256`지원
512-4093없음-항상 drop
4094IPS0Link가 있을 때만

IPS, DSS, session 0의 magic VLAN과 drop 범위를 한 표로 통합했습니다.

Session 0을 VLAN 4094로 전환
초기: session 0 = untagged `wwanY``vlan id 4094` link 추가session 0 = VLAN 4094Master untagged frame drop
효과각 subdevice가 자체 MTU·up 상태 사용IPS·DSS의 session 0 종속 완화

Magic VLAN을 만들면 master의 untagged 경로가 즉시 대체됩니다.

2. 영어 원문 전체

번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.

원문 전체 펼치기
1 .. SPDX-License-Identifier: GPL-2.0
2
3 ======================================================
4 cdc_mbim - Driver for CDC MBIM Mobile Broadband modems
5 ======================================================
6
7 The cdc_mbim driver supports USB devices conforming to the "Universal
8 Serial Bus Communications Class Subclass Specification for Mobile
9 Broadband Interface Model" [1], which is a further development of
10 "Universal Serial Bus Communications Class Subclass Specifications for
11 Network Control Model Devices" [2] optimized for Mobile Broadband
12 devices, aka "3G/LTE modems".
13
14
15 Command Line Parameters
16 =======================
17
18 The cdc_mbim driver has no parameters of its own. But the probing
19 behaviour for NCM 1.0 backwards compatible MBIM functions (an
20 "NCM/MBIM function" as defined in section 3.2 of [1]) is affected
21 by a cdc_ncm driver parameter:
22
23 prefer_mbim
24 -----------
25 :Type: Boolean
26 :Valid Range: N/Y (0-1)
27 :Default Value: Y (MBIM is preferred)
28
29 This parameter sets the system policy for NCM/MBIM functions. Such
30 functions will be handled by either the cdc_ncm driver or the cdc_mbim
31 driver depending on the prefer_mbim setting. Setting prefer_mbim=N
32 makes the cdc_mbim driver ignore these functions and lets the cdc_ncm
33 driver handle them instead.
34
35 The parameter is writable, and can be changed at any time. A manual
36 unbind/bind is required to make the change effective for NCM/MBIM
37 functions bound to the "wrong" driver
38
39
40 Basic usage
41 ===========
42
43 MBIM functions are inactive when unmanaged. The cdc_mbim driver only
44 provides a userspace interface to the MBIM control channel, and will
45 not participate in the management of the function. This implies that a
46 userspace MBIM management application always is required to enable a
47 MBIM function.
48
49 Such userspace applications includes, but are not limited to:
50
51 - mbimcli (included with the libmbim [3] library), and
52 - ModemManager [4]
53
54 Establishing a MBIM IP session requires at least these actions by the
55 management application:
56
57 - open the control channel
58 - configure network connection settings
59 - connect to network
60 - configure IP interface
61
62 Management application development
63 ----------------------------------
64 The driver <-> userspace interfaces are described below. The MBIM
65 control channel protocol is described in [1].
66
67
68 MBIM control channel userspace ABI
69 ==================================
70
71 /dev/cdc-wdmX character device
72 ------------------------------
73 The driver creates a two-way pipe to the MBIM function control channel
74 using the cdc-wdm driver as a subdriver. The userspace end of the
75 control channel pipe is a /dev/cdc-wdmX character device.
76
77 The cdc_mbim driver does not process or police messages on the control
78 channel. The channel is fully delegated to the userspace management
79 application. It is therefore up to this application to ensure that it
80 complies with all the control channel requirements in [1].
81
82 The cdc-wdmX device is created as a child of the MBIM control
83 interface USB device. The character device associated with a specific
84 MBIM function can be looked up using sysfs. For example::
85
86 bjorn@nemi:~$ ls /sys/bus/usb/drivers/cdc_mbim/2-4:2.12/usbmisc
87 cdc-wdm0
88
89 bjorn@nemi:~$ grep . /sys/bus/usb/drivers/cdc_mbim/2-4:2.12/usbmisc/cdc-wdm0/dev
90 180:0
91
92
93 USB configuration descriptors
94 -----------------------------
95 The wMaxControlMessage field of the CDC MBIM functional descriptor
96 limits the maximum control message size. The management application is
97 responsible for negotiating a control message size complying with the
98 requirements in section 9.3.1 of [1], taking this descriptor field
99 into consideration.
100
101 The userspace application can access the CDC MBIM functional
102 descriptor of a MBIM function using either of the two USB
103 configuration descriptor kernel interfaces described in [6] or [7].
104
105 See also the ioctl documentation below.
106
107
108 Fragmentation
109 -------------
110 The userspace application is responsible for all control message
111 fragmentation and defragmentaion, as described in section 9.5 of [1].
112
113
114 /dev/cdc-wdmX write()
115 ---------------------
116 The MBIM control messages from the management application *must not*
117 exceed the negotiated control message size.
118
119
120 /dev/cdc-wdmX read()
121 --------------------
122 The management application *must* accept control messages of up the
123 negotiated control message size.
124
125
126 /dev/cdc-wdmX ioctl()
127 ---------------------
128 IOCTL_WDM_MAX_COMMAND: Get Maximum Command Size
129 This ioctl returns the wMaxControlMessage field of the CDC MBIM
130 functional descriptor for MBIM devices. This is intended as a
131 convenience, eliminating the need to parse the USB descriptors from
132 userspace.
133
134 ::
135
136 #include <stdio.h>
137 #include <fcntl.h>
138 #include <sys/ioctl.h>
139 #include <linux/types.h>
140 #include <linux/usb/cdc-wdm.h>
141 int main()
142 {
143 __u16 max;
144 int fd = open("/dev/cdc-wdm0", O_RDWR);
145 if (!ioctl(fd, IOCTL_WDM_MAX_COMMAND, &max))
146 printf("wMaxControlMessage is %d\n", max);
147 }
148
149
150 Custom device services
151 ----------------------
152 The MBIM specification allows vendors to freely define additional
153 services. This is fully supported by the cdc_mbim driver.
154
155 Support for new MBIM services, including vendor specified services, is
156 implemented entirely in userspace, like the rest of the MBIM control
157 protocol
158
159 New services should be registered in the MBIM Registry [5].
160
161
162
163 MBIM data channel userspace ABI
164 ===============================
165
166 wwanY network device
167 --------------------
168 The cdc_mbim driver represents the MBIM data channel as a single
169 network device of the "wwan" type. This network device is initially
170 mapped to MBIM IP session 0.
171
172
173 Multiplexed IP sessions (IPS)
174 -----------------------------
175 MBIM allows multiplexing up to 256 IP sessions over a single USB data
176 channel. The cdc_mbim driver models such IP sessions as 802.1q VLAN
177 subdevices of the master wwanY device, mapping MBIM IP session Z to
178 VLAN ID Z for all values of Z greater than 0.
179
180 The device maximum Z is given in the MBIM_DEVICE_CAPS_INFO structure
181 described in section 10.5.1 of [1].
182
183 The userspace management application is responsible for adding new
184 VLAN links prior to establishing MBIM IP sessions where the SessionId
185 is greater than 0. These links can be added by using the normal VLAN
186 kernel interfaces, either ioctl or netlink.
187
188 For example, adding a link for a MBIM IP session with SessionId 3::
189
190 ip link add link wwan0 name wwan0.3 type vlan id 3
191
192 The driver will automatically map the "wwan0.3" network device to MBIM
193 IP session 3.
194
195
196 Device Service Streams (DSS)
197 ----------------------------
198 MBIM also allows up to 256 non-IP data streams to be multiplexed over
199 the same shared USB data channel. The cdc_mbim driver models these
200 sessions as another set of 802.1q VLAN subdevices of the master wwanY
201 device, mapping MBIM DSS session A to VLAN ID (256 + A) for all values
202 of A.
203
204 The device maximum A is given in the MBIM_DEVICE_SERVICES_INFO
205 structure described in section 10.5.29 of [1].
206
207 The DSS VLAN subdevices are used as a practical interface between the
208 shared MBIM data channel and a MBIM DSS aware userspace application.
209 It is not intended to be presented as-is to an end user. The
210 assumption is that a userspace application initiating a DSS session
211 also takes care of the necessary framing of the DSS data, presenting
212 the stream to the end user in an appropriate way for the stream type.
213
214 The network device ABI requires a dummy ethernet header for every DSS
215 data frame being transported. The contents of this header is
216 arbitrary, with the following exceptions:
217
218 - TX frames using an IP protocol (0x0800 or 0x86dd) will be dropped
219 - RX frames will have the protocol field set to ETH_P_802_3 (but will
220 not be properly formatted 802.3 frames)
221 - RX frames will have the destination address set to the hardware
222 address of the master device
223
224 The DSS supporting userspace management application is responsible for
225 adding the dummy ethernet header on TX and stripping it on RX.
226
227 This is a simple example using tools commonly available, exporting
228 DssSessionId 5 as a pty character device pointed to by a /dev/nmea
229 symlink::
230
231 ip link add link wwan0 name wwan0.dss5 type vlan id 261
232 ip link set dev wwan0.dss5 up
233 socat INTERFACE:wwan0.dss5,type=2 PTY:,echo=0,link=/dev/nmea
234
235 This is only an example, most suitable for testing out a DSS
236 service. Userspace applications supporting specific MBIM DSS services
237 are expected to use the tools and programming interfaces required by
238 that service.
239
240 Note that adding VLAN links for DSS sessions is entirely optional. A
241 management application may instead choose to bind a packet socket
242 directly to the master network device, using the received VLAN tags to
243 map frames to the correct DSS session and adding 18 byte VLAN ethernet
244 headers with the appropriate tag on TX. In this case using a socket
245 filter is recommended, matching only the DSS VLAN subset. This avoid
246 unnecessary copying of unrelated IP session data to userspace. For
247 example::
248
249 static struct sock_filter dssfilter[] = {
250 /* use special negative offsets to get VLAN tag */
251 BPF_STMT(BPF_LD|BPF_B|BPF_ABS, SKF_AD_OFF + SKF_AD_VLAN_TAG_PRESENT),
252 BPF_JUMP(BPF_JMP|BPF_JEQ|BPF_K, 1, 0, 6), /* true */
253
254 /* verify DSS VLAN range */
255 BPF_STMT(BPF_LD|BPF_H|BPF_ABS, SKF_AD_OFF + SKF_AD_VLAN_TAG),
256 BPF_JUMP(BPF_JMP|BPF_JGE|BPF_K, 256, 0, 4), /* 256 is first DSS VLAN */
257 BPF_JUMP(BPF_JMP|BPF_JGE|BPF_K, 512, 3, 0), /* 511 is last DSS VLAN */
258
259 /* verify ethertype */
260 BPF_STMT(BPF_LD|BPF_H|BPF_ABS, 2 * ETH_ALEN),
261 BPF_JUMP(BPF_JMP|BPF_JEQ|BPF_K, ETH_P_802_3, 0, 1),
262
263 BPF_STMT(BPF_RET|BPF_K, (u_int)-1), /* accept */
264 BPF_STMT(BPF_RET|BPF_K, 0), /* ignore */
265 };
266
267
268
269 Tagged IP session 0 VLAN
270 ------------------------
271 As described above, MBIM IP session 0 is treated as special by the
272 driver. It is initially mapped to untagged frames on the wwanY
273 network device.
274
275 This mapping implies a few restrictions on multiplexed IPS and DSS
276 sessions, which may not always be practical:
277
278 - no IPS or DSS session can use a frame size greater than the MTU on
279 IP session 0
280 - no IPS or DSS session can be in the up state unless the network
281 device representing IP session 0 also is up
282
283 These problems can be avoided by optionally making the driver map IP
284 session 0 to a VLAN subdevice, similar to all other IP sessions. This
285 behaviour is triggered by adding a VLAN link for the magic VLAN ID
286 4094. The driver will then immediately start mapping MBIM IP session
287 0 to this VLAN, and will drop untagged frames on the master wwanY
288 device.
289
290 Tip: It might be less confusing to the end user to name this VLAN
291 subdevice after the MBIM SessionID instead of the VLAN ID. For
292 example::
293
294 ip link add link wwan0 name wwan0.0 type vlan id 4094
295
296
297 VLAN mapping
298 ------------
299
300 Summarizing the cdc_mbim driver mapping described above, we have this
301 relationship between VLAN tags on the wwanY network device and MBIM
302 sessions on the shared USB data channel::
303
304 VLAN ID MBIM type MBIM SessionID Notes
305 ---------------------------------------------------------
306 untagged IPS 0 a)
307 1 - 255 IPS 1 - 255 <VLANID>
308 256 - 511 DSS 0 - 255 <VLANID - 256>
309 512 - 4093 b)
310 4094 IPS 0 c)
311
312 a) if no VLAN ID 4094 link exists, else dropped
313 b) unsupported VLAN range, unconditionally dropped
314 c) if a VLAN ID 4094 link exists, else dropped
315
316
317
318
319 References
320 ==========
321
322 1) USB Implementers Forum, Inc. - "Universal Serial Bus
323 Communications Class Subclass Specification for Mobile Broadband
324 Interface Model", Revision 1.0 (Errata 1), May 1, 2013
325
326 - http://www.usb.org/developers/docs/devclass_docs/
327
328 2) USB Implementers Forum, Inc. - "Universal Serial Bus
329 Communications Class Subclass Specifications for Network Control
330 Model Devices", Revision 1.0 (Errata 1), November 24, 2010
331
332 - http://www.usb.org/developers/docs/devclass_docs/
333
334 3) libmbim - "a glib-based library for talking to WWAN modems and
335 devices which speak the Mobile Interface Broadband Model (MBIM)
336 protocol"
337
338 - http://www.freedesktop.org/wiki/Software/libmbim/
339
340 4) ModemManager - "a DBus-activated daemon which controls mobile
341 broadband (2G/3G/4G) devices and connections"
342
343 - http://www.freedesktop.org/wiki/Software/ModemManager/
344
345 5) "MBIM (Mobile Broadband Interface Model) Registry"
346
347 - http://compliance.usb.org/mbim/
348
349 6) "/sys/kernel/debug/usb/devices output format"
350
351 - Documentation/driver-api/usb/usb.rst
352
353 7) "/sys/bus/usb/devices/.../descriptors"
354
355 - Documentation/ABI/stable/sysfs-bus-usb
356

3. 한국어 전문 번역

영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.

드라이버 개요, prefer_mbim 정책과 기본 사용법

1-67

cdc_mbim - CDC MBIM 모바일 광대역 모뎀용 드라이버

`cdc_mbim` 드라이버는 "Universal Serial Bus Communications Class Subclass Specification for Mobile Broadband Interface Model"(MBIM) [1]을 따르는 USB 장치를 지원합니다. MBIM은 "Universal Serial Bus Communications Class Subclass Specifications for Network Control Model Devices"(NCM) [2]를 모바일 광대역 장치, 즉 3G/LTE 모뎀에 맞게 발전시킨 규격입니다.

명령행 매개변수

`cdc_mbim` 드라이버 자체에는 매개변수가 없습니다. 그러나 NCM 1.0과 하위 호환되는 MBIM function, 즉 [1]의 3.2절에서 정의한 "NCM/MBIM function"의 probe 동작은 `cdc_ncm` 드라이버의 `prefer_mbim` 매개변수에 영향을 받습니다.

prefer_mbim

:Type:          Boolean
:Valid Range:   N/Y (0-1)
:Default Value: Y (MBIM is preferred)

이 매개변수는 NCM/MBIM function에 적용할 시스템 정책을 정합니다. 해당 function은 `prefer_mbim` 설정에 따라 `cdc_ncm` 또는 `cdc_mbim` 드라이버가 처리합니다. `prefer_mbim=N`으로 설정하면 `cdc_mbim`은 이 function을 무시하고 대신 `cdc_ncm`이 처리하게 합니다.

이 매개변수는 쓰기 가능하므로 언제든 바꿀 수 있습니다. 다만 이미 "잘못된" 드라이버에 연결된 NCM/MBIM function에 새 설정을 적용하려면 수동으로 unbind한 뒤 다시 bind해야 합니다.

기본 사용법

관리되지 않는 MBIM function은 비활성 상태입니다. `cdc_mbim` 드라이버는 MBIM control channel의 user space interface만 제공하며 function 관리에는 관여하지 않습니다. 따라서 MBIM function을 활성화하려면 언제나 user space MBIM 관리 application이 필요합니다.

이러한 user space application에는 다음 도구가 포함되지만 이에 한정되지는 않습니다.

  • `libmbim` [3] library에 포함된 `mbimcli`
  • `ModemManager` [4]

MBIM IP session을 수립하려면 관리 application이 적어도 다음 작업을 수행해야 합니다.

  • Control channel을 엽니다.
  • Network connection 설정을 구성합니다.
  • Network에 연결합니다.
  • IP interface를 구성합니다.

관리 application 개발

드라이버와 user space 사이의 interface는 아래에서 설명합니다. MBIM control channel protocol은 [1]에 설명되어 있습니다.

.. SPDX-License-Identifier: GPL-2.0

======================================================
cdc_mbim - Driver for CDC MBIM Mobile Broadband modems
======================================================

The cdc_mbim driver supports USB devices conforming to the "Universal
Serial Bus Communications Class Subclass Specification for Mobile
Broadband Interface Model" [1], which is a further development of
"Universal Serial Bus Communications Class Subclass Specifications for
Network Control Model Devices" [2] optimized for Mobile Broadband
devices, aka "3G/LTE modems".


Command Line Parameters
=======================

The cdc_mbim driver has no parameters of its own.  But the probing
behaviour for NCM 1.0 backwards compatible MBIM functions (an
"NCM/MBIM function" as defined in section 3.2 of [1]) is affected
by a cdc_ncm driver parameter:

prefer_mbim
-----------
:Type:          Boolean
:Valid Range:   N/Y (0-1)
:Default Value: Y (MBIM is preferred)

This parameter sets the system policy for NCM/MBIM functions.  Such
functions will be handled by either the cdc_ncm driver or the cdc_mbim
driver depending on the prefer_mbim setting.  Setting prefer_mbim=N
makes the cdc_mbim driver ignore these functions and lets the cdc_ncm
driver handle them instead.

The parameter is writable, and can be changed at any time. A manual
unbind/bind is required to make the change effective for NCM/MBIM
functions bound to the "wrong" driver


Basic usage
===========

MBIM functions are inactive when unmanaged. The cdc_mbim driver only
provides a userspace interface to the MBIM control channel, and will
not participate in the management of the function. This implies that a
userspace MBIM management application always is required to enable a
MBIM function.

Such userspace applications includes, but are not limited to:

 - mbimcli (included with the libmbim [3] library), and
 - ModemManager [4]

Establishing a MBIM IP session requires at least these actions by the
management application:

 - open the control channel
 - configure network connection settings
 - connect to network
 - configure IP interface

Management application development
----------------------------------
The driver <-> userspace interfaces are described below.  The MBIM
control channel protocol is described in [1].

MBIM control channel user space ABI

68-162

MBIM control channel user space ABI

`/dev/cdc-wdmX` character device

드라이버는 `cdc-wdm` 드라이버를 subdriver로 사용해 MBIM function의 control channel로 이어지는 양방향 pipe를 만듭니다. 이 control channel pipe에서 user space 쪽 끝은 `/dev/cdc-wdmX` character device입니다.

`cdc_mbim` 드라이버는 control channel의 message를 처리하거나 규제하지 않습니다. 이 channel은 전적으로 user space 관리 application에 위임됩니다. 따라서 [1]에 명시된 모든 control channel 요구 사항을 준수할 책임은 해당 application에 있습니다.

`cdc-wdmX` device는 MBIM control interface USB device의 child로 생성됩니다. 특정 MBIM function에 연결된 character device는 sysfs에서 찾을 수 있습니다. 예를 들면 다음과 같습니다.

bjorn@nemi:~$ ls /sys/bus/usb/drivers/cdc_mbim/2-4:2.12/usbmisc
cdc-wdm0

bjorn@nemi:~$ grep . /sys/bus/usb/drivers/cdc_mbim/2-4:2.12/usbmisc/cdc-wdm0/dev
180:0

USB configuration descriptor

CDC MBIM functional descriptor의 `wMaxControlMessage` field는 control message의 최대 크기를 제한합니다. 관리 application은 이 descriptor field를 고려해 [1]의 9.3.1절 요구 사항을 만족하는 control message 크기를 협상해야 합니다.

User space application은 [6] 또는 [7]에 설명된 두 USB configuration descriptor kernel interface 중 하나를 사용해 MBIM function의 CDC MBIM functional descriptor에 접근할 수 있습니다.

아래의 ioctl 설명도 함께 참고하십시오.

Fragmentation

[1]의 9.5절에서 설명하는 모든 control message fragmentation과 defragmentation은 user space application이 담당합니다.

`/dev/cdc-wdmX write()`

관리 application이 보내는 MBIM control message는 협상된 control message 크기를 절대로 초과해서는 안 됩니다.

`/dev/cdc-wdmX read()`

관리 application은 협상된 control message 크기까지의 message를 반드시 받아들일 수 있어야 합니다.

`/dev/cdc-wdmX ioctl()`

`IOCTL_WDM_MAX_COMMAND`: 최대 command 크기 얻기

이 ioctl은 MBIM device에 대해 CDC MBIM functional descriptor의 `wMaxControlMessage` field를 반환합니다. User space가 USB descriptor를 직접 parse하지 않아도 되게 하는 편의 기능입니다.

#include <stdio.h>
#include <fcntl.h>
#include <sys/ioctl.h>
#include <linux/types.h>
#include <linux/usb/cdc-wdm.h>
int main()
{
        __u16 max;
        int fd = open("/dev/cdc-wdm0", O_RDWR);
        if (!ioctl(fd, IOCTL_WDM_MAX_COMMAND, &max))
                printf("wMaxControlMessage is %d\n", max);
}

사용자 정의 device service

MBIM specification은 vendor가 추가 service를 자유롭게 정의할 수 있도록 허용합니다. `cdc_mbim` 드라이버는 이를 완전히 지원합니다.

Vendor 지정 service를 포함한 새 MBIM service 지원은 나머지 MBIM control protocol과 마찬가지로 전적으로 user space에서 구현합니다.

새 service는 MBIM Registry [5]에 등록해야 합니다.

MBIM control channel userspace ABI
==================================

/dev/cdc-wdmX character device
------------------------------
The driver creates a two-way pipe to the MBIM function control channel
using the cdc-wdm driver as a subdriver.  The userspace end of the
control channel pipe is a /dev/cdc-wdmX character device.

The cdc_mbim driver does not process or police messages on the control
channel.  The channel is fully delegated to the userspace management
application.  It is therefore up to this application to ensure that it
complies with all the control channel requirements in [1].

The cdc-wdmX device is created as a child of the MBIM control
interface USB device.  The character device associated with a specific
MBIM function can be looked up using sysfs.  For example::

 bjorn@nemi:~$ ls /sys/bus/usb/drivers/cdc_mbim/2-4:2.12/usbmisc
 cdc-wdm0

 bjorn@nemi:~$ grep . /sys/bus/usb/drivers/cdc_mbim/2-4:2.12/usbmisc/cdc-wdm0/dev
 180:0


USB configuration descriptors
-----------------------------
The wMaxControlMessage field of the CDC MBIM functional descriptor
limits the maximum control message size. The management application is
responsible for negotiating a control message size complying with the
requirements in section 9.3.1 of [1], taking this descriptor field
into consideration.

The userspace application can access the CDC MBIM functional
descriptor of a MBIM function using either of the two USB
configuration descriptor kernel interfaces described in [6] or [7].

See also the ioctl documentation below.


Fragmentation
-------------
The userspace application is responsible for all control message
fragmentation and defragmentaion, as described in section 9.5 of [1].


/dev/cdc-wdmX write()
---------------------
The MBIM control messages from the management application *must not*
exceed the negotiated control message size.


/dev/cdc-wdmX read()
--------------------
The management application *must* accept control messages of up the
negotiated control message size.


/dev/cdc-wdmX ioctl()
---------------------
IOCTL_WDM_MAX_COMMAND: Get Maximum Command Size
This ioctl returns the wMaxControlMessage field of the CDC MBIM
functional descriptor for MBIM devices.  This is intended as a
convenience, eliminating the need to parse the USB descriptors from
userspace.

::

        #include <stdio.h>
        #include <fcntl.h>
        #include <sys/ioctl.h>
        #include <linux/types.h>
        #include <linux/usb/cdc-wdm.h>
        int main()
        {
                __u16 max;
                int fd = open("/dev/cdc-wdm0", O_RDWR);
                if (!ioctl(fd, IOCTL_WDM_MAX_COMMAND, &max))
                        printf("wMaxControlMessage is %d\n", max);
        }


Custom device services
----------------------
The MBIM specification allows vendors to freely define additional
services.  This is fully supported by the cdc_mbim driver.

Support for new MBIM services, including vendor specified services, is
implemented entirely in userspace, like the rest of the MBIM control
protocol

New services should be registered in the MBIM Registry [5].


MBIM data channel ABI와 multiplexed IP session

163-195

MBIM data channel user space ABI

`wwanY` network device

`cdc_mbim` 드라이버는 MBIM data channel을 `wwan` type의 단일 network device로 표현합니다. 처음에는 이 network device가 MBIM IP session 0에 mapping됩니다.

Multiplexed IP session(IPS)

MBIM은 단일 USB data channel에서 최대 256개의 IP session을 multiplex할 수 있습니다. `cdc_mbim` 드라이버는 이러한 IP session을 master `wwanY` device의 802.1Q VLAN subdevice로 모델링하며, 0보다 큰 모든 Z에 대해 MBIM IP session Z를 VLAN ID Z에 mapping합니다.

Device가 지원하는 최대 Z 값은 [1]의 10.5.1절에 설명된 `MBIM_DEVICE_CAPS_INFO` structure에서 제공합니다.

User space 관리 application은 `SessionId`가 0보다 큰 MBIM IP session을 수립하기 전에 새 VLAN link를 추가해야 합니다. 이 link는 ioctl이나 netlink 같은 일반 VLAN kernel interface로 추가할 수 있습니다.

예를 들어 `SessionId` 3인 MBIM IP session의 link는 다음처럼 추가합니다.

ip link add link wwan0 name wwan0.3 type vlan id 3

드라이버는 `wwan0.3` network device를 MBIM IP session 3에 자동으로 mapping합니다.

MBIM data channel userspace ABI
===============================

wwanY network device
--------------------
The cdc_mbim driver represents the MBIM data channel as a single
network device of the "wwan" type. This network device is initially
mapped to MBIM IP session 0.


Multiplexed IP sessions (IPS)
-----------------------------
MBIM allows multiplexing up to 256 IP sessions over a single USB data
channel.  The cdc_mbim driver models such IP sessions as 802.1q VLAN
subdevices of the master wwanY device, mapping MBIM IP session Z to
VLAN ID Z for all values of Z greater than 0.

The device maximum Z is given in the MBIM_DEVICE_CAPS_INFO structure
described in section 10.5.1 of [1].

The userspace management application is responsible for adding new
VLAN links prior to establishing MBIM IP sessions where the SessionId
is greater than 0. These links can be added by using the normal VLAN
kernel interfaces, either ioctl or netlink.

For example, adding a link for a MBIM IP session with SessionId 3::

  ip link add link wwan0 name wwan0.3 type vlan id 3

The driver will automatically map the "wwan0.3" network device to MBIM
IP session 3.

Device Service Stream과 packet socket 처리

196-268

Device Service Stream(DSS)

MBIM은 같은 공유 USB data channel에서 최대 256개의 non-IP data stream도 multiplex할 수 있습니다. `cdc_mbim` 드라이버는 이 session을 master `wwanY` device에 속한 또 하나의 802.1Q VLAN subdevice 집합으로 모델링하며, 모든 A 값에 대해 MBIM DSS session A를 VLAN ID `(256 + A)`에 mapping합니다.

Device가 지원하는 최대 A 값은 [1]의 10.5.29절에 설명된 `MBIM_DEVICE_SERVICES_INFO` structure에서 제공합니다.

DSS VLAN subdevice는 공유 MBIM data channel과 MBIM DSS를 이해하는 user space application 사이의 실용적인 interface로 사용합니다. 그대로 end user에게 노출하려는 interface는 아닙니다. DSS session을 시작하는 user space application이 DSS data에 필요한 framing도 처리하고, stream type에 알맞은 방식으로 end user에게 stream을 제공한다고 가정합니다.

Network device ABI에 따라 전송되는 모든 DSS data frame에는 dummy Ethernet header가 필요합니다. 이 header의 내용은 다음 예외를 제외하면 임의로 정할 수 있습니다.

  • IP protocol `0x0800` 또는 `0x86dd`를 사용하는 TX frame은 drop됩니다.
  • RX frame의 protocol field는 `ETH_P_802_3`으로 설정되지만 올바른 802.3 frame 형식은 아닙니다.
  • RX frame의 destination address는 master device의 hardware address로 설정됩니다.

DSS를 지원하는 user space 관리 application은 TX에서 dummy Ethernet header를 추가하고 RX에서 이를 제거할 책임이 있습니다.

다음은 흔히 제공되는 도구를 사용해 `DssSessionId` 5를 `/dev/nmea` symlink가 가리키는 pty character device로 내보내는 간단한 예입니다.

ip link add link wwan0 name wwan0.dss5 type vlan id 261
ip link set dev wwan0.dss5 up
socat INTERFACE:wwan0.dss5,type=2 PTY:,echo=0,link=/dev/nmea

이 예는 DSS service를 시험하는 용도에 가장 적합합니다. 특정 MBIM DSS service를 지원하는 user space application은 해당 service가 요구하는 도구와 programming interface를 사용해야 합니다.

DSS session용 VLAN link를 추가하는 것은 완전히 선택 사항입니다. 관리 application은 대신 packet socket을 master network device에 직접 bind하고, 수신 VLAN tag로 frame을 올바른 DSS session에 mapping하며, TX에서는 적절한 tag가 든 18-byte VLAN Ethernet header를 추가할 수 있습니다.

이 방식을 사용할 때는 DSS VLAN 범위만 match하는 socket filter를 권장합니다. 그러면 관련 없는 IP session data가 user space로 불필요하게 복사되는 것을 피할 수 있습니다. 예를 들면 다음과 같습니다.

static struct sock_filter dssfilter[] = {
        /* use special negative offsets to get VLAN tag */
        BPF_STMT(BPF_LD|BPF_B|BPF_ABS, SKF_AD_OFF + SKF_AD_VLAN_TAG_PRESENT),
        BPF_JUMP(BPF_JMP|BPF_JEQ|BPF_K, 1, 0, 6), /* true */

        /* verify DSS VLAN range */
        BPF_STMT(BPF_LD|BPF_H|BPF_ABS, SKF_AD_OFF + SKF_AD_VLAN_TAG),
        BPF_JUMP(BPF_JMP|BPF_JGE|BPF_K, 256, 0, 4), /* 256 is first DSS VLAN */
        BPF_JUMP(BPF_JMP|BPF_JGE|BPF_K, 512, 3, 0), /* 511 is last DSS VLAN */

        /* verify ethertype */
        BPF_STMT(BPF_LD|BPF_H|BPF_ABS, 2 * ETH_ALEN),
        BPF_JUMP(BPF_JMP|BPF_JEQ|BPF_K, ETH_P_802_3, 0, 1),

        BPF_STMT(BPF_RET|BPF_K, (u_int)-1), /* accept */
        BPF_STMT(BPF_RET|BPF_K, 0),         /* ignore */
};
Device Service Streams (DSS)
----------------------------
MBIM also allows up to 256 non-IP data streams to be multiplexed over
the same shared USB data channel.  The cdc_mbim driver models these
sessions as another set of 802.1q VLAN subdevices of the master wwanY
device, mapping MBIM DSS session A to VLAN ID (256 + A) for all values
of A.

The device maximum A is given in the MBIM_DEVICE_SERVICES_INFO
structure described in section 10.5.29 of [1].

The DSS VLAN subdevices are used as a practical interface between the
shared MBIM data channel and a MBIM DSS aware userspace application.
It is not intended to be presented as-is to an end user. The
assumption is that a userspace application initiating a DSS session
also takes care of the necessary framing of the DSS data, presenting
the stream to the end user in an appropriate way for the stream type.

The network device ABI requires a dummy ethernet header for every DSS
data frame being transported.  The contents of this header is
arbitrary, with the following exceptions:

 - TX frames using an IP protocol (0x0800 or 0x86dd) will be dropped
 - RX frames will have the protocol field set to ETH_P_802_3 (but will
   not be properly formatted 802.3 frames)
 - RX frames will have the destination address set to the hardware
   address of the master device

The DSS supporting userspace management application is responsible for
adding the dummy ethernet header on TX and stripping it on RX.

This is a simple example using tools commonly available, exporting
DssSessionId 5 as a pty character device pointed to by a /dev/nmea
symlink::

  ip link add link wwan0 name wwan0.dss5 type vlan id 261
  ip link set dev wwan0.dss5 up
  socat INTERFACE:wwan0.dss5,type=2 PTY:,echo=0,link=/dev/nmea

This is only an example, most suitable for testing out a DSS
service. Userspace applications supporting specific MBIM DSS services
are expected to use the tools and programming interfaces required by
that service.

Note that adding VLAN links for DSS sessions is entirely optional.  A
management application may instead choose to bind a packet socket
directly to the master network device, using the received VLAN tags to
map frames to the correct DSS session and adding 18 byte VLAN ethernet
headers with the appropriate tag on TX.  In this case using a socket
filter is recommended, matching only the DSS VLAN subset. This avoid
unnecessary copying of unrelated IP session data to userspace.  For
example::

  static struct sock_filter dssfilter[] = {
        /* use special negative offsets to get VLAN tag */
        BPF_STMT(BPF_LD|BPF_B|BPF_ABS, SKF_AD_OFF + SKF_AD_VLAN_TAG_PRESENT),
        BPF_JUMP(BPF_JMP|BPF_JEQ|BPF_K, 1, 0, 6), /* true */

        /* verify DSS VLAN range */
        BPF_STMT(BPF_LD|BPF_H|BPF_ABS, SKF_AD_OFF + SKF_AD_VLAN_TAG),
        BPF_JUMP(BPF_JMP|BPF_JGE|BPF_K, 256, 0, 4),        /* 256 is first DSS VLAN */
        BPF_JUMP(BPF_JMP|BPF_JGE|BPF_K, 512, 3, 0),        /* 511 is last DSS VLAN */

        /* verify ethertype */
        BPF_STMT(BPF_LD|BPF_H|BPF_ABS, 2 * ETH_ALEN),
        BPF_JUMP(BPF_JMP|BPF_JEQ|BPF_K, ETH_P_802_3, 0, 1),

        BPF_STMT(BPF_RET|BPF_K, (u_int)-1),        /* accept */
        BPF_STMT(BPF_RET|BPF_K, 0),                /* ignore */
  };


Tagged IP session 0과 전체 VLAN mapping

269-317

Tagged IP session 0 VLAN

앞에서 설명했듯이 드라이버는 MBIM IP session 0을 특별하게 처리합니다. 처음에는 이 session을 `wwanY` network device의 untagged frame에 mapping합니다.

이 mapping에는 multiplex된 IPS와 DSS session에서 항상 실용적이지는 않은 몇 가지 제한이 따릅니다.

  • 어떤 IPS 또는 DSS session도 IP session 0의 MTU보다 큰 frame size를 사용할 수 없습니다.
  • IP session 0을 나타내는 network device가 up 상태가 아니면 어떤 IPS 또는 DSS session도 up 상태가 될 수 없습니다.

다른 IP session과 비슷하게 IP session 0도 VLAN subdevice로 mapping하도록 선택하면 이러한 문제를 피할 수 있습니다. Magic VLAN ID 4094의 VLAN link를 추가하면 이 동작이 활성화됩니다. 드라이버는 즉시 MBIM IP session 0을 이 VLAN에 mapping하기 시작하고 master `wwanY` device의 untagged frame은 drop합니다.

팁: 이 VLAN subdevice의 이름을 VLAN ID가 아니라 MBIM `SessionID`에 맞추면 end user가 덜 혼동할 수 있습니다. 예를 들면 다음과 같습니다.

ip link add link wwan0 name wwan0.0 type vlan id 4094

VLAN mapping

위에서 설명한 `cdc_mbim` 드라이버 mapping을 정리하면, `wwanY` network device의 VLAN tag와 공유 USB data channel의 MBIM session 사이에는 다음 관계가 있습니다.

cdc_mbim VLAN mapping
VLAN IDMBIM typeMBIM SessionID조건·비고
untaggedIPS0VLAN ID 4094 link가 없을 때, 아니면 drop
1-255IPS1-255`SessionID = VLANID`
256-511DSS0-255`SessionID = VLANID - 256`
512-4093--지원하지 않으며 항상 drop
4094IPS0VLAN ID 4094 link가 있을 때, 아니면 drop

원문의 ASCII 표를 같은 의미와 경계값을 유지한 구조화 표로 다시 그렸습니다.

Tagged IP session 0 VLAN
------------------------
As described above, MBIM IP session 0 is treated as special by the
driver.  It is initially mapped to untagged frames on the wwanY
network device.

This mapping implies a few restrictions on multiplexed IPS and DSS
sessions, which may not always be practical:

 - no IPS or DSS session can use a frame size greater than the MTU on
   IP session 0
 - no IPS or DSS session can be in the up state unless the network
   device representing IP session 0 also is up

These problems can be avoided by optionally making the driver map IP
session 0 to a VLAN subdevice, similar to all other IP sessions.  This
behaviour is triggered by adding a VLAN link for the magic VLAN ID
4094.  The driver will then immediately start mapping MBIM IP session
0 to this VLAN, and will drop untagged frames on the master wwanY
device.

Tip: It might be less confusing to the end user to name this VLAN
subdevice after the MBIM SessionID instead of the VLAN ID.  For
example::

  ip link add link wwan0 name wwan0.0 type vlan id 4094


VLAN mapping
------------

Summarizing the cdc_mbim driver mapping described above, we have this
relationship between VLAN tags on the wwanY network device and MBIM
sessions on the shared USB data channel::

  VLAN ID       MBIM type   MBIM SessionID           Notes
  ---------------------------------------------------------
  untagged      IPS         0                        a)
  1 - 255       IPS         1 - 255 <VLANID>
  256 - 511     DSS         0 - 255 <VLANID - 256>
  512 - 4093                                         b)
  4094          IPS         0                        c)

    a) if no VLAN ID 4094 link exists, else dropped
    b) unsupported VLAN range, unconditionally dropped
    c) if a VLAN ID 4094 link exists, else dropped


참고 문헌과 kernel interface 문서

318-355

참고 문헌

1) USB Implementers Forum, Inc., "Universal Serial Bus Communications Class Subclass Specification for Mobile Broadband Interface Model", Revision 1.0(Errata 1), 2013년 5월 1일.

http://www.usb.org/developers/docs/devclass_docs/

2) USB Implementers Forum, Inc., "Universal Serial Bus Communications Class Subclass Specifications for Network Control Model Devices", Revision 1.0(Errata 1), 2010년 11월 24일.

http://www.usb.org/developers/docs/devclass_docs/

3) `libmbim`: MBIM(Mobile Interface Broadband Model) protocol을 사용하는 WWAN modem 및 device와 통신하기 위한 glib 기반 library.

http://www.freedesktop.org/wiki/Software/libmbim/

4) `ModemManager`: 모바일 광대역 2G/3G/4G device와 connection을 제어하는 D-Bus 활성화 daemon.

http://www.freedesktop.org/wiki/Software/ModemManager/

5) "MBIM(Mobile Broadband Interface Model) Registry".

http://compliance.usb.org/mbim/

6) `/sys/kernel/debug/usb/devices` 출력 형식.

`Documentation/driver-api/usb/usb.rst`

7) `/sys/bus/usb/devices/.../descriptors`.

`Documentation/ABI/stable/sysfs-bus-usb`


References
==========

 1) USB Implementers Forum, Inc. - "Universal Serial Bus
    Communications Class Subclass Specification for Mobile Broadband
    Interface Model", Revision 1.0 (Errata 1), May 1, 2013

      - http://www.usb.org/developers/docs/devclass_docs/

 2) USB Implementers Forum, Inc. - "Universal Serial Bus
    Communications Class Subclass Specifications for Network Control
    Model Devices", Revision 1.0 (Errata 1), November 24, 2010

      - http://www.usb.org/developers/docs/devclass_docs/

 3) libmbim - "a glib-based library for talking to WWAN modems and
    devices which speak the Mobile Interface Broadband Model (MBIM)
    protocol"

      - http://www.freedesktop.org/wiki/Software/libmbim/

 4) ModemManager - "a DBus-activated daemon which controls mobile
    broadband (2G/3G/4G) devices and connections"

      - http://www.freedesktop.org/wiki/Software/ModemManager/

 5) "MBIM (Mobile Broadband Interface Model) Registry"

       - http://compliance.usb.org/mbim/

 6) "/sys/kernel/debug/usb/devices output format"

       - Documentation/driver-api/usb/usb.rst

 7) "/sys/bus/usb/devices/.../descriptors"

       - Documentation/ABI/stable/sysfs-bus-usb