USB Gadget Function 시험

문서 범위와 대상 function

이 문서는 USB gadget이 제공하는 function을 기본적으로 시험하는 데 필요한 정보를 요약합니다.

대상은 ACM, ECM, ECM subset, EEM, FFS, HID, LOOPBACK, MASS STORAGE, MIDI, NCM, OBEX, PHONET, RNDIS, SERIAL, SOURCESINK, 구형 UAC1, UAC2, UVC, PRINTER, `u_audio` API 기반 UAC1, MIDI2의 21종입니다.

==============
Gadget Testing
==============

This file summarizes information on basic testing of USB functions
provided by gadgets.

.. contents

   1. ACM function
   2. ECM function
   3. ECM subset function
   4. EEM function
   5. FFS function
   6. HID function
   7. LOOPBACK function
   8. MASS STORAGE function
   9. MIDI function
   10. NCM function
   11. OBEX function
   12. PHONET function
   13. RNDIS function
   14. SERIAL function
   15. SOURCESINK function
   16. UAC1 function (legacy implementation)
   17. UAC2 function
   18. UVC function
   19. PRINTER function
   20. UAC1 function (new API)
   21. MIDI2 function

1. ACM function

ACM function은 `usb_f_acm.ko` 모듈이 제공합니다.

function 디렉터리를 만들 때 사용하는 이름은 `acm`입니다. 디렉터리에는 읽기 전용 `port_num` 속성 하나가 있습니다.

시스템 전체에서 ACM, generic serial, OBEX port를 합쳐 최대 4개까지 만들 수 있습니다.

시험은 host의 `/dev/ttyACM<X>`와 device의 `/dev/ttyGS<Y>` 사이에서 `cat`으로 데이터를 양방향 전송해 확인합니다.

1. ACM function
===============

The function is provided by usb_f_acm.ko module.

Function-specific configfs interface
------------------------------------

The function name to use when creating the function directory is "acm".
The ACM function provides just one attribute in its function directory:

	port_num

The attribute is read-only.

There can be at most 4 ACM/generic serial/OBEX ports in the system.


Testing the ACM function
------------------------

On the host::

	cat > /dev/ttyACM<X>

On the device::

	cat /dev/ttyGS<Y>

then the other way round

On the device::

	cat > /dev/ttyGS<Y>

On the host::

	cat /dev/ttyACM<X>

2. ECM function

ECM function은 `usb_f_ecm.ko` 모듈이 제공하며 function 디렉터리 이름은 `ecm`입니다.

`ifname`은 연결된 network interface 이름, `qmult`는 high/super speed queue 길이 배수, `host_addr`와 `dev_addr`는 Ethernet-over-USB 양 끝의 MAC address입니다.

`functions/ecm.<instance name>`을 만들면 `qmult` 기본값은 5이고 두 MAC address는 무작위로 선택됩니다.

function이 바인딩되지 않은 동안에는 `ifname`을 쓸 수 있습니다. `usb%d` 같은 interface pattern을 쓰면 network core가 다음 빈 `usbX` interface를 선택하며 기본 pattern도 `usb%d`입니다.

시험할 때 device와 host에 IP address를 구성하고 서로의 IP로 ping을 보냅니다.

2. ECM function
===============

The function is provided by usb_f_ecm.ko module.

Function-specific configfs interface
------------------------------------

The function name to use when creating the function directory is "ecm".
The ECM function provides these attributes in its function directory:

	=============== ==================================================
	ifname		network device interface name associated with this
			function instance
	qmult		queue length multiplier for high and super speed
	host_addr	MAC address of host's end of this
			Ethernet over USB link
	dev_addr	MAC address of device's end of this
			Ethernet over USB link
	=============== ==================================================

and after creating the functions/ecm.<instance name> they contain default
values: qmult is 5, dev_addr and host_addr are randomly selected.
The ifname can be written to if the function is not bound. A write must be an
interface pattern such as "usb%d", which will cause the net core to choose the
next free usbX interface. By default, it is set to "usb%d".

Testing the ECM function
------------------------

Configure IP addresses of the device and the host. Then:

On the device::

	ping <host's IP>

On the host::

	ping <device's IP>

3. ECM subset function

ECM subset function은 `usb_f_ecm_subset.ko` 모듈이 제공하며 function 디렉터리 이름은 `geth`입니다.

`ifname`, `qmult`, `host_addr`, `dev_addr`의 의미는 ECM과 같습니다.

원문은 function 생성 뒤의 기본값 설명에서 `functions/ecm.<instance name>` 경로를 사용합니다. 여기에 적힌 기본값은 `qmult=5`, 무작위 `dev_addr`와 `host_addr`입니다.

바인딩 전에는 `ifname`에 `usb%d` 같은 pattern을 쓸 수 있으며 network core가 다음 빈 `usbX`를 고릅니다. 기본값은 `usb%d`입니다.

device와 host에 IP address를 구성한 뒤 양방향 ping으로 시험합니다.

3. ECM subset function
======================

The function is provided by usb_f_ecm_subset.ko module.

Function-specific configfs interface
------------------------------------

The function name to use when creating the function directory is "geth".
The ECM subset function provides these attributes in its function directory:

	=============== ==================================================
	ifname		network device interface name associated with this
			function instance
	qmult		queue length multiplier for high and super speed
	host_addr	MAC address of host's end of this
			Ethernet over USB link
	dev_addr	MAC address of device's end of this
			Ethernet over USB link
	=============== ==================================================

and after creating the functions/ecm.<instance name> they contain default
values: qmult is 5, dev_addr and host_addr are randomly selected.
The ifname can be written to if the function is not bound. A write must be an
interface pattern such as "usb%d", which will cause the net core to choose the
next free usbX interface. By default, it is set to "usb%d".

Testing the ECM subset function
-------------------------------

Configure IP addresses of the device and the host. Then:

On the device::

	ping <host's IP>

On the host::

	ping <device's IP>

4. EEM function

EEM function은 `usb_f_eem.ko` 모듈이 제공하며 function 디렉터리 이름은 `eem`입니다.

제공 속성은 `ifname`, `qmult`, `host_addr`, `dev_addr`입니다.

`functions/eem.<instance name>` 생성 뒤 `qmult`는 5, host/device MAC address는 무작위 값입니다.

function을 아직 바인딩하지 않았다면 `ifname`에 `usb%d` 같은 pattern을 쓸 수 있습니다. 기본 pattern도 `usb%d`이며 network core가 다음 빈 `usbX`를 고릅니다.

device와 host에 IP address를 설정한 뒤 서로 ping을 보내 시험합니다.

4. EEM function
===============

The function is provided by usb_f_eem.ko module.

Function-specific configfs interface
------------------------------------

The function name to use when creating the function directory is "eem".
The EEM function provides these attributes in its function directory:

	=============== ==================================================
	ifname		network device interface name associated with this
			function instance
	qmult		queue length multiplier for high and super speed
	host_addr	MAC address of host's end of this
			Ethernet over USB link
	dev_addr	MAC address of device's end of this
			Ethernet over USB link
	=============== ==================================================

