다기능 복합 USB 가젯

개요

Multifunction Composite Gadget, 즉 `g_multi`는 USB composite framework를 폭넓게 사용해 여러 기능을 하나의 USB 장치로 제공하는 복합 가젯입니다.

호스트에서는 하나의 물리적 USB 장치가 여러 interface를 가진 composite device로 열거되고, 각 interface를 담당하는 class driver가 개별 기능을 처리합니다.

이 구조를 이용하면 네트워크, 직렬 통신, 저장 장치를 하나의 가젯 모듈에서 동시에 노출할 수 있습니다.

==============================
Multifunction Composite Gadget
==============================

Overview
========

The Multifunction Composite Gadget (or g_multi) is a composite gadget
that makes extensive use of the composite framework to provide
a... multifunction gadget.

표준·선택 구성

표준 구성은 RNDIS, USB CDC ACM, USB Mass Storage 기능을 하나의 USB configuration에 담습니다.

Kconfig option으로 CDC ECM Ethernet 기능을 켤 수 있고 RNDIS는 끌 수 있습니다. RNDIS와 CDC ECM을 둘 다 활성화하면 장치는 두 configuration을 가집니다.

두 configuration 구성에서는 첫 번째가 RNDIS를, 두 번째가 CDC ECM을 제공합니다. 호스트는 자신에게 적합한 configuration을 선택합니다.

CDC ECM을 켜는 비표준 구성을 사용하면 장치 기능 조합이 달라지므로 vendor ID 또는 product ID, 혹은 둘 다 변경해야 할 수 있습니다.

In its standard configuration it provides a single USB configuration
with RNDIS[1] (that is Ethernet), USB CDC[2] ACM (that is serial) and
USB Mass Storage functions.

A CDC ECM (Ethernet) function may be turned on via a Kconfig option
and RNDIS can be turned off.  If they are both enabled the gadget will
have two configurations -- one with RNDIS and another with CDC ECM[3].

Please note that if you use non-standard configuration (that is enable
CDC ECM) you may need to change vendor and/or product ID.

호스트 드라이버의 필요성

가젯의 기능을 실제로 사용하려면 호스트 쪽에서도 각 interface를 처리할 드라이버가 동작해야 합니다. 호스트 지원이 없으면 가젯을 구성해도 해당 기능을 이용할 수 없습니다.

필요한 설정과 드라이버 설치 방식은 운영체제마다 다르므로 Linux, Windows, 기타 시스템을 나누어 설명합니다.

Host drivers
============

To make use of the gadget one needs to make it work on host side --
without that there's no hope of achieving anything with the gadget.
As one might expect, things one need to do very from system to system.

Linux 호스트 드라이버

`g_multi`는 표준 composite framework와 표준 USB class를 사용하므로 Linux 호스트에는 별도의 전용 드라이버가 필요하지 않습니다. 각 기능은 해당 class용 기존 드라이버가 처리합니다.

RNDIS configuration이 첫 번째인 2-configuration 구성에서도 같은 원칙이 적용됩니다. Linux 호스트는 두 번째 CDC ECM configuration을 선택합니다.

CDC ECM은 Linux에서 더 자연스럽게 지원되므로 RNDIS보다 안정적으로 동작할 것으로 기대됩니다.

Linux host drivers
------------------

Since the gadget uses standard composite framework and appears as such
to Linux host it does not need any additional drivers on Linux host
side.  All the functions are handled by respective drivers developed
for them.

This is also true for two configuration set-up with RNDIS
configuration being the first one.  Linux host will use the second
configuration with CDC ECM which should work better under Linux.

Windows의 composite gadget 인식

Windows에서 가젯을 사용하려면 두 조건을 충족해야 합니다. 먼저 장치를 USB composite gadget으로 인식해야 하고, 이어서 각 interface에 적절한 기능 드라이버를 설치해야 합니다.

Windows의 composite 장치 인식 조건을 만족하면 USB Generic Parent Driver가 장치를 맡고 각 개별 interface에 맞는 드라이버를 찾습니다.

`g_multi` 사용자는 composite 인식 조건 대부분을 직접 신경 쓸 필요가 없습니다.

다만 장치는 단일 configuration이어야 합니다. RNDIS와 CDC ECM을 함께 켠 2-configuration 가젯은 적절한 INF를 직접 만들고 제출하지 않는 한 Windows에서 그대로 동작하지 않습니다.

따라서 Windows 호환성이 목표라면 기본 단일 configuration을 유지하거나, 복수 configuration을 설명하는 INF 배포 전략을 별도로 마련해야 합니다.

