gadget-testing.rst

   1==============
   2Gadget Testing
   3==============
   4
   5This file summarizes information on basic testing of USB functions
   6provided by gadgets.
   7
   8.. contents
   9
  10   1. ACM function
  11   2. ECM function
  12   3. ECM subset function
  13   4. EEM function
  14   5. FFS function
  15   6. HID function
  16   7. LOOPBACK function
  17   8. MASS STORAGE function
  18   9. MIDI function
  19   10. NCM function
  20   11. OBEX function
  21   12. PHONET function
  22   13. RNDIS function
  23   14. SERIAL function
  24   15. SOURCESINK function
  25   16. UAC1 function (legacy implementation)
  26   17. UAC2 function
  27   18. UVC function
  28   19. PRINTER function
  29   20. UAC1 function (new API)
  30   21. MIDI2 function
  31
  32
  331. ACM function
  34===============
  35
  36The function is provided by usb_f_acm.ko module.
  37
  38Function-specific configfs interface
  39------------------------------------
  40
  41The function name to use when creating the function directory is "acm".
  42The ACM function provides just one attribute in its function directory:
  43
  44	port_num
  45
  46The attribute is read-only.
  47
  48There can be at most 4 ACM/generic serial/OBEX ports in the system.
  49
  50
  51Testing the ACM function
  52------------------------
  53
  54On the host::
  55
  56	cat > /dev/ttyACM<X>
  57
  58On the device::
  59
  60	cat /dev/ttyGS<Y>
  61
  62then the other way round
  63
  64On the device::
  65
  66	cat > /dev/ttyGS<Y>
  67
  68On the host::
  69
  70	cat /dev/ttyACM<X>
  71
  722. ECM function
  73===============
  74
  75The function is provided by usb_f_ecm.ko module.
  76
  77Function-specific configfs interface
  78------------------------------------
  79
  80The function name to use when creating the function directory is "ecm".
  81The ECM function provides these attributes in its function directory:
  82
  83	=============== ==================================================
  84	ifname		network device interface name associated with this
  85			function instance
  86	qmult		queue length multiplier for high and super speed
  87	host_addr	MAC address of host's end of this
  88			Ethernet over USB link
  89	dev_addr	MAC address of device's end of this
  90			Ethernet over USB link
  91	=============== ==================================================
  92
  93and after creating the functions/ecm.<instance name> they contain default
  94values: qmult is 5, dev_addr and host_addr are randomly selected.
  95The ifname can be written to if the function is not bound. A write must be an
  96interface pattern such as "usb%d", which will cause the net core to choose the
  97next free usbX interface. By default, it is set to "usb%d".
  98
  99Testing the ECM function
 100------------------------
 101
 102Configure IP addresses of the device and the host. Then:
 103
 104On the device::
 105
 106	ping <host's IP>
 107
 108On the host::
 109
 110	ping <device's IP>
 111
 1123. ECM subset function
 113======================
 114
 115The function is provided by usb_f_ecm_subset.ko module.
 116
 117Function-specific configfs interface
 118------------------------------------
 119
 120The function name to use when creating the function directory is "geth".
 121The ECM subset function provides these attributes in its function directory:
 122
 123	=============== ==================================================
 124	ifname		network device interface name associated with this
 125			function instance
 126	qmult		queue length multiplier for high and super speed
 127	host_addr	MAC address of host's end of this
 128			Ethernet over USB link
 129	dev_addr	MAC address of device's end of this
 130			Ethernet over USB link
 131	=============== ==================================================
 132
 133and after creating the functions/ecm.<instance name> they contain default
 134values: qmult is 5, dev_addr and host_addr are randomly selected.
 135The ifname can be written to if the function is not bound. A write must be an
 136interface pattern such as "usb%d", which will cause the net core to choose the
 137next free usbX interface. By default, it is set to "usb%d".
 138
 139Testing the ECM subset function
 140-------------------------------
 141
 142Configure IP addresses of the device and the host. Then:
 143
 144On the device::
 145
 146	ping <host's IP>
 147
 148On the host::
 149
 150	ping <device's IP>
 151
 1524. EEM function
 153===============
 154
 155The function is provided by usb_f_eem.ko module.
 156
 157Function-specific configfs interface
 158------------------------------------
 159
 160The function name to use when creating the function directory is "eem".
 161The EEM function provides these attributes in its function directory:
 162
 163	=============== ==================================================
 164	ifname		network device interface name associated with this
 165			function instance
 166	qmult		queue length multiplier for high and super speed
 167	host_addr	MAC address of host's end of this
 168			Ethernet over USB link
 169	dev_addr	MAC address of device's end of this
 170			Ethernet over USB link
 171	=============== ==================================================
 172
 173and after creating the functions/eem.<instance name> they contain default
 174values: qmult is 5, dev_addr and host_addr are randomly selected.
 175The ifname can be written to if the function is not bound. A write must be an
 176interface pattern such as "usb%d", which will cause the net core to choose the
 177next free usbX interface. By default, it is set to "usb%d".
 178
 179Testing the EEM function
 180------------------------
 181
 182Configure IP addresses of the device and the host. Then:
 183
 184On the device::
 185
 186	ping <host's IP>
 187
 188On the host::
 189
 190	ping <device's IP>
 191
 1925. FFS function
 193===============
 194
 195The function is provided by usb_f_fs.ko module.
 196
 197Function-specific configfs interface
 198------------------------------------
 199
 200The function name to use when creating the function directory is "ffs".
 201The function directory is intentionally empty and not modifiable.
 202
 203After creating the directory there is a new instance (a "device") of FunctionFS
 204available in the system. Once a "device" is available, the user should follow
 205the standard procedure for using FunctionFS (mount it, run the userspace
 206process which implements the function proper). The gadget should be enabled
 207by writing a suitable string to usb_gadget/<gadget>/UDC.
 208
 209The FFS function provides just one attribute in its function directory:
 210
 211	ready
 212
 213The attribute is read-only and signals if the function is ready (1) to be
 214used, E.G. if userspace has written descriptors and strings to ep0, so
 215the gadget can be enabled.
 216
 217Testing the FFS function
 218------------------------
 219
 220On the device: start the function's userspace daemon, enable the gadget
 221
 222On the host: use the USB function provided by the device
 223
 2246. HID function
 225===============
 226
 227The function is provided by usb_f_hid.ko module.
 228
 229Function-specific configfs interface
 230------------------------------------
 231
 232The function name to use when creating the function directory is "hid".
 233The HID function provides these attributes in its function directory:
 234
 235	=============== ===========================================
 236	protocol	HID protocol to use
 237	report_desc	data to be used in HID reports, except data
 238			passed with /dev/hidg<X>
 239	report_length	HID report length
 240	subclass	HID subclass to use
 241	=============== ===========================================
 242
 243For a keyboard the protocol and the subclass are 1, the report_length is 8,
 244while the report_desc is::
 245
 246  $ hd my_report_desc
 247  00000000  05 01 09 06 a1 01 05 07  19 e0 29 e7 15 00 25 01  |..........)...%.|
 248  00000010  75 01 95 08 81 02 95 01  75 08 81 03 95 05 75 01  |u.......u.....u.|
 249  00000020  05 08 19 01 29 05 91 02  95 01 75 03 91 03 95 06  |....).....u.....|
 250  00000030  75 08 15 00 25 65 05 07  19 00 29 65 81 00 c0     |u...%e....)e...|
 251  0000003f
 252
 253Such a sequence of bytes can be stored to the attribute with echo::
 254
 255  $ echo -ne \\x05\\x01\\x09\\x06\\xa1.....
 256
 257Testing the HID function
 258------------------------
 259
 260Device:
 261
 262- create the gadget
 263- connect the gadget to a host, preferably not the one used
 264  to control the gadget
 265- run a program which writes to /dev/hidg<N>, e.g.
 266  a userspace program found in Documentation/usb/gadget_hid.rst::
 267
 268	$ ./hid_gadget_test /dev/hidg0 keyboard
 269
 270Host:
 271
 272- observe the keystrokes from the gadget
 273
 2747. LOOPBACK function
 275====================
 276
 277The function is provided by usb_f_ss_lb.ko module.
 278
 279Function-specific configfs interface
 280------------------------------------
 281
 282The function name to use when creating the function directory is "Loopback".
 283The LOOPBACK function provides these attributes in its function directory:
 284
 285	=============== =======================
 286	qlen		depth of loopback queue
 287	bulk_buflen	buffer length
 288	=============== =======================
 289
 290Testing the LOOPBACK function
 291-----------------------------
 292
 293device: run the gadget
 294
 295host: test-usb (tools/usb/testusb.c)
 296
 2978. MASS STORAGE function
 298========================
 299
 300The function is provided by usb_f_mass_storage.ko module.
 301
 302Function-specific configfs interface
 303------------------------------------
 304
 305The function name to use when creating the function directory is "mass_storage".
 306The MASS STORAGE function provides these attributes in its directory:
 307files:
 308
 309	=============== ==============================================
 310	stall		Set to permit function to halt bulk endpoints.
 311			Disabled on some USB devices known not to work
 312			correctly. You should set it to true.
 313	num_buffers	Number of pipeline buffers. Valid numbers
 314			are 2..4. Available only if
 315			CONFIG_USB_GADGET_DEBUG_FILES is set.
 316	=============== ==============================================
 317
 318and a default lun.0 directory corresponding to SCSI LUN #0.
 319
 320A new lun can be added with mkdir::
 321
 322	$ mkdir functions/mass_storage.0/partition.5
 323
 324Lun numbering does not have to be continuous, except for lun #0 which is
 325created by default. A maximum of 8 luns can be specified and they all must be
 326named following the <name>.<number> scheme. The numbers can be 0..8.
 327Probably a good convention is to name the luns "lun.<number>",
 328although it is not mandatory.
 329
 330In each lun directory there are the following attribute files:
 331
 332	=============== ==============================================
 333	file		The path to the backing file for the LUN.
 334			Required if LUN is not marked as removable.
 335	ro		Flag specifying access to the LUN shall be
 336			read-only. This is implied if CD-ROM emulation
 337			is enabled as well as when it was impossible
 338			to open "filename" in R/W mode.
 339	removable	Flag specifying that LUN shall be indicated as
 340			being removable.
 341	cdrom		Flag specifying that LUN shall be reported as
 342			being a CD-ROM.
 343	nofua		Flag specifying that FUA flag
 344			in SCSI WRITE(10,12)
 345	forced_eject	This write-only file is useful only when
 346			the function is active. It causes the backing
 347			file to be forcibly detached from the LUN,
 348			regardless of whether the host has allowed it.
 349			Any non-zero number of bytes written will
 350			result in ejection.
 351	=============== ==============================================
 352
 353Testing the MASS STORAGE function
 354---------------------------------
 355
 356device: connect the gadget, enable it
 357host: dmesg, see the USB drives appear (if system configured to automatically
 358mount)
 359
 3609. MIDI function
 361================
 362
 363The function is provided by usb_f_midi.ko module.
 364
 365Function-specific configfs interface
 366------------------------------------
 367
 368The function name to use when creating the function directory is "midi".
 369The MIDI function provides these attributes in its function directory:
 370
 371	=============== ====================================
 372	buflen		MIDI buffer length
 373	id		ID string for the USB MIDI adapter
 374	in_ports	number of MIDI input ports
 375	index		index value for the USB MIDI adapter
 376	out_ports	number of MIDI output ports
 377	qlen		USB read request queue length
 378	=============== ====================================
 379
 380Testing the MIDI function
 381-------------------------
 382
 383There are two cases: playing a mid from the gadget to
 384the host and playing a mid from the host to the gadget.
 385
 3861) Playing a mid from the gadget to the host:
 387
 388host::
 389
 390  $ arecordmidi -l
 391   Port    Client name                      Port name
 392   14:0    Midi Through                     Midi Through Port-0
 393   24:0    MIDI Gadget                      MIDI Gadget MIDI 1
 394  $ arecordmidi -p 24:0 from_gadget.mid
 395
 396gadget::
 397
 398  $ aplaymidi -l
 399   Port    Client name                      Port name
 400   20:0    f_midi                           f_midi
 401
 402  $ aplaymidi -p 20:0 to_host.mid
 403
 4042) Playing a mid from the host to the gadget
 405
 406gadget::
 407
 408  $ arecordmidi -l
 409   Port    Client name                      Port name
 410   20:0    f_midi                           f_midi
 411
 412  $ arecordmidi -p 20:0 from_host.mid
 413
 414host::
 415
 416  $ aplaymidi -l
 417   Port    Client name                      Port name
 418   14:0    Midi Through                     Midi Through Port-0
 419   24:0    MIDI Gadget                      MIDI Gadget MIDI 1
 420
 421  $ aplaymidi -p24:0 to_gadget.mid
 422
 423The from_gadget.mid should sound identical to the to_host.mid.
 424
 425The from_host.id should sound identical to the to_gadget.mid.
 426
 427MIDI files can be played to speakers/headphones with e.g. timidity installed::
 428
 429  $ aplaymidi -l
 430   Port    Client name                      Port name
 431   14:0    Midi Through                     Midi Through Port-0
 432   24:0    MIDI Gadget                      MIDI Gadget MIDI 1
 433  128:0    TiMidity                         TiMidity port 0
 434  128:1    TiMidity                         TiMidity port 1
 435  128:2    TiMidity                         TiMidity port 2
 436  128:3    TiMidity                         TiMidity port 3
 437
 438  $ aplaymidi -p 128:0 file.mid
 439
 440MIDI ports can be logically connected using the aconnect utility, e.g.::
 441
 442  $ aconnect 24:0 128:0 # try it on the host
 443
 444After the gadget's MIDI port is connected to timidity's MIDI port,
 445whatever is played at the gadget side with aplaymidi -l is audible
 446in host's speakers/headphones.
 447
 44810. NCM function
 449================
 450
 451The function is provided by usb_f_ncm.ko module.
 452
 453Function-specific configfs interface
 454------------------------------------
 455
 456The function name to use when creating the function directory is "ncm".
 457The NCM function provides these attributes in its function directory:
 458
 459	======================= ==================================================
 460	ifname			network device interface name associated with this
 461				function instance
 462	qmult			queue length multiplier for high and super speed
 463	host_addr		MAC address of host's end of this
 464				Ethernet over USB link
 465	dev_addr		MAC address of device's end of this
 466				Ethernet over USB link
 467	max_segment_size	Segment size required for P2P connections. This
 468				will set MTU to 14 bytes
 469	======================= ==================================================
 470
 471and after creating the functions/ncm.<instance name> they contain default
 472values: qmult is 5, dev_addr and host_addr are randomly selected.
 473The ifname can be written to if the function is not bound. A write must be an
 474interface pattern such as "usb%d", which will cause the net core to choose the
 475next free usbX interface. By default, it is set to "usb%d".
 476
 477Testing the NCM function
 478------------------------
 479
 480Configure IP addresses of the device and the host. Then:
 481
 482On the device::
 483
 484	ping <host's IP>
 485
 486On the host::
 487
 488	ping <device's IP>
 489
 49011. OBEX function
 491=================
 492
 493The function is provided by usb_f_obex.ko module.
 494
 495Function-specific configfs interface
 496------------------------------------
 497
 498The function name to use when creating the function directory is "obex".
 499The OBEX function provides just one attribute in its function directory:
 500
 501	port_num
 502
 503The attribute is read-only.
 504
 505There can be at most 4 ACM/generic serial/OBEX ports in the system.
 506
 507Testing the OBEX function
 508-------------------------
 509
 510On device::
 511
 512	seriald -f /dev/ttyGS<Y> -s 1024
 513
 514On host::
 515
 516	serialc -v <vendorID> -p <productID> -i<interface#> -a1 -s1024 \
 517                -t<out endpoint addr> -r<in endpoint addr>
 518
 519where seriald and serialc are Felipe's utilities found here:
 520
 521	https://github.com/felipebalbi/usb-tools.git master
 522
 52312. PHONET function
 524===================
 525
 526The function is provided by usb_f_phonet.ko module.
 527
 528Function-specific configfs interface
 529------------------------------------
 530
 531The function name to use when creating the function directory is "phonet".
 532The PHONET function provides just one attribute in its function directory:
 533
 534	=============== ==================================================
 535	ifname		network device interface name associated with this
 536			function instance
 537	=============== ==================================================
 538
 539Testing the PHONET function
 540---------------------------
 541
 542It is not possible to test the SOCK_STREAM protocol without a specific piece
 543of hardware, so only SOCK_DGRAM has been tested. For the latter to work,
 544in the past I had to apply the patch mentioned here:
 545
 546http://www.spinics.net/lists/linux-usb/msg85689.html
 547
 548These tools are required:
 549
 550git://git.gitorious.org/meego-cellular/phonet-utils.git
 551
 552On the host::
 553
 554	$ ./phonet -a 0x10 -i usbpn0
 555	$ ./pnroute add 0x6c usbpn0
 556	$./pnroute add 0x10 usbpn0
 557	$ ifconfig usbpn0 up
 558
 559On the device::
 560
 561	$ ./phonet -a 0x6c -i upnlink0
 562	$ ./pnroute add 0x10 upnlink0
 563	$ ifconfig upnlink0 up
 564
 565Then a test program can be used::
 566
 567	http://www.spinics.net/lists/linux-usb/msg85690.html
 568
 569On the device::
 570
 571	$ ./pnxmit -a 0x6c -r
 572
 573On the host::
 574
 575	$ ./pnxmit -a 0x10 -s 0x6c
 576
 577As a result some data should be sent from host to device.
 578Then the other way round:
 579
 580On the host::
 581
 582	$ ./pnxmit -a 0x10 -r
 583
 584On the device::
 585
 586	$ ./pnxmit -a 0x6c -s 0x10
 587
 58813. RNDIS function
 589==================
 590
 591The function is provided by usb_f_rndis.ko module.
 592
 593Function-specific configfs interface
 594------------------------------------
 595
 596The function name to use when creating the function directory is "rndis".
 597The RNDIS function provides these attributes in its function directory:
 598
 599	=============== ==================================================
 600	ifname		network device interface name associated with this
 601			function instance
 602	qmult		queue length multiplier for high and super speed
 603	host_addr	MAC address of host's end of this
 604			Ethernet over USB link
 605	dev_addr	MAC address of device's end of this
 606			Ethernet over USB link
 607	=============== ==================================================
 608
 609and after creating the functions/rndis.<instance name> they contain default
 610values: qmult is 5, dev_addr and host_addr are randomly selected.
 611The ifname can be written to if the function is not bound. A write must be an
 612interface pattern such as "usb%d", which will cause the net core to choose the
 613next free usbX interface. By default, it is set to "usb%d".
 614
 615Testing the RNDIS function
 616--------------------------
 617
 618Configure IP addresses of the device and the host. Then:
 619
 620On the device::
 621
 622	ping <host's IP>
 623
 624On the host::
 625
 626	ping <device's IP>
 627
 62814. SERIAL function
 629===================
 630
 631The function is provided by usb_f_gser.ko module.
 632
 633Function-specific configfs interface
 634------------------------------------
 635
 636The function name to use when creating the function directory is "gser".
 637The SERIAL function provides just one attribute in its function directory:
 638
 639	port_num
 640
 641The attribute is read-only.
 642
 643There can be at most 4 ACM/generic serial/OBEX ports in the system.
 644
 645Testing the SERIAL function
 646---------------------------
 647
 648On host::
 649
 650	insmod usbserial
 651	echo VID PID >/sys/bus/usb-serial/drivers/generic/new_id
 652
 653On host::
 654
 655	cat > /dev/ttyUSB<X>
 656
 657On target::
 658
 659	cat /dev/ttyGS<Y>
 660
 661then the other way round
 662
 663On target::
 664
 665	cat > /dev/ttyGS<Y>
 666
 667On host::
 668
 669	cat /dev/ttyUSB<X>
 670
 67115. SOURCESINK function
 672=======================
 673
 674The function is provided by usb_f_ss_lb.ko module.
 675
 676Function-specific configfs interface
 677------------------------------------
 678
 679The function name to use when creating the function directory is "SourceSink".
 680The SOURCESINK function provides these attributes in its function directory:
 681
 682	=============== ==================================
 683	pattern		0 (all zeros), 1 (mod63), 2 (none)
 684	isoc_interval	1..16
 685	isoc_maxpacket	0 - 1023 (fs), 0 - 1024 (hs/ss)
 686	isoc_mult	0..2 (hs/ss only)
 687	isoc_maxburst	0..15 (ss only)
 688	bulk_buflen	buffer length
 689	bulk_qlen	depth of queue for bulk
 690	iso_qlen	depth of queue for iso
 691	=============== ==================================
 692
 693Testing the SOURCESINK function
 694-------------------------------
 695
 696device: run the gadget
 697
 698host: test-usb (tools/usb/testusb.c)
 699
 700
 70116. UAC1 function (legacy implementation)
 702=========================================
 703
 704The function is provided by usb_f_uac1_legacy.ko module.
 705
 706Function-specific configfs interface
 707------------------------------------
 708
 709The function name to use when creating the function directory
 710is "uac1_legacy".
 711The uac1 function provides these attributes in its function directory:
 712
 713	=============== ====================================
 714	audio_buf_size	audio buffer size
 715	fn_cap		capture pcm device file name
 716	fn_cntl		control device file name
 717	fn_play		playback pcm device file name
 718	req_buf_size	ISO OUT endpoint request buffer size
 719	req_count	ISO OUT endpoint request count
 720	=============== ====================================
 721
 722The attributes have sane default values.
 723
 724Testing the UAC1 function
 725-------------------------
 726
 727device: run the gadget
 728
 729host::
 730
 731	aplay -l # should list our USB Audio Gadget
 732
 73317. UAC2 function
 734=================
 735
 736The function is provided by usb_f_uac2.ko module.
 737
 738Function-specific configfs interface
 739------------------------------------
 740
 741The function name to use when creating the function directory is "uac2".
 742The uac2 function provides these attributes in its function directory:
 743
 744	================ ====================================================
 745	c_chmask         capture channel mask
 746	c_srate          list of capture sampling rates (comma-separated)
 747	c_ssize          capture sample size (bytes)
 748	c_sync           capture synchronization type (async/adaptive)
 749	c_mute_present   capture mute control enable
 750	c_volume_present capture volume control enable
 751	c_volume_min     capture volume control min value (in 1/256 dB)
 752	c_volume_max     capture volume control max value (in 1/256 dB)
 753	c_volume_res     capture volume control resolution (in 1/256 dB)
 754	c_hs_bint        capture bInterval for HS/SS (1-4: fixed, 0: auto)
 755	fb_max           maximum extra bandwidth in async mode
 756	p_chmask         playback channel mask
 757	p_srate          list of playback sampling rates (comma-separated)
 758	p_ssize          playback sample size (bytes)
 759	p_mute_present   playback mute control enable
 760	p_volume_present playback volume control enable
 761	p_volume_min     playback volume control min value (in 1/256 dB)
 762	p_volume_max     playback volume control max value (in 1/256 dB)
 763	p_volume_res     playback volume control resolution (in 1/256 dB)
 764	p_hs_bint        playback bInterval for HS/SS (1-4: fixed, 0: auto)
 765	req_number       the number of pre-allocated request for both capture
 766	                 and playback
 767	function_name    name of the interface
 768	if_ctrl_name     topology control name
 769	clksrc_in_name   input clock name
 770	clksrc_out_name  output clock name
 771	p_it_name        playback input terminal name
 772	p_it_ch_name     playback input first channel name
 773	p_ot_name        playback output terminal name
 774	p_fu_vol_name    playback function unit name
 775	c_it_name        capture input terminal name
 776	c_it_ch_name     capture input first channel name
 777	c_ot_name        capture output terminal name
 778	c_fu_vol_name    capture functional unit name
 779	c_terminal_type  code of the capture terminal type
 780	p_terminal_type  code of the playback terminal type
 781	================ ====================================================
 782
 783The attributes have sane default values.
 784
 785Testing the UAC2 function
 786-------------------------
 787
 788device: run the gadget
 789host: aplay -l # should list our USB Audio Gadget
 790
 791This function does not require real hardware support, it just
 792sends a stream of audio data to/from the host. In order to
 793actually hear something at the device side, a command similar
 794to this must be used at the device side::
 795
 796	$ arecord -f dat -t wav -D hw:2,0 | aplay -D hw:0,0 &
 797
 798e.g.::
 799
 800	$ arecord -f dat -t wav -D hw:CARD=UAC2Gadget,DEV=0 | \
 801	  aplay -D default:CARD=OdroidU3
 802
 80318. UVC function
 804================
 805
 806The function is provided by usb_f_uvc.ko module.
 807
 808Function-specific configfs interface
 809------------------------------------
 810
 811The function name to use when creating the function directory is "uvc".
 812The uvc function provides these attributes in its function directory:
 813
 814	=================== ================================================
 815	streaming_interval  interval for polling endpoint for data transfers
 816	streaming_maxburst  bMaxBurst for super speed companion descriptor
 817	streaming_maxpacket maximum packet size this endpoint is capable of
 818			    sending or receiving when this configuration is
 819			    selected
 820	function_name       name of the interface
 821	=================== ================================================
 822
 823There are also "control" and "streaming" subdirectories, each of which contain
 824a number of their subdirectories. There are some sane defaults provided, but
 825the user must provide the following:
 826
 827	================== ====================================================
 828	control header     create in control/header, link from control/class/fs
 829			   and/or control/class/ss
 830	streaming header   create in streaming/header, link from
 831			   streaming/class/fs and/or streaming/class/hs and/or
 832			   streaming/class/ss
 833	format description create in streaming/mjpeg and/or
 834			   streaming/uncompressed
 835	frame description  create in streaming/mjpeg/<format> and/or in
 836			   streaming/uncompressed/<format>
 837	================== ====================================================
 838
 839Each frame description contains frame interval specification, and each
 840such specification consists of a number of lines with an interval value
 841in each line. The rules stated above are best illustrated with an example::
 842
 843  # mkdir functions/uvc.usb0/control/header/h
 844  # cd functions/uvc.usb0/control/
 845  # ln -s header/h class/fs
 846  # ln -s header/h class/ss
 847  # mkdir -p functions/uvc.usb0/streaming/uncompressed/u/360p
 848  # cat <<EOF > functions/uvc.usb0/streaming/uncompressed/u/360p/dwFrameInterval
 849  666666
 850  1000000
 851  5000000
 852  EOF
 853  # cd $GADGET_CONFIGFS_ROOT
 854  # mkdir functions/uvc.usb0/streaming/header/h
 855  # cd functions/uvc.usb0/streaming/header/h
 856  # ln -s ../../uncompressed/u
 857  # cd ../../class/fs
 858  # ln -s ../../header/h
 859  # cd ../../class/hs
 860  # ln -s ../../header/h
 861  # cd ../../class/ss
 862  # ln -s ../../header/h
 863
 864
 865Testing the UVC function
 866------------------------
 867
 868device: run the gadget, modprobe vivid::
 869
 870  # uvc-gadget -u /dev/video<uvc video node #> -v /dev/video<vivid video node #>
 871
 872where uvc-gadget is this program:
 873	http://git.ideasonboard.org/uvc-gadget.git
 874
 875with these patches:
 876
 877	https://lore.kernel.org/r/1386675637-18243-1-git-send-email-r.baldyga@samsung.com/
 878
 879host::
 880
 881	luvcview -f yuv
 882
 88319. PRINTER function
 884====================
 885
 886The function is provided by usb_f_printer.ko module.
 887
 888Function-specific configfs interface
 889------------------------------------
 890
 891The function name to use when creating the function directory is "printer".
 892The printer function provides these attributes in its function directory:
 893
 894	==========	===========================================
 895	pnp_string	Data to be passed to the host in pnp string
 896	q_len		Number of requests per endpoint
 897	==========	===========================================
 898
 899Testing the PRINTER function
 900----------------------------
 901
 902The most basic testing:
 903
 904device: run the gadget::
 905
 906	# ls -l /devices/virtual/usb_printer_gadget/
 907
 908should show g_printer<number>.
 909
 910If udev is active, then /dev/g_printer<number> should appear automatically.
 911
 912host:
 913
 914If udev is active, then e.g. /dev/usb/lp0 should appear.
 915
 916host->device transmission:
 917
 918device::
 919
 920	# cat /dev/g_printer<number>
 921
 922host::
 923
 924	# cat > /dev/usb/lp0
 925
 926device->host transmission::
 927
 928	# cat > /dev/g_printer<number>
 929
 930host::
 931
 932	# cat /dev/usb/lp0
 933
 934More advanced testing can be done with the prn_example
 935described in Documentation/usb/gadget_printer.rst.
 936
 937
 93820. UAC1 function (virtual ALSA card, using u_audio API)
 939========================================================
 940
 941The function is provided by usb_f_uac1.ko module.
 942It will create a virtual ALSA card and the audio streams are simply
 943sinked to and sourced from it.
 944
 945Function-specific configfs interface
 946------------------------------------
 947
 948The function name to use when creating the function directory is "uac1".
 949The uac1 function provides these attributes in its function directory:
 950
 951	================ ====================================================
 952	c_chmask         capture channel mask
 953	c_srate          list of capture sampling rates (comma-separated)
 954	c_ssize          capture sample size (bytes)
 955	c_mute_present   capture mute control enable
 956	c_volume_present capture volume control enable
 957	c_volume_min     capture volume control min value (in 1/256 dB)
 958	c_volume_max     capture volume control max value (in 1/256 dB)
 959	c_volume_res     capture volume control resolution (in 1/256 dB)
 960	p_chmask         playback channel mask
 961	p_srate          list of playback sampling rates (comma-separated)
 962	p_ssize          playback sample size (bytes)
 963	p_mute_present   playback mute control enable
 964	p_volume_present playback volume control enable
 965	p_volume_min     playback volume control min value (in 1/256 dB)
 966	p_volume_max     playback volume control max value (in 1/256 dB)
 967	p_volume_res     playback volume control resolution (in 1/256 dB)
 968	req_number       the number of pre-allocated requests for both capture
 969	                 and playback
 970	function_name    name of the interface
 971	p_it_name        playback input terminal name
 972	p_it_ch_name     playback channels name
 973	p_ot_name        playback output terminal name
 974	p_fu_vol_name    playback mute/volume functional unit name
 975	c_it_name        capture input terminal name
 976	c_it_ch_name     capture channels name
 977	c_ot_name        capture output terminal name
 978	c_fu_vol_name    capture mute/volume functional unit name
 979	================ ====================================================
 980
 981The attributes have sane default values.
 982
 983Testing the UAC1 function
 984-------------------------
 985
 986device: run the gadget
 987host: aplay -l # should list our USB Audio Gadget
 988
 989This function does not require real hardware support, it just
 990sends a stream of audio data to/from the host. In order to
 991actually hear something at the device side, a command similar
 992to this must be used at the device side::
 993
 994	$ arecord -f dat -t wav -D hw:2,0 | aplay -D hw:0,0 &
 995
 996e.g.::
 997
 998	$ arecord -f dat -t wav -D hw:CARD=UAC1Gadget,DEV=0 | \
 999	  aplay -D default:CARD=OdroidU3