and after creating the functions/eem.<instance name> they contain default
values: qmult is 5, dev_addr and host_addr are randomly selected.
The ifname can be written to if the function is not bound. A write must be an
interface pattern such as "usb%d", which will cause the net core to choose the
next free usbX interface. By default, it is set to "usb%d".

Testing the EEM function
------------------------

Configure IP addresses of the device and the host. Then:

On the device::

	ping <host's IP>

On the host::

	ping <device's IP>

5. FFS function

FFS function은 `usb_f_fs.ko` 모듈이 제공하며 function 디렉터리 이름은 `ffs`입니다.

function 디렉터리는 의도적으로 비어 있고 수정할 수 없습니다. 디렉터리를 만들면 새 FunctionFS instance, 즉 device가 시스템에 생깁니다.

instance가 생기면 FunctionFS의 표준 절차에 따라 mount하고 실제 function을 구현하는 사용자 공간 process를 실행해야 합니다. 적절한 문자열을 `usb_gadget/<gadget>/UDC`에 써서 gadget을 활성화합니다.

FFS function은 읽기 전용 `ready` 속성 하나를 제공합니다. 사용자 공간이 ep0에 descriptor와 string을 써서 gadget을 활성화할 준비가 되면 값이 1입니다.

시험은 device에서 function의 사용자 공간 daemon을 시작하고 gadget을 활성화한 뒤, host에서 device가 제공한 USB function을 사용하는 방식입니다.

5. FFS function
===============

The function is provided by usb_f_fs.ko module.

Function-specific configfs interface
------------------------------------

The function name to use when creating the function directory is "ffs".
The function directory is intentionally empty and not modifiable.

After creating the directory there is a new instance (a "device") of FunctionFS
available in the system. Once a "device" is available, the user should follow
the standard procedure for using FunctionFS (mount it, run the userspace
process which implements the function proper). The gadget should be enabled
by writing a suitable string to usb_gadget/<gadget>/UDC.

The FFS function provides just one attribute in its function directory:

	ready

The attribute is read-only and signals if the function is ready (1) to be
used, E.G. if userspace has written descriptors and strings to ep0, so
the gadget can be enabled.

Testing the FFS function
------------------------

On the device: start the function's userspace daemon, enable the gadget

On the host: use the USB function provided by the device

6. HID function

HID function은 `usb_f_hid.ko` 모듈이 제공하며 function 디렉터리 이름은 `hid`입니다.

`protocol`은 HID protocol, `report_desc`는 `/dev/hidg<X>`로 전달하는 데이터 이외의 HID report descriptor 데이터, `report_length`는 report 길이, `subclass`는 HID subclass를 지정합니다.

키보드 예제에서는 `protocol=1`, `subclass=1`, `report_length=8`을 사용합니다. 원문은 `hd my_report_desc`로 63바이트 report descriptor를 보여 줍니다.

이 byte sequence는 `echo -ne \x05\x01...` 형식으로 `report_desc` 속성에 저장할 수 있습니다.

device에서 gadget을 만들고 가능하면 제어에 쓰는 host와 다른 host에 연결한 뒤 `/dev/hidg<N>`에 쓰는 프로그램을 실행합니다.

예제 `./hid_gadget_test /dev/hidg0 keyboard`는 `Documentation/usb/gadget_hid.rst`의 사용자 공간 프로그램이며, host에서 gadget이 보낸 keystroke를 관찰합니다.

6. HID function
===============

The function is provided by usb_f_hid.ko module.

Function-specific configfs interface
------------------------------------

The function name to use when creating the function directory is "hid".
The HID function provides these attributes in its function directory:

	=============== ===========================================
	protocol	HID protocol to use
	report_desc	data to be used in HID reports, except data
			passed with /dev/hidg<X>
	report_length	HID report length
	subclass	HID subclass to use
	=============== ===========================================

For a keyboard the protocol and the subclass are 1, the report_length is 8,
while the report_desc is::

  $ hd my_report_desc
  00000000  05 01 09 06 a1 01 05 07  19 e0 29 e7 15 00 25 01  |..........)...%.|
  00000010  75 01 95 08 81 02 95 01  75 08 81 03 95 05 75 01  |u.......u.....u.|
  00000020  05 08 19 01 29 05 91 02  95 01 75 03 91 03 95 06  |....).....u.....|
  00000030  75 08 15 00 25 65 05 07  19 00 29 65 81 00 c0     |u...%e....)e...|
  0000003f

Such a sequence of bytes can be stored to the attribute with echo::

  $ echo -ne \\x05\\x01\\x09\\x06\\xa1.....

Testing the HID function
------------------------

Device:

- create the gadget
- connect the gadget to a host, preferably not the one used
  to control the gadget
- run a program which writes to /dev/hidg<N>, e.g.
  a userspace program found in Documentation/usb/gadget_hid.rst::

	$ ./hid_gadget_test /dev/hidg0 keyboard

Host:

- observe the keystrokes from the gadget

7. LOOPBACK function

LOOPBACK function은 `usb_f_ss_lb.ko` 모듈이 제공하며 function 디렉터리 이름은 대소문자를 포함한 `Loopback`입니다.

`qlen`은 loopback queue 깊이이고 `bulk_buflen`은 buffer 길이입니다.

device에서는 gadget을 실행합니다.

host에서는 `tools/usb/testusb.c`의 `test-usb`를 사용해 시험합니다.

7. LOOPBACK function
====================

The function is provided by usb_f_ss_lb.ko module.

Function-specific configfs interface
------------------------------------

The function name to use when creating the function directory is "Loopback".
The LOOPBACK function provides these attributes in its function directory:

	=============== =======================
	qlen		depth of loopback queue
	bulk_buflen	buffer length
	=============== =======================

Testing the LOOPBACK function
-----------------------------

device: run the gadget

host: test-usb (tools/usb/testusb.c)

8. MASS STORAGE function

MASS STORAGE function은 `usb_f_mass_storage.ko` 모듈이 제공하며 function 디렉터리 이름은 `mass_storage`입니다.

function 수준의 `stall`은 bulk endpoint halt 허용 여부입니다. 올바르게 동작하지 않는 것으로 알려진 일부 USB device에서는 비활성화되지만, 일반적으로 true로 설정해야 합니다.

`num_buffers`는 pipeline buffer 수이며 유효 범위는 2부터 4입니다. `CONFIG_USB_GADGET_DEBUG_FILES`가 설정된 경우에만 노출됩니다.

기본으로 SCSI LUN #0에 해당하는 `lun.0` 디렉터리가 생깁니다. `mkdir functions/mass_storage.0/partition.5`처럼 새 LUN을 추가할 수 있습니다.

