요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.
1. 요약·해설
원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.
2. 영어 원문 전체
번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.
원문 전체 펼치기
.. 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 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 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 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
------------------------
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
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
3. 한국어 전문 번역
영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.
드라이버 개요, prefer_mbim 정책과 기본 사용법
1-67cdc_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-162MBIM 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-195MBIM 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-268Device 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-317Tagged 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 사이에는 다음 관계가 있습니다.
원문의 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
요약·해설
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로 사용하는 점이 이 문서의 핵심입니다.
`prefer_mbim`이 하위 호환 function을 어느 드라이버가 맡을지 결정합니다.
드라이버가 자동으로 수행하지 않는 user space 관리 순서입니다.
`cdc-wdm` pipe는 message를 그대로 전달하며 protocol 처리는 user space에 남습니다.
Descriptor, ioctl, read와 write가 공유하는 상한을 정리합니다.
IP session 1-255는 같은 번호의 VLAN subdevice로 나타납니다.
DSS payload를 network ABI로 운반할 때 dummy Ethernet header를 처리하는 경로입니다.
Dummy header라도 protocol과 destination에는 명시적인 제약이 있습니다.
Master device에 직접 bind할 때 unrelated IPS traffic을 제외합니다.
IPS, DSS, session 0의 magic VLAN과 drop 범위를 한 표로 통합했습니다.
Magic VLAN을 만들면 master의 untagged 경로가 즉시 대체됩니다.