Orange Pi5 kernel

^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   1) ==============================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   2) Multifunction Composite Gadget
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   3) ==============================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   4) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   5) Overview
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   6) ========
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   7) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   8) The Multifunction Composite Gadget (or g_multi) is a composite gadget
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   9) that makes extensive use of the composite framework to provide
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  10) a... multifunction gadget.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  11) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  12) In it's standard configuration it provides a single USB configuration
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  13) with RNDIS[1] (that is Ethernet), USB CDC[2] ACM (that is serial) and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  14) USB Mass Storage functions.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  15) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  16) A CDC ECM (Ethernet) function may be turned on via a Kconfig option
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  17) and RNDIS can be turned off.  If they are both enabled the gadget will
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  18) have two configurations -- one with RNDIS and another with CDC ECM[3].
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  19) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  20) Please note that if you use non-standard configuration (that is enable
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  21) CDC ECM) you may need to change vendor and/or product ID.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  22) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  23) Host drivers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  24) ============
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  25) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  26) To make use of the gadget one needs to make it work on host side --
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  27) without that there's no hope of achieving anything with the gadget.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  28) As one might expect, things one need to do very from system to system.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  29) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  30) Linux host drivers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  31) ------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  32) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  33) Since the gadget uses standard composite framework and appears as such
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  34) to Linux host it does not need any additional drivers on Linux host
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  35) side.  All the functions are handled by respective drivers developed
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  36) for them.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  37) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  38) This is also true for two configuration set-up with RNDIS
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  39) configuration being the first one.  Linux host will use the second
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  40) configuration with CDC ECM which should work better under Linux.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  41) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  42) Windows host drivers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  43) --------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  44) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  45) For the gadget to work under Windows two conditions have to be met:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  46) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  47) Detecting as composite gadget
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  48) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  49) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  50) First of all, Windows need to detect the gadget as an USB composite
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  51) gadget which on its own have some conditions[4].  If they are met,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  52) Windows lets USB Generic Parent Driver[5] handle the device which then
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  53) tries to match drivers for each individual interface (sort of, don't
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  54) get into too many details).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  55) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  56) The good news is: you do not have to worry about most of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  57) conditions!
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  58) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  59) The only thing to worry is that the gadget has to have a single
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  60) configuration so a dual RNDIS and CDC ECM gadget won't work unless you
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  61) create a proper INF -- and of course, if you do submit it!
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  62) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  63) Installing drivers for each function
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  64) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  65) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  66) The other, trickier thing is making Windows install drivers for each
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  67) individual function.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  68) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  69) For mass storage it is trivial since Windows detect it's an interface
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  70) implementing USB Mass Storage class and selects appropriate driver.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  71) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  72) Things are harder with RDNIS and CDC ACM.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  73) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  74) RNDIS
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  75) .....
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  76) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  77) To make Windows select RNDIS drivers for the first function in the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  78) gadget, one needs to use the [[file:linux.inf]] file provided with this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  79) document.  It "attaches" Window's RNDIS driver to the first interface
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  80) of the gadget.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  81) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  82) Please note, that while testing we encountered some issues[6] when
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  83) RNDIS was not the first interface.  You do not need to worry abut it
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  84) unless you are trying to develop your own gadget in which case watch
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  85) out for this bug.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  86) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  87) CDC ACM
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  88) .......
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  89) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  90) Similarly, [[file:linux-cdc-acm.inf]] is provided for CDC ACM.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  91) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  92) Customising the gadget
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  93) ......................
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  94) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  95) If you intend to hack the g_multi gadget be advised that rearranging
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  96) functions will obviously change interface numbers for each of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  97) functionality.  As an effect provided INFs won't work since they have
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  98) interface numbers hard-coded in them (it's not hard to change those
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  99) though[7]).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101) This also means, that after experimenting with g_multi and changing
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102) provided functions one should change gadget's vendor and/or product ID
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103) so there will be no collision with other customised gadgets or the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104) original gadget.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106) Failing to comply may cause brain damage after wondering for hours why
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107) things don't work as intended before realising Windows have cached
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108) some drivers information (changing USB port may sometimes help plus
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109) you might try using USBDeview[8] to remove the phantom device).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111) INF testing
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112) ...........
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114) Provided INF files have been tested on Windows XP SP3, Windows Vista
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115) and Windows 7, all 32-bit versions.  It should work on 64-bit versions
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116) as well.  It most likely won't work on Windows prior to Windows XP
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117) SP2.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119) Other systems
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120) -------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122) At this moment, drivers for any other systems have not been tested.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123) Knowing how MacOS is based on BSD and BSD is an Open Source it is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124) believed that it should (read: "I have no idea whether it will") work
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125) out-of-the-box.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127) For more exotic systems I have even less to say...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129) Any testing and drivers *are* *welcome*!
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131) Authors
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132) =======
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134) This document has been written by Michal Nazarewicz
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135) ([[mailto:mina86@mina86.com]]).  INF files have been hacked with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136) support of Marek Szyprowski ([[mailto:m.szyprowski@samsung.com]]) and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137) Xiaofan Chen ([[mailto:xiaofanc@gmail.com]]) basing on the MS RNDIS
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138) template[9], Microchip's CDC ACM INF file and David Brownell's
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139) ([[mailto:dbrownell@users.sourceforge.net]]) original INF files.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141) Footnotes
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142) =========
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144) [1] Remote Network Driver Interface Specification,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145) [[https://msdn.microsoft.com/en-us/library/ee484414.aspx]].
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147) [2] Communications Device Class Abstract Control Model, spec for this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148) and other USB classes can be found at
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149) [[http://www.usb.org/developers/devclass_docs/]].
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151) [3] CDC Ethernet Control Model.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 153) [4] [[https://msdn.microsoft.com/en-us/library/ff537109(v=VS.85).aspx]]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 154) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 155) [5] [[https://msdn.microsoft.com/en-us/library/ff539234(v=VS.85).aspx]]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 156) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 157) [6] To put it in some other nice words, Windows failed to respond to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 158) any user input.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 159) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 160) [7] You may find [[http://www.cygnal.org/ubb/Forum9/HTML/001050.html]]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 161) useful.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 162) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 163) [8] https://www.nirsoft.net/utils/usb_devices_view.html
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 164) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 165) [9] [[https://msdn.microsoft.com/en-us/library/ff570620.aspx]]