LUN 번호는 기본 생성되는 0번을 제외하면 연속일 필요가 없습니다. 최대 8개를 지정할 수 있고 이름은 `<name>.<number>` 형식이어야 하며 번호는 0..8입니다. `lun.<number>`가 권장 관례지만 필수는 아닙니다.

각 LUN에서 `file`은 backing file 경로, `ro`는 읽기 전용, `removable`은 이동식 표시, `cdrom`은 CD-ROM 표시, `nofua`는 SCSI WRITE(10,12)의 FUA flag 관련 설정입니다. `forced_eject`는 활성 function의 backing file을 host 허가와 무관하게 강제로 분리하는 쓰기 전용 파일이며 0이 아닌 바이트를 쓰면 eject됩니다.

시험은 device에서 gadget을 연결·활성화하고 host의 `dmesg`와 자동 mount 결과에서 USB drive가 나타나는지 확인합니다.

8. MASS STORAGE function
========================

The function is provided by usb_f_mass_storage.ko module.

Function-specific configfs interface
------------------------------------

The function name to use when creating the function directory is "mass_storage".
The MASS STORAGE function provides these attributes in its directory:
files:

	=============== ==============================================
	stall		Set to permit function to halt bulk endpoints.
			Disabled on some USB devices known not to work
			correctly. You should set it to true.
	num_buffers	Number of pipeline buffers. Valid numbers
			are 2..4. Available only if
			CONFIG_USB_GADGET_DEBUG_FILES is set.
	=============== ==============================================

and a default lun.0 directory corresponding to SCSI LUN #0.

A new lun can be added with mkdir::

	$ mkdir functions/mass_storage.0/partition.5

Lun numbering does not have to be continuous, except for lun #0 which is
created by default. A maximum of 8 luns can be specified and they all must be
named following the <name>.<number> scheme. The numbers can be 0..8.
Probably a good convention is to name the luns "lun.<number>",
although it is not mandatory.

In each lun directory there are the following attribute files:

	=============== ==============================================
	file		The path to the backing file for the LUN.
			Required if LUN is not marked as removable.
	ro		Flag specifying access to the LUN shall be
			read-only. This is implied if CD-ROM emulation
			is enabled as well as when it was impossible
			to open "filename" in R/W mode.
	removable	Flag specifying that LUN shall be indicated as
			being removable.
	cdrom		Flag specifying that LUN shall be reported as
			being a CD-ROM.
	nofua		Flag specifying that FUA flag
			in SCSI WRITE(10,12)
	forced_eject	This write-only file is useful only when
			the function is active. It causes the backing
			file to be forcibly detached from the LUN,
			regardless of whether the host has allowed it.
			Any non-zero number of bytes written will
			result in ejection.
	=============== ==============================================

Testing the MASS STORAGE function
---------------------------------

device: connect the gadget, enable it
host: dmesg, see the USB drives appear (if system configured to automatically
mount)

9. MIDI function

MIDI function은 `usb_f_midi.ko` 모듈이 제공하며 function 디렉터리 이름은 `midi`입니다.

속성은 MIDI buffer 길이 `buflen`, USB MIDI adapter ID 문자열 `id`, 입력·출력 port 수 `in_ports`·`out_ports`, adapter index `index`, USB read request queue 길이 `qlen`입니다.

시험은 gadget에서 host로 MIDI 파일을 재생하는 경우와 host에서 gadget으로 재생하는 경우로 나뉩니다.

gadget→host 시험에서 host는 `arecordmidi -p 24:0 from_gadget.mid`로 기록하고 gadget은 `aplaymidi -p 20:0 to_host.mid`로 재생합니다. `from_gadget.mid`는 `to_host.mid`와 동일하게 들려야 합니다.

host→gadget 시험에서는 gadget이 `arecordmidi -p 20:0 from_host.mid`로 기록하고 host가 `aplaymidi -p24:0 to_gadget.mid`로 재생합니다. 원문은 결과 파일을 `from_host.id`라고 적고 있으며 `to_gadget.mid`와 동일하게 들려야 한다고 설명합니다.

TiMidity가 설치되어 있으면 `aplaymidi -p 128:0 file.mid`처럼 MIDI 파일을 speaker/headphone으로 재생할 수 있습니다.

`aconnect 24:0 128:0`처럼 MIDI port를 논리적으로 연결할 수 있습니다.

gadget MIDI port를 TiMidity port에 연결하면 gadget 측에서 재생한 내용이 host speaker/headphone으로 들립니다. 원문의 마지막 문장은 gadget 측 명령을 `aplaymidi -l`로 표기합니다.

9. MIDI function
================

The function is provided by usb_f_midi.ko module.

Function-specific configfs interface
------------------------------------

The function name to use when creating the function directory is "midi".
The MIDI function provides these attributes in its function directory:

	=============== ====================================
	buflen		MIDI buffer length
	id		ID string for the USB MIDI adapter
	in_ports	number of MIDI input ports
	index		index value for the USB MIDI adapter
	out_ports	number of MIDI output ports
	qlen		USB read request queue length
	=============== ====================================

Testing the MIDI function
-------------------------

There are two cases: playing a mid from the gadget to
the host and playing a mid from the host to the gadget.

1) Playing a mid from the gadget to the host:

host::

  $ arecordmidi -l
   Port    Client name                      Port name
   14:0    Midi Through                     Midi Through Port-0
   24:0    MIDI Gadget                      MIDI Gadget MIDI 1
  $ arecordmidi -p 24:0 from_gadget.mid

gadget::

  $ aplaymidi -l
   Port    Client name                      Port name
   20:0    f_midi                           f_midi

  $ aplaymidi -p 20:0 to_host.mid

2) Playing a mid from the host to the gadget

gadget::

  $ arecordmidi -l
   Port    Client name                      Port name
   20:0    f_midi                           f_midi

  $ arecordmidi -p 20:0 from_host.mid

host::

  $ aplaymidi -l
   Port    Client name                      Port name
   14:0    Midi Through                     Midi Through Port-0
   24:0    MIDI Gadget                      MIDI Gadget MIDI 1

  $ aplaymidi -p24:0 to_gadget.mid

The from_gadget.mid should sound identical to the to_host.mid.

The from_host.id should sound identical to the to_gadget.mid.

MIDI files can be played to speakers/headphones with e.g. timidity installed::

  $ aplaymidi -l
   Port    Client name                      Port name
   14:0    Midi Through                     Midi Through Port-0
   24:0    MIDI Gadget                      MIDI Gadget MIDI 1
  128:0    TiMidity                         TiMidity port 0
  128:1    TiMidity                         TiMidity port 1
  128:2    TiMidity                         TiMidity port 2
  128:3    TiMidity                         TiMidity port 3

  $ aplaymidi -p 128:0 file.mid

MIDI ports can be logically connected using the aconnect utility, e.g.::

  $ aconnect 24:0 128:0 # try it on the host

After the gadget's MIDI port is connected to timidity's MIDI port,
whatever is played at the gadget side with aplaymidi -l is audible
in host's speakers/headphones.

10. NCM function

