Introduction
~~~~~~~~~~~~~~~
USB gadget is a mode of Linux USB port handling when Linux is not driving
the port as a host port, but as a device - this lets Linux act as a mass
storage (usb hdd, usb cdrom, etc.), a hid device (mouse, keyboard), a
webcam, etc.

Orange PI and some other cheap arm boards feature an OTG port; OTG means
on-the-go: the electronics implements both host and device roles, the software
driver can change the role any time. The Linux kernel calls device mode
drivers "gadgets".

Converting one of the ports to a gadget is often useful:
  - the cheap arm board can become the hardware implementation of a complex
    USB peripheral for a PC
  - an arm mini-server can expose some of its internals over the USB to a PC,
    e.g. an orange PI used as a NAS also mountable as a mass storage over USB
  - a second ethernet port using g_ether


How to set it up
~~~~~~~~~~~~~~~~~~~
As of Jun 2016, the following process worked for me, on an orange PI pc v1.2:

1. Install your favorite Linux distribution

2. Get a recent kernel source; I used armbian's 3.4.112

3. patch the sunxi udc driver at drivers/usb/sunxi_usb/udc/sunxi_udc.c,
to enable usb device mode:

--- sunxi_udc.c.orig	2016-06-12 16:08:07.000000000 +0200
+++ sunxi_udc.c	2016-06-12 16:51:30.000000000 +0200
@@ -57,7 +57,7 @@
 static sunxi_udc_io_t g_sunxi_udc_io;
 static u32 usb_connect = 0;
 static u32 is_controller_alive = 0;
-static u8 is_udc_enable = 0;   /* is udc enable by gadget? */
+static u8 is_udc_enable = 1;   /* is udc enable by gadget? */
 
 #ifdef CONFIG_USB_SUNXI_USB0_OTG
 static struct platform_device *g_udc_pdev = NULL;

4. while configuring the kernel, make sure to select the following components:

CONFIG_USB_SUNXI_USB0_OTG=y
CONFIG_USB_GADGET=y
CONFIG_USB_ETH=m

   menuconfig:
   -> Device Drivers
   -> USB support (USB_SUPPORT [=y])

     -> SUNXI USB2.0 Dual Role Controller support (USB_SUNXI_USB [=y]
       -> SUNXI USB2.0 Manager (USB_SUNXI_USB_MANAGER [=y])
         -> USB0 Controller support (<choice> [=y])
         (select "otg support")

     -> USB Gadget Support (=y)
       -> Ethernet gadget (module)

5. reboot to the new kernel

6. activate the device
  - make sure otg role is not 2: echo -n 0 > /sys/bus/platform/devices/sunxi_usb_udc/otg_role
  - load the driver: modprobe g_ether
  - switch otg role to 2: echo -n 2 > /sys/bus/platform/devices/sunxi_usb_udc/otg_role

  NOTE: it is important to switch role to otg only after the gadget driver
  is loaded, else the udc driver will not engage device mode. Having g_ether
  (or your favorite gadget driver) in a module makes it easier to have the order
  right.

7. host and cable

A plain USB to microUSB cable should work. You should use external power
supply on most arm boards - pumping 2A over the microUSB plug is probably
not a good idea.

My USB Host was a Debian system which detected usb0 as cdc_ether.



Thanks to tkaiser for the excellent support on irc.freenode.net #linux-sunxi