Windows host drivers
--------------------

For the gadget to work under Windows two conditions have to be met:

Detecting as composite gadget
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

First of all, Windows need to detect the gadget as an USB composite
gadget which on its own have some conditions[4].  If they are met,
Windows lets USB Generic Parent Driver[5] handle the device which then
tries to match drivers for each individual interface (sort of, don't
get into too many details).

The good news is: you do not have to worry about most of the
conditions!

The only thing to worry is that the gadget has to have a single
configuration so a dual RNDIS and CDC ECM gadget won't work unless you
create a proper INF -- and of course, if you do submit it!

Windows의 기능별 드라이버

Windows에서 더 까다로운 부분은 복합 장치 아래의 개별 function마다 알맞은 드라이버를 설치하는 일입니다.

Mass Storage는 interface class만으로 식별할 수 있으므로 Windows가 USB Mass Storage 구현임을 알아내고 적절한 기본 드라이버를 선택합니다.

RNDIS와 CDC ACM은 interface를 해당 Windows 드라이버에 연결하기 위한 INF 파일이 필요합니다.

원문 72줄의 `RDNIS` 표기는 문맥상 RNDIS를 뜻하며, 번역에서는 표준 명칭 RNDIS로 표기합니다.

Installing drivers for each function
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The other, trickier thing is making Windows install drivers for each
individual function.

For mass storage it is trivial since Windows detect it's an interface
implementing USB Mass Storage class and selects appropriate driver.

Things are harder with RDNIS and CDC ACM.

RNDIS INF

Windows가 가젯의 첫 번째 function에 RNDIS 드라이버를 선택하게 하려면 문서와 함께 제공되는 `linux.inf`를 사용합니다.

이 INF는 Windows의 RNDIS 드라이버를 가젯의 첫 번째 interface에 연결합니다.

시험 과정에서는 RNDIS가 첫 interface가 아닐 때 Windows가 제대로 응답하지 않는 문제가 관찰되었습니다.

표준 `g_multi` 구성만 사용한다면 이를 따로 걱정할 필요가 없지만, 자체 composite gadget을 개발하면서 function 순서를 바꾸는 경우 이 문제를 고려해야 합니다.

RNDIS
.....

To make Windows select RNDIS drivers for the first function in the
gadget, one needs to use the [[file:linux.inf]] file provided with this
document.  It "attaches" Window's RNDIS driver to the first interface
of the gadget.

Please note, that while testing we encountered some issues[6] when
RNDIS was not the first interface.  You do not need to worry abut it
unless you are trying to develop your own gadget in which case watch
out for this bug.

CDC ACM INF

CDC ACM에도 같은 방식으로 `linux-cdc-acm.inf`가 제공됩니다. 이 파일은 해당 ACM interface를 Windows의 직렬 드라이버에 연결합니다.

두 INF 모두 특정 interface 번호를 전제로 하므로 function 순서를 바꾸면 함께 수정해야 합니다.

CDC ACM
.......

Similarly, [[file:linux-cdc-acm.inf]] is provided for CDC ACM.

가젯 사용자 정의

`g_multi`의 function 순서를 재배치하면 각 기능의 interface 번호가 달라집니다. 제공된 INF는 interface 번호를 고정해 두었으므로 순서가 바뀐 구성에서는 그대로 동작하지 않습니다.

INF 안의 interface 번호를 새 구성에 맞게 고치는 일 자체는 어렵지 않지만, 배포하는 가젯 descriptor와 INF가 항상 같은 번호 체계를 사용해야 합니다.

제공 기능을 바꾸어 실험한 뒤에는 다른 사용자 정의 가젯이나 원본 `g_multi`와 충돌하지 않도록 vendor ID 또는 product ID를 변경해야 합니다.

같은 VID/PID로 구성을 계속 바꾸면 Windows가 이전 장치의 드라이버 정보를 cache해 새 구성을 잘못 연결할 수 있습니다. 이때 다른 USB port를 사용하면 도움이 될 수 있습니다.

남아 있는 phantom device와 cached 연결을 정리하려면 원문이 안내하는 USBDeview를 이용할 수도 있습니다.

Customising the gadget
......................

If you intend to hack the g_multi gadget be advised that rearranging
functions will obviously change interface numbers for each of the
functionality.  As an effect provided INFs won't work since they have
interface numbers hard-coded in them (it's not hard to change those
though[7]).

This also means, that after experimenting with g_multi and changing
provided functions one should change gadget's vendor and/or product ID
so there will be no collision with other customised gadgets or the
original gadget.