NCM function은 `usb_f_ncm.ko` 모듈이 제공하며 function 디렉터리 이름은 `ncm`입니다.

`ifname`, `qmult`, `host_addr`, `dev_addr`는 다른 Ethernet gadget과 같은 의미입니다.

`max_segment_size`는 P2P 연결에 필요한 segment 크기이며 원문은 이것이 MTU를 14바이트로 설정한다고 설명합니다.

instance 생성 뒤 `qmult=5`, 두 MAC address는 무작위, `ifname=usb%d`가 기본입니다. 바인딩 전에는 interface pattern을 써서 다음 빈 `usbX`를 선택하게 할 수 있습니다.

device와 host에 IP address를 구성한 뒤 양방향 ping으로 시험합니다.

10. NCM function
================

The function is provided by usb_f_ncm.ko module.

Function-specific configfs interface
------------------------------------

The function name to use when creating the function directory is "ncm".
The NCM function provides these attributes in its function directory:

	======================= ==================================================
	ifname			network device interface name associated with this
				function instance
	qmult			queue length multiplier for high and super speed
	host_addr		MAC address of host's end of this
				Ethernet over USB link
	dev_addr		MAC address of device's end of this
				Ethernet over USB link
	max_segment_size	Segment size required for P2P connections. This
				will set MTU to 14 bytes
	======================= ==================================================

and after creating the functions/ncm.<instance name> they contain default
values: qmult is 5, dev_addr and host_addr are randomly selected.
The ifname can be written to if the function is not bound. A write must be an
interface pattern such as "usb%d", which will cause the net core to choose the
next free usbX interface. By default, it is set to "usb%d".

Testing the NCM function
------------------------

Configure IP addresses of the device and the host. Then:

On the device::

	ping <host's IP>

On the host::

	ping <device's IP>

11. OBEX function

OBEX function은 `usb_f_obex.ko` 모듈이 제공하며 function 디렉터리 이름은 `obex`입니다.

읽기 전용 `port_num` 속성 하나를 제공합니다.

시스템의 ACM, generic serial, OBEX port 합계는 최대 4개입니다.

device에서는 `seriald -f /dev/ttyGS<Y> -s 1024`를 실행합니다. host에서는 vendor/product ID, interface 번호, endpoint address를 지정해 `serialc`를 실행합니다.

`seriald`와 `serialc`는 `https://github.com/felipebalbi/usb-tools.git`의 master branch에 있는 Felipe의 utility입니다.

11. OBEX function
=================

The function is provided by usb_f_obex.ko module.

Function-specific configfs interface
------------------------------------

The function name to use when creating the function directory is "obex".
The OBEX function provides just one attribute in its function directory:

	port_num

The attribute is read-only.

There can be at most 4 ACM/generic serial/OBEX ports in the system.

Testing the OBEX function
-------------------------

On device::

	seriald -f /dev/ttyGS<Y> -s 1024

On host::

	serialc -v <vendorID> -p <productID> -i<interface#> -a1 -s1024 \
                -t<out endpoint addr> -r<in endpoint addr>

where seriald and serialc are Felipe's utilities found here:

	https://github.com/felipebalbi/usb-tools.git master

12. PHONET function

PHONET function은 `usb_f_phonet.ko` 모듈이 제공하며 function 디렉터리 이름은 `phonet`입니다.

function instance에 연결된 network interface 이름을 나타내는 `ifname` 속성 하나를 제공합니다.

특정 하드웨어 없이는 `SOCK_STREAM` protocol을 시험할 수 없으므로 원문에서는 `SOCK_DGRAM`만 시험했습니다. 과거에는 이를 위해 원문에 연결된 linux-usb patch가 필요했습니다.

시험에는 `git://git.gitorious.org/meego-cellular/phonet-utils.git`의 도구가 필요합니다.

host는 주소 `0x10`을 `usbpn0`에 지정하고 `0x6c`, `0x10` route를 추가한 뒤 interface를 올립니다. device는 주소 `0x6c`을 `upnlink0`에 지정하고 `0x10` route를 추가한 뒤 interface를 올립니다.

host→device 시험은 device에서 `pnxmit -a 0x6c -r`, host에서 `pnxmit -a 0x10 -s 0x6c`을 실행하며 데이터가 device로 전달되어야 합니다.

반대 방향은 host에서 `pnxmit -a 0x10 -r`, device에서 `pnxmit -a 0x6c -s 0x10`을 실행합니다.

12. PHONET function
===================

The function is provided by usb_f_phonet.ko module.

Function-specific configfs interface
------------------------------------

The function name to use when creating the function directory is "phonet".
The PHONET function provides just one attribute in its function directory:

	=============== ==================================================
	ifname		network device interface name associated with this
			function instance
	=============== ==================================================

Testing the PHONET function
---------------------------

It is not possible to test the SOCK_STREAM protocol without a specific piece
of hardware, so only SOCK_DGRAM has been tested. For the latter to work,
in the past I had to apply the patch mentioned here:

http://www.spinics.net/lists/linux-usb/msg85689.html

These tools are required:

git://git.gitorious.org/meego-cellular/phonet-utils.git

On the host::

	$ ./phonet -a 0x10 -i usbpn0
	$ ./pnroute add 0x6c usbpn0
	$./pnroute add 0x10 usbpn0
	$ ifconfig usbpn0 up

On the device::

	$ ./phonet -a 0x6c -i upnlink0
	$ ./pnroute add 0x10 upnlink0
	$ ifconfig upnlink0 up

Then a test program can be used::

	http://www.spinics.net/lists/linux-usb/msg85690.html

On the device::

	$ ./pnxmit -a 0x6c -r

On the host::

	$ ./pnxmit -a 0x10 -s 0x6c

As a result some data should be sent from host to device.
Then the other way round:

On the host::

	$ ./pnxmit -a 0x10 -r

On the device::

	$ ./pnxmit -a 0x6c -s 0x10

13. RNDIS function

RNDIS function은 `usb_f_rndis.ko` 모듈이 제공하며 function 디렉터리 이름은 `rndis`입니다.

속성은 `ifname`, `qmult`, `host_addr`, `dev_addr`입니다.

`functions/rndis.<instance name>` 생성 뒤 `qmult=5`, MAC address는 무작위로 선택됩니다.

바인딩 전에는 `ifname`에 `usb%d` 같은 interface pattern을 쓸 수 있고 network core가 다음 빈 `usbX`를 선택합니다. 기본값은 `usb%d`입니다.

device와 host에 IP address를 구성한 뒤 양방향 ping으로 시험합니다.

13. RNDIS function
==================

The function is provided by usb_f_rndis.ko module.

Function-specific configfs interface
------------------------------------

The function name to use when creating the function directory is "rndis".
The RNDIS function provides these attributes in its function directory:

	=============== ==================================================
	ifname		network device interface name associated with this
			function instance
	qmult		queue length multiplier for high and super speed
	host_addr	MAC address of host's end of this
			Ethernet over USB link
	dev_addr	MAC address of device's end of this
			Ethernet over USB link
	=============== ==================================================