1000
1001
100221. MIDI2 function
1003==================
1004
1005The function is provided by usb_f_midi2.ko module.
1006It will create a virtual ALSA card containing a UMP rawmidi device
1007where the UMP packet is looped back. In addition, a legacy rawmidi
1008device is created. The UMP rawmidi is bound with ALSA sequencer
1009clients, too.
1010
1011Function-specific configfs interface
1012------------------------------------
1013
1014The function name to use when creating the function directory is "midi2".
1015The midi2 function provides these attributes in its function directory
1016as the card top-level information:
1017
1018	=============	=================================================
1019	process_ump	Bool flag to process UMP Stream messages (0 or 1)
1020	static_block	Bool flag for static blocks (0 or 1)
1021	iface_name	Optional interface name string
1022	=============	=================================================
1023
1024The directory contains a subdirectory "ep.0", and this provides the
1025attributes for a UMP Endpoint (which is a pair of USB MIDI Endpoints):
1026
1027	=============	=================================================
1028	protocol_caps	MIDI protocol capabilities;
1029			1: MIDI 1.0, 2: MIDI 2.0, or 3: both protocols
1030	protocol	Default MIDI protocol (either 1 or 2)
1031	ep_name		UMP Endpoint name string
1032	product_id	Product ID string
1033	manufacturer	Manufacture ID number (24 bit)
1034	family		Device family ID number (16 bit)
1035	model		Device model ID number (16 bit)
1036	sw_revision	Software revision (32 bit)
1037	=============	=================================================
1038
1039Each Endpoint subdirectory contains a subdirectory "block.0", which
1040represents the Function Block for Block 0 information.
1041Its attributes are:
1042
1043	=================	===============================================
1044	name			Function Block name string
1045	direction		Direction of this FB
1046				1: input, 2: output, or 3: bidirectional
1047	first_group		The first UMP Group number (0-15)
1048	num_groups		The number of groups in this FB (1-16)
1049	midi1_first_group	The first UMP Group number for MIDI 1.0 (0-15)
1050	midi1_num_groups	The number of groups for MIDI 1.0 (0-16)
1051	ui_hint			UI-hint of this FB
1052				0: unknown, 1: receiver, 2: sender, 3: both
1053	midi_ci_version		Supported MIDI-CI version number (8 bit)
1054	is_midi1		Legacy MIDI 1.0 device (0-2)
1055				0: MIDI 2.0 device,
1056				1: MIDI 1.0 without restriction, or
1057				2: MIDI 1.0 with low speed
1058	sysex8_streams		Max number of SysEx8 streams (8 bit)
1059	active			Bool flag for FB activity (0 or 1)
1060	=================	===============================================
1061
1062If multiple Function Blocks are required, you can add more Function
1063Blocks by creating subdirectories "block.<num>" with the corresponding
1064Function Block number (1, 2, ....). The FB subdirectories can be
1065dynamically removed, too. Note that the Function Block numbers must be
1066continuous.
1067
1068Similarly, if you multiple UMP Endpoints are required, you can add
1069more Endpoints by creating subdirectories "ep.<num>". The number must
1070be continuous.
1071
1072For emulating the old MIDI 2.0 device without UMP v1.1 support, pass 0
1073to `process_ump` flag. Then the whole UMP v1.1 requests are ignored.
1074
1075Testing the MIDI2 function
1076--------------------------
1077
1078On the device: run the gadget, and running::
1079
1080  $ cat /proc/asound/cards
1081
1082will show a new sound card containing a MIDI2 device.
1083
1084OTOH, on the host::
1085
1086  $ cat /proc/asound/cards
1087
1088will show a new sound card containing either MIDI1 or MIDI2 device,
1089depending on the USB audio driver configuration.
1090
1091On both, when ALSA sequencer is enabled on the host, you can find the
1092UMP MIDI client such as "MIDI 2.0 Gadget".
1093
1094As the driver simply loops back the data, there is no need for a real
1095device just for testing.
1096
1097For testing a MIDI input from the gadget to the host (e.g. emulating a
1098MIDI keyboard), you can send a MIDI stream like the following.
1099
1100On the gadget::
1101
1102  $ aconnect -o
1103  ....
1104  client 20: 'MIDI 2.0 Gadget' [type=kernel,card=1]
1105      0 'MIDI 2.0        '
1106      1 'Group 1 (MIDI 2.0 Gadget I/O)'
1107  $ aplaymidi -p 20:1 to_host.mid
1108
1109On the host::
1110
1111  $ aconnect -i
1112  ....
1113  client 24: 'MIDI 2.0 Gadget' [type=kernel,card=2]
1114      0 'MIDI 2.0        '
1115      1 'Group 1 (MIDI 2.0 Gadget I/O)'
1116  $ arecordmidi -p 24:1 from_gadget.mid
1117
1118If you have a UMP-capable application, you can use the UMP port to
1119send/receive the raw UMP packets, too. For example, aseqdump program
1120with UMP support can receive from UMP port. On the host::
1121
1122  $ aseqdump -u 2 -p 24:1
1123  Waiting for data. Press Ctrl+C to end.
1124  Source  Group    Event                  Ch  Data
1125   24:1   Group  0, Program change          0, program 0, Bank select 0:0
1126   24:1   Group  0, Channel pressure        0, value 0x80000000
1127
1128For testing a MIDI output to the gadget to the host (e.g. emulating a
1129MIDI synth), it'll be just other way round.
1130
1131On the gadget::
1132
1133  $ arecordmidi -p 20:1 from_host.mid
1134
1135On the host::
1136
1137  $ aplaymidi -p 24:1 to_gadget.mid
1138
1139The access to MIDI 1.0 on altset 0 on the host is supported, and it's
1140translated from/to UMP packets on the gadget. It's bound to only
1141Function Block 0.
1142
1143The current operation mode can be observed in ALSA control element
1144"Operation Mode" for SND_CTL_IFACE_RAWMIDI.  For example::
1145
1146  $ amixer -c1 contents
1147  numid=1,iface=RAWMIDI,name='Operation Mode'
1148    ; type=INTEGER,access=r--v----,values=1,min=0,max=2,step=0
1149    : values=2
1150
1151where 0 = unused, 1 = MIDI 1.0 (altset 0), 2 = MIDI 2.0 (altset 1).
1152The example above shows it's running in 2, i.e. MIDI 2.0.