Failing to comply may cause brain damage after wondering for hours why
things don't work as intended before realising Windows have cached
some drivers information (changing USB port may sometimes help plus
you might try using USBDeview[8] to remove the phantom device).

INF 시험 범위

제공된 INF 파일은 Windows XP SP3, Windows Vista, Windows 7의 32비트 버전에서 시험되었습니다.

64비트 버전에서도 동작할 것으로 예상하지만 원문은 이를 시험 결과가 아닌 전망으로 표현합니다.

Windows XP SP2보다 오래된 Windows에서는 동작하지 않을 가능성이 큽니다.

INF testing
...........

Provided INF files have been tested on Windows XP SP3, Windows Vista
and Windows 7, all 32-bit versions.  It should work on 64-bit versions
as well.  It most likely won't work on Windows prior to Windows XP
SP2.

기타 운영체제

문서 작성 시점에는 Linux와 Windows 이외 운영체제용 드라이버를 시험하지 않았습니다.

macOS가 BSD에 기반하고 BSD가 오픈 소스라는 점에서 별도 설정 없이 동작할 것이라고 추측하지만, 원문은 실제 확인이 없는 낙관적 추정임을 명시합니다.

더 특수한 운영체제에 대해서는 제공할 수 있는 정보가 없습니다.

다른 시스템에서의 시험 결과와 드라이버 기여를 환영합니다.

Other systems
-------------

At this moment, drivers for any other systems have not been tested.
Knowing how MacOS is based on BSD and BSD is an Open Source it is
believed that it should (read: "I have no idea whether it will") work
out-of-the-box.

For more exotic systems I have even less to say...

Any testing and drivers *are* *welcome*!

작성자와 INF 출처

이 문서는 Michal Nazarewicz가 작성했습니다.

INF 파일은 Marek Szyprowski와 Xiaofan Chen의 지원을 받아 수정했습니다.

작업은 Microsoft RNDIS template, Microchip CDC ACM INF, David Brownell의 원본 INF 파일을 바탕으로 했습니다. 저자 이메일과 원본 표기는 영어 원문에 그대로 보존됩니다.

Authors
=======

This document has been written by Michal Nazarewicz
([[mailto:[email protected]]]).  INF files have been hacked with
support of Marek Szyprowski ([[mailto:[email protected]]]) and
Xiaofan Chen ([[mailto:[email protected]]]) basing on the MS RNDIS
template[9], Microchip's CDC ACM INF file and David Brownell's
([[mailto:[email protected]]]) original INF files.

각주 1~5

각주 [1]은 RNDIS를 Remote Network Driver Interface Specification으로 풀어 쓰고 Microsoft 문서 링크를 제공합니다.

각주 [2]는 CDC ACM을 Communications Device Class Abstract Control Model로 설명하며 USB class 문서 위치를 안내합니다.

각주 [3]은 CDC ECM을 CDC Ethernet Control Model로 풀이합니다.

각주 [4]는 Windows의 USB composite device 열거 조건 문서, 각주 [5]는 USB Generic Parent Driver 문서를 가리킵니다.

링크는 당시 문서의 출처 좌표를 보존하기 위해 원문 전체에 그대로 남아 있습니다.

Footnotes
=========

[1] Remote Network Driver Interface Specification,
[[https://msdn.microsoft.com/en-us/library/ee484414.aspx]].

[2] Communications Device Class Abstract Control Model, spec for this
and other USB classes can be found at
[[http://www.usb.org/developers/devclass_docs/]].

[3] CDC Ethernet Control Model.

[4] [[https://msdn.microsoft.com/en-us/library/ff537109(v=VS.85).aspx]]

[5] [[https://msdn.microsoft.com/en-us/library/ff539234(v=VS.85).aspx]]

각주 6~9

각주 [6]은 RNDIS가 첫 interface가 아닐 때 관찰한 문제를 Windows가 사용자 입력에 전혀 응답하지 않은 현상으로 설명합니다.

각주 [7]은 INF의 interface 번호를 수정할 때 참고할 수 있는 외부 게시물을 안내합니다.

각주 [8]은 Windows의 phantom USB device를 살펴보고 제거하는 USBDeview 페이지를 가리킵니다.

각주 [9]는 Microsoft RNDIS template의 출처입니다.

[6] To put it in some other nice words, Windows failed to respond to
any user input.

[7] You may find [[http://www.cygnal.org/ubb/Forum9/HTML/001050.html]]
useful.

[8] https://www.nirsoft.net/utils/usb_devices_view.html

[9] [[https://msdn.microsoft.com/en-us/library/ff570620.aspx]]