and after creating the functions/rndis.<instance name> they contain default
values: qmult is 5, dev_addr and host_addr are randomly selected.
The ifname can be written to if the function is not bound. A write must be an
interface pattern such as "usb%d", which will cause the net core to choose the
next free usbX interface. By default, it is set to "usb%d".

Testing the RNDIS function
--------------------------

Configure IP addresses of the device and the host. Then:

On the device::

	ping <host's IP>

On the host::

	ping <device's IP>

14. SERIAL function

SERIAL function은 `usb_f_gser.ko` 모듈이 제공하며 function 디렉터리 이름은 `gser`입니다.

읽기 전용 `port_num` 속성 하나를 제공합니다.

시스템의 ACM, generic serial, OBEX port 합계는 최대 4개입니다.

host에서 `usbserial`을 로드하고 `generic/new_id`에 gadget의 VID와 PID를 등록합니다.

그 뒤 host의 `/dev/ttyUSB<X>`와 target의 `/dev/ttyGS<Y>`에서 `cat` 송수신 방향을 서로 바꿔 양방향 전송을 확인합니다.

14. SERIAL function
===================

The function is provided by usb_f_gser.ko module.

Function-specific configfs interface
------------------------------------

The function name to use when creating the function directory is "gser".
The SERIAL function provides just one attribute in its function directory:

	port_num

The attribute is read-only.

There can be at most 4 ACM/generic serial/OBEX ports in the system.

Testing the SERIAL function
---------------------------

On host::

	insmod usbserial
	echo VID PID >/sys/bus/usb-serial/drivers/generic/new_id

On host::

	cat > /dev/ttyUSB<X>

On target::

	cat /dev/ttyGS<Y>

then the other way round

On target::

	cat > /dev/ttyGS<Y>

On host::

	cat /dev/ttyUSB<X>

15. SOURCESINK function

SOURCESINK function은 LOOPBACK과 같은 `usb_f_ss_lb.ko` 모듈이 제공하며 function 디렉터리 이름은 대소문자를 포함한 `SourceSink`입니다.

`pattern`은 0이면 all zeros, 1이면 mod63, 2이면 pattern 없음입니다. isochronous 설정은 `isoc_interval` 1..16, `isoc_maxpacket`은 full speed 0..1023 및 high/super speed 0..1024, `isoc_mult`는 high/super speed에서 0..2, `isoc_maxburst`는 super speed에서 0..15입니다.

bulk와 iso queue는 `bulk_buflen`, `bulk_qlen`, `iso_qlen`으로 buffer 길이와 queue 깊이를 설정합니다.

device에서 gadget을 실행하고 host에서 `tools/usb/testusb.c`의 `test-usb`로 시험합니다.

15. SOURCESINK function
=======================

The function is provided by usb_f_ss_lb.ko module.

Function-specific configfs interface
------------------------------------

The function name to use when creating the function directory is "SourceSink".
The SOURCESINK function provides these attributes in its function directory:

	=============== ==================================
	pattern		0 (all zeros), 1 (mod63), 2 (none)
	isoc_interval	1..16
	isoc_maxpacket	0 - 1023 (fs), 0 - 1024 (hs/ss)
	isoc_mult	0..2 (hs/ss only)
	isoc_maxburst	0..15 (ss only)
	bulk_buflen	buffer length
	bulk_qlen	depth of queue for bulk
	iso_qlen	depth of queue for iso
	=============== ==================================

Testing the SOURCESINK function
-------------------------------

device: run the gadget

host: test-usb (tools/usb/testusb.c)

16. UAC1 function (legacy)

구형 UAC1 function은 `usb_f_uac1_legacy.ko` 모듈이 제공하며 function 디렉터리 이름은 `uac1_legacy`입니다.

`audio_buf_size`는 audio buffer 크기, `fn_cap`은 capture PCM device 파일, `fn_cntl`은 control device 파일, `fn_play`는 playback PCM device 파일입니다.

`req_buf_size`와 `req_count`는 각각 ISO OUT endpoint request buffer 크기와 request 수이며, 모든 속성에는 합리적인 기본값이 있습니다.

device에서 gadget을 실행하고 host에서 `aplay -l`을 실행해 USB Audio Gadget이 목록에 나타나는지 확인합니다.

16. UAC1 function (legacy implementation)
=========================================

The function is provided by usb_f_uac1_legacy.ko module.

Function-specific configfs interface
------------------------------------

The function name to use when creating the function directory
is "uac1_legacy".
The uac1 function provides these attributes in its function directory:

	=============== ====================================
	audio_buf_size	audio buffer size
	fn_cap		capture pcm device file name
	fn_cntl		control device file name
	fn_play		playback pcm device file name
	req_buf_size	ISO OUT endpoint request buffer size
	req_count	ISO OUT endpoint request count
	=============== ====================================

The attributes have sane default values.

Testing the UAC1 function
-------------------------

device: run the gadget

host::

	aplay -l # should list our USB Audio Gadget

17. UAC2 function

UAC2 function은 `usb_f_uac2.ko` 모듈이 제공하며 function 디렉터리 이름은 `uac2`입니다.

capture 속성은 channel mask `c_chmask`, comma-separated sample rate 목록 `c_srate`, sample size `c_ssize`, synchronization type `c_sync`, mute/volume enable, 1/256dB 단위 volume min/max/resolution, HS/SS `bInterval`인 `c_hs_bint`입니다.

`fb_max`는 asynchronous mode의 최대 추가 대역폭입니다. playback 쪽은 `p_chmask`, `p_srate`, `p_ssize`, mute/volume enable, volume min/max/resolution, `p_hs_bint`를 제공합니다.

`req_number`는 capture와 playback 양쪽에 미리 할당할 request 수입니다. `function_name`, `if_ctrl_name`, input/output clock, playback/capture terminal·channel·function unit 이름과 terminal type code도 설정할 수 있습니다.

모든 속성에는 합리적인 기본값이 있습니다.

device에서 gadget을 실행하고 host의 `aplay -l`에서 USB Audio Gadget을 확인합니다. 실제 hardware 없이 host와 audio data stream을 주고받을 수 있습니다.

device에서 실제 소리를 들으려면 `arecord`로 gadget capture stream을 읽어 `aplay`로 실제 sound card에 전달합니다. 원문은 `hw:2,0 → hw:0,0`과 `UAC2Gadget → OdroidU3` 예제를 제공합니다.

17. UAC2 function
=================

The function is provided by usb_f_uac2.ko module.

Function-specific configfs interface
------------------------------------

The function name to use when creating the function directory is "uac2".
The uac2 function provides these attributes in its function directory:

	================ ====================================================
	c_chmask         capture channel mask
	c_srate          list of capture sampling rates (comma-separated)
	c_ssize          capture sample size (bytes)
	c_sync           capture synchronization type (async/adaptive)
	c_mute_present   capture mute control enable
	c_volume_present capture volume control enable
	c_volume_min     capture volume control min value (in 1/256 dB)
	c_volume_max     capture volume control max value (in 1/256 dB)
	c_volume_res     capture volume control resolution (in 1/256 dB)
	c_hs_bint        capture bInterval for HS/SS (1-4: fixed, 0: auto)
	fb_max           maximum extra bandwidth in async mode
	p_chmask         playback channel mask
	p_srate          list of playback sampling rates (comma-separated)
	p_ssize          playback sample size (bytes)
	p_mute_present   playback mute control enable
	p_volume_present playback volume control enable
	p_volume_min     playback volume control min value (in 1/256 dB)
	p_volume_max     playback volume control max value (in 1/256 dB)
	p_volume_res     playback volume control resolution (in 1/256 dB)
	p_hs_bint        playback bInterval for HS/SS (1-4: fixed, 0: auto)
	req_number       the number of pre-allocated request for both capture
	                 and playback
	function_name    name of the interface
	if_ctrl_name     topology control name
	clksrc_in_name   input clock name
	clksrc_out_name  output clock name
	p_it_name        playback input terminal name
	p_it_ch_name     playback input first channel name
	p_ot_name        playback output terminal name
	p_fu_vol_name    playback function unit name
	c_it_name        capture input terminal name
	c_it_ch_name     capture input first channel name
	c_ot_name        capture output terminal name
	c_fu_vol_name    capture functional unit name
	c_terminal_type  code of the capture terminal type
	p_terminal_type  code of the playback terminal type
	================ ====================================================

The attributes have sane default values.

Testing the UAC2 function
-------------------------

device: run the gadget
host: aplay -l # should list our USB Audio Gadget

This function does not require real hardware support, it just
sends a stream of audio data to/from the host. In order to
actually hear something at the device side, a command similar
to this must be used at the device side::

	$ arecord -f dat -t wav -D hw:2,0 | aplay -D hw:0,0 &

e.g.::

	$ arecord -f dat -t wav -D hw:CARD=UAC2Gadget,DEV=0 | \
	  aplay -D default:CARD=OdroidU3

18. UVC function

UVC function은 `usb_f_uvc.ko` 모듈이 제공하며 function 디렉터리 이름은 `uvc`입니다.

function root 속성은 endpoint polling interval `streaming_interval`, SuperSpeed companion descriptor의 `bMaxBurst`인 `streaming_maxburst`, endpoint 최대 packet 크기 `streaming_maxpacket`, interface 이름 `function_name`입니다.

`control`과 `streaming` 하위 디렉터리에는 다시 여러 하위 디렉터리가 있습니다. 합리적인 기본값도 있지만 control header, streaming header, format description, frame description은 사용자가 제공해야 합니다.

control header는 `control/header`에 만들고 `control/class/fs` 및/또는 `control/class/ss`에서 링크합니다. streaming header는 `streaming/header`에 만들고 fs/hs/ss class에서 필요한 속도에 링크합니다.

format은 `streaming/mjpeg` 및/또는 `streaming/uncompressed`에 만들고, frame은 해당 format 디렉터리 아래에 만듭니다. 각 frame의 `dwFrameInterval`은 줄마다 interval 값 하나를 갖습니다.

시험할 때 device에서 gadget과 `vivid`를 실행하고 `uvc-gadget -u <uvc node> -v <vivid node>`를 사용합니다. 원문은 ideasonboard의 uvc-gadget과 지정 patch를 참조합니다.

host에서는 `luvcview -f yuv`로 영상 스트림을 확인합니다.

18. UVC function
================

The function is provided by usb_f_uvc.ko module.

Function-specific configfs interface
------------------------------------

The function name to use when creating the function directory is "uvc".
The uvc function provides these attributes in its function directory:

	=================== ================================================
	streaming_interval  interval for polling endpoint for data transfers
	streaming_maxburst  bMaxBurst for super speed companion descriptor
	streaming_maxpacket maximum packet size this endpoint is capable of
			    sending or receiving when this configuration is
			    selected
	function_name       name of the interface
	=================== ================================================

There are also "control" and "streaming" subdirectories, each of which contain
a number of their subdirectories. There are some sane defaults provided, but
the user must provide the following:

	================== ====================================================
	control header     create in control/header, link from control/class/fs
			   and/or control/class/ss
	streaming header   create in streaming/header, link from
			   streaming/class/fs and/or streaming/class/hs and/or
			   streaming/class/ss
	format description create in streaming/mjpeg and/or
			   streaming/uncompressed
	frame description  create in streaming/mjpeg/<format> and/or in
			   streaming/uncompressed/<format>
	================== ====================================================

Each frame description contains frame interval specification, and each
such specification consists of a number of lines with an interval value
in each line. The rules stated above are best illustrated with an example::

  # mkdir functions/uvc.usb0/control/header/h
  # cd functions/uvc.usb0/control/
  # ln -s header/h class/fs
  # ln -s header/h class/ss
  # mkdir -p functions/uvc.usb0/streaming/uncompressed/u/360p
  # cat <<EOF > functions/uvc.usb0/streaming/uncompressed/u/360p/dwFrameInterval
  666666
  1000000
  5000000
  EOF
  # cd $GADGET_CONFIGFS_ROOT
  # mkdir functions/uvc.usb0/streaming/header/h
  # cd functions/uvc.usb0/streaming/header/h
  # ln -s ../../uncompressed/u
  # cd ../../class/fs
  # ln -s ../../header/h
  # cd ../../class/hs
  # ln -s ../../header/h
  # cd ../../class/ss
  # ln -s ../../header/h


Testing the UVC function
------------------------

device: run the gadget, modprobe vivid::

  # uvc-gadget -u /dev/video<uvc video node #> -v /dev/video<vivid video node #>

where uvc-gadget is this program:
	http://git.ideasonboard.org/uvc-gadget.git

with these patches:

	https://lore.kernel.org/r/1386675637-18243-1-git-send-email-r.baldyga@samsung.com/

host::

	luvcview -f yuv

19. PRINTER function

PRINTER function은 `usb_f_printer.ko` 모듈이 제공하며 function 디렉터리 이름은 `printer`입니다.

`pnp_string`은 host에 전달할 PNP string 데이터이고 `q_len`은 endpoint당 request 수입니다.

가장 기본적인 시험에서 device는 gadget을 실행하고 `/devices/virtual/usb_printer_gadget/`을 나열해 `g_printer<number>`가 보이는지 확인합니다.

udev가 활성화되어 있으면 device의 `/dev/g_printer<number>`와 host의 `/dev/usb/lp0`이 자동으로 생겨야 합니다.

host→device 전송은 device에서 `cat /dev/g_printer<number>`로 읽고 host에서 `cat > /dev/usb/lp0`으로 씁니다.

device→host 전송은 device에서 `cat > /dev/g_printer<number>`로 쓰고 host에서 `cat /dev/usb/lp0`으로 읽습니다.

고급 시험은 `Documentation/usb/gadget_printer.rst`에 설명된 `prn_example`로 수행할 수 있습니다.

19. PRINTER function
====================

The function is provided by usb_f_printer.ko module.

Function-specific configfs interface
------------------------------------

The function name to use when creating the function directory is "printer".
The printer function provides these attributes in its function directory:

	==========	===========================================
	pnp_string	Data to be passed to the host in pnp string
	q_len		Number of requests per endpoint
	==========	===========================================

Testing the PRINTER function
----------------------------

The most basic testing:

device: run the gadget::

	# ls -l /devices/virtual/usb_printer_gadget/

should show g_printer<number>.

If udev is active, then /dev/g_printer<number> should appear automatically.

host:

If udev is active, then e.g. /dev/usb/lp0 should appear.

host->device transmission:

device::

	# cat /dev/g_printer<number>

host::

	# cat > /dev/usb/lp0

device->host transmission::

	# cat > /dev/g_printer<number>

host::

	# cat /dev/usb/lp0

More advanced testing can be done with the prn_example
described in Documentation/usb/gadget_printer.rst.

20. UAC1 function (u_audio API)

새 UAC1 function은 `usb_f_uac1.ko` 모듈이 제공하며 가상 ALSA card를 만들고 audio stream을 그 card로 sink/source합니다. function 디렉터리 이름은 `uac1`입니다.

capture 쪽은 `c_chmask`, comma-separated `c_srate`, `c_ssize`, mute/volume enable, 1/256dB 단위 volume min/max/resolution을 제공합니다.

playback 쪽은 대응하는 `p_chmask`, `p_srate`, `p_ssize`, mute/volume enable, volume min/max/resolution을 제공합니다.

`req_number`는 capture와 playback 양쪽의 pre-allocated request 수이고 `function_name`은 interface 이름입니다. playback/capture input terminal, channel, output terminal, mute/volume functional unit 이름도 설정할 수 있습니다.

속성에는 합리적인 기본값이 있습니다. 실제 hardware 없이 host와 audio data stream을 주고받습니다.

device에서 gadget을 실행하고 host의 `aplay -l`에서 USB Audio Gadget을 확인합니다. 실제 소리를 들으려면 device의 `arecord` 출력을 실제 sound card의 `aplay`로 pipe하며 원문은 `UAC1Gadget → OdroidU3` 예제를 제공합니다.

20. UAC1 function (virtual ALSA card, using u_audio API)
========================================================

The function is provided by usb_f_uac1.ko module.
It will create a virtual ALSA card and the audio streams are simply
sinked to and sourced from it.

Function-specific configfs interface
------------------------------------

The function name to use when creating the function directory is "uac1".
The uac1 function provides these attributes in its function directory:

	================ ====================================================
	c_chmask         capture channel mask
	c_srate          list of capture sampling rates (comma-separated)
	c_ssize          capture sample size (bytes)
	c_mute_present   capture mute control enable
	c_volume_present capture volume control enable
	c_volume_min     capture volume control min value (in 1/256 dB)
	c_volume_max     capture volume control max value (in 1/256 dB)
	c_volume_res     capture volume control resolution (in 1/256 dB)
	p_chmask         playback channel mask
	p_srate          list of playback sampling rates (comma-separated)
	p_ssize          playback sample size (bytes)
	p_mute_present   playback mute control enable
	p_volume_present playback volume control enable
	p_volume_min     playback volume control min value (in 1/256 dB)
	p_volume_max     playback volume control max value (in 1/256 dB)
	p_volume_res     playback volume control resolution (in 1/256 dB)
	req_number       the number of pre-allocated requests for both capture
	                 and playback
	function_name    name of the interface
	p_it_name        playback input terminal name
	p_it_ch_name     playback channels name
	p_ot_name        playback output terminal name
	p_fu_vol_name    playback mute/volume functional unit name
	c_it_name        capture input terminal name
	c_it_ch_name     capture channels name
	c_ot_name        capture output terminal name
	c_fu_vol_name    capture mute/volume functional unit name
	================ ====================================================

The attributes have sane default values.

Testing the UAC1 function
-------------------------

device: run the gadget
host: aplay -l # should list our USB Audio Gadget

This function does not require real hardware support, it just
sends a stream of audio data to/from the host. In order to
actually hear something at the device side, a command similar
to this must be used at the device side::

	$ arecord -f dat -t wav -D hw:2,0 | aplay -D hw:0,0 &

e.g.::

	$ arecord -f dat -t wav -D hw:CARD=UAC1Gadget,DEV=0 | \
	  aplay -D default:CARD=OdroidU3

21. MIDI2 function

MIDI2 function은 `usb_f_midi2.ko` 모듈이 제공합니다. UMP packet을 loopback하는 UMP rawmidi device가 포함된 가상 ALSA card를 만들고, legacy rawmidi device도 함께 생성합니다. UMP rawmidi는 ALSA sequencer client에도 바인딩됩니다.

function 디렉터리 이름은 `midi2`입니다. card 최상위에는 UMP Stream message 처리 여부 `process_ump`, static block 여부 `static_block`, 선택적 interface 이름 `iface_name`이 있습니다.

`ep.0` 하위 디렉터리는 USB MIDI endpoint 한 쌍을 나타내는 UMP Endpoint 속성을 제공합니다. `protocol_caps`는 MIDI 1.0, MIDI 2.0 또는 둘 다를 1, 2, 3으로 표시하고 `protocol`은 기본 protocol 1 또는 2입니다.

Endpoint에는 `ep_name`, `product_id`, 24-bit `manufacturer`, 16-bit `family`와 `model`, 32-bit `sw_revision`도 있습니다.

각 Endpoint의 `block.0`은 Function Block 0을 나타냅니다. 이름, direction, 첫 group과 group 수, MIDI 1.0용 group 범위, UI hint, MIDI-CI version, legacy MIDI 1.0 유형, SysEx8 stream 최대 수, active flag를 설정합니다.

`direction`은 input=1, output=2, bidirectional=3입니다. `first_group`은 0..15, `num_groups`는 1..16, MIDI 1.0용 첫 group은 0..15이고 group 수는 0..16입니다.

`ui_hint`는 unknown=0, receiver=1, sender=2, both=3입니다. `is_midi1`은 MIDI 2.0 device=0, 제한 없는 MIDI 1.0=1, low speed MIDI 1.0=2입니다.

여러 Function Block이 필요하면 연속 번호의 `block.<num>`을 만들며 동적으로 제거할 수도 있습니다. 여러 UMP Endpoint도 연속 번호의 `ep.<num>`으로 추가합니다.

UMP v1.1을 지원하지 않는 구형 MIDI 2.0 device를 모방하려면 `process_ump=0`으로 설정해 모든 UMP v1.1 요청을 무시합니다.

device와 host 각각에서 `/proc/asound/cards`를 확인하면 새 sound card가 나타납니다. host에서는 USB audio driver 구성에 따라 MIDI1 또는 MIDI2 device로 보입니다. ALSA sequencer가 활성화되면 양쪽에서 `MIDI 2.0 Gadget` 같은 UMP MIDI client를 찾을 수 있습니다.

driver는 데이터를 단순 loopback하므로 시험에 실제 MIDI hardware가 필요하지 않습니다.

gadget→host 입력 시험은 gadget에서 `aplaymidi -p 20:1 to_host.mid`, host에서 `arecordmidi -p 24:1 from_gadget.mid`를 사용합니다. UMP 지원 응용 프로그램은 raw UMP packet도 송수신할 수 있고, 예제 `aseqdump -u 2 -p 24:1`은 Program change와 Channel pressure를 표시합니다.

host→gadget 출력 시험은 gadget에서 `arecordmidi -p 20:1 from_host.mid`, host에서 `aplaymidi -p 24:1 to_gadget.mid`를 실행합니다.

host의 altset 0 MIDI 1.0 접근도 지원되며 gadget에서 UMP packet으로 상호 변환되고 Function Block 0에만 연결됩니다. 현재 mode는 `SND_CTL_IFACE_RAWMIDI`의 ALSA control `Operation Mode`로 확인합니다. 값 0은 unused, 1은 MIDI 1.0(altset 0), 2는 MIDI 2.0(altset 1)이며 원문 예제 값 2는 MIDI 2.0 동작을 뜻합니다.

21. MIDI2 function
==================

The function is provided by usb_f_midi2.ko module.
It will create a virtual ALSA card containing a UMP rawmidi device
where the UMP packet is looped back. In addition, a legacy rawmidi
device is created. The UMP rawmidi is bound with ALSA sequencer
clients, too.

Function-specific configfs interface
------------------------------------

The function name to use when creating the function directory is "midi2".
The midi2 function provides these attributes in its function directory
as the card top-level information:

	=============	=================================================
	process_ump	Bool flag to process UMP Stream messages (0 or 1)
	static_block	Bool flag for static blocks (0 or 1)
	iface_name	Optional interface name string
	=============	=================================================

The directory contains a subdirectory "ep.0", and this provides the
attributes for a UMP Endpoint (which is a pair of USB MIDI Endpoints):

	=============	=================================================
	protocol_caps	MIDI protocol capabilities;
			1: MIDI 1.0, 2: MIDI 2.0, or 3: both protocols
	protocol	Default MIDI protocol (either 1 or 2)
	ep_name		UMP Endpoint name string
	product_id	Product ID string
	manufacturer	Manufacture ID number (24 bit)
	family		Device family ID number (16 bit)
	model		Device model ID number (16 bit)
	sw_revision	Software revision (32 bit)
	=============	=================================================

Each Endpoint subdirectory contains a subdirectory "block.0", which
represents the Function Block for Block 0 information.
Its attributes are:

	=================	===============================================
	name			Function Block name string
	direction		Direction of this FB
				1: input, 2: output, or 3: bidirectional
	first_group		The first UMP Group number (0-15)
	num_groups		The number of groups in this FB (1-16)
	midi1_first_group	The first UMP Group number for MIDI 1.0 (0-15)
	midi1_num_groups	The number of groups for MIDI 1.0 (0-16)
	ui_hint			UI-hint of this FB
				0: unknown, 1: receiver, 2: sender, 3: both
	midi_ci_version		Supported MIDI-CI version number (8 bit)
	is_midi1		Legacy MIDI 1.0 device (0-2)
				0: MIDI 2.0 device,
				1: MIDI 1.0 without restriction, or
				2: MIDI 1.0 with low speed
	sysex8_streams		Max number of SysEx8 streams (8 bit)
	active			Bool flag for FB activity (0 or 1)
	=================	===============================================

If multiple Function Blocks are required, you can add more Function
Blocks by creating subdirectories "block.<num>" with the corresponding
Function Block number (1, 2, ....). The FB subdirectories can be
dynamically removed, too. Note that the Function Block numbers must be
continuous.

Similarly, if you multiple UMP Endpoints are required, you can add
more Endpoints by creating subdirectories "ep.<num>". The number must
be continuous.

For emulating the old MIDI 2.0 device without UMP v1.1 support, pass 0
to `process_ump` flag. Then the whole UMP v1.1 requests are ignored.

Testing the MIDI2 function
--------------------------

On the device: run the gadget, and running::

  $ cat /proc/asound/cards

will show a new sound card containing a MIDI2 device.

OTOH, on the host::

  $ cat /proc/asound/cards

will show a new sound card containing either MIDI1 or MIDI2 device,
depending on the USB audio driver configuration.

On both, when ALSA sequencer is enabled on the host, you can find the
UMP MIDI client such as "MIDI 2.0 Gadget".

As the driver simply loops back the data, there is no need for a real
device just for testing.

For testing a MIDI input from the gadget to the host (e.g. emulating a
MIDI keyboard), you can send a MIDI stream like the following.

On the gadget::

  $ aconnect -o
  ....
  client 20: 'MIDI 2.0 Gadget' [type=kernel,card=1]
      0 'MIDI 2.0        '
      1 'Group 1 (MIDI 2.0 Gadget I/O)'
  $ aplaymidi -p 20:1 to_host.mid

On the host::

  $ aconnect -i
  ....
  client 24: 'MIDI 2.0 Gadget' [type=kernel,card=2]
      0 'MIDI 2.0        '
      1 'Group 1 (MIDI 2.0 Gadget I/O)'
  $ arecordmidi -p 24:1 from_gadget.mid

If you have a UMP-capable application, you can use the UMP port to
send/receive the raw UMP packets, too. For example, aseqdump program
with UMP support can receive from UMP port. On the host::

  $ aseqdump -u 2 -p 24:1
  Waiting for data. Press Ctrl+C to end.
  Source  Group    Event                  Ch  Data
   24:1   Group  0, Program change          0, program 0, Bank select 0:0
   24:1   Group  0, Channel pressure        0, value 0x80000000

For testing a MIDI output to the gadget to the host (e.g. emulating a
MIDI synth), it'll be just other way round.

On the gadget::

  $ arecordmidi -p 20:1 from_host.mid

On the host::

  $ aplaymidi -p 24:1 to_gadget.mid

The access to MIDI 1.0 on altset 0 on the host is supported, and it's
translated from/to UMP packets on the gadget. It's bound to only
Function Block 0.

The current operation mode can be observed in ALSA control element
"Operation Mode" for SND_CTL_IFACE_RAWMIDI.  For example::

  $ amixer -c1 contents
  numid=1,iface=RAWMIDI,name='Operation Mode'
    ; type=INTEGER,access=r--v----,values=1,min=0,max=2,step=0
    : values=2

where 0 = unused, 1 = MIDI 1.0 (altset 0), 2 = MIDI 2.0 (altset 1).
The example above shows it's running in 2, i.e. MIDI 2.0.