How to enable Android ConfigFS gadgets

  • The instructions to enabled MTP/PTP from command line did not work for me reliably on Marshmallow release or AOSP master snapshots. They work fine on Lollipop though.

Synopsis

  • Android moved to ConfigFS based USB gadgets for their newer (android-3.14+) kernels.
  • Following configurations are verified on IFC6410 running Lollipop (android-5.1.1) and AOSP master (as on 20-Jan-2016) with kernel 3.18 with software rendering (libGLES_android).

Kernel Configuration

  • Make sure your kernel has at least following ConfigFS USB gadget and Android configs enabled.

CONFIG_USB_CONFIGFS=y
CONFIG_USB_CONFIGFS_F_FS=y
CONFIG_USB_CONFIGFS_F_MTP=y
CONFIG_USB_CONFIGFS_F_PTP=y
CONFIG_USB_CONFIGFS_UEVENT=y

Enable Android USB gadgets from UI

Changes for AOSP master snapshot

  • AOSP has already checked in ConfigFS init scripts in system/core project and these scripts work out of the box. We just have to add minor ConfigFS initialization steps in init.${ro.hardware}.rc to set ConfigFS gadget and UDC driver related properties and mount ConfigFS usb gadgets.

init.${ro.hardware}.rc changes

on init
+    # Create mount-point for ConfigFS USB gadgets
+    # Add standard gadget entries
+    mount configfs none /config
+    mkdir /config/usb_gadget/g1 0770 shell shell
+    write /config/usb_gadget/g1/idVendor 0x18D1
+    write /config/usb_gadget/g1/idProduct 0x4E26
+    mkdir /config/usb_gadget/g1/strings/0x409 0770 shell shell
+    write /config/usb_gadget/g1/strings/0x409/serialnumber 0123459876
+    write /config/usb_gadget/g1/strings/0x409/manufacturer Qcom
+    write /config/usb_gadget/g1/strings/0x409/product IFC6410
+    mkdir /config/usb_gadget/g1/configs/b.1 0770 shell shell
+    mkdir /config/usb_gadget/g1/configs/b.1/strings/0x409 0770 shell shell
+    write /config/usb_gadget/g1/configs/b.1/strings/0x409/configuration "Conf 1"
+    write /config/usb_gadget/g1/configs/b.1/MaxPower 120
+
+    # Create adb+ffs gadget function
+    mkdir /config/usb_gadget/g1/functions/ffs.adb 0770 shell shell
+    mkdir /dev/usb-ffs 0770 shell shell
+    mkdir /dev/usb-ffs/adb 0770 shell shell
+    mount functionfs adb /dev/usb-ffs/adb uid=2000,gid=2000
+
+    # Create MTP and PTP functions
+    mkdir /config/usb_gadget/g1/functions/mtp.gs0 0770 shell shell
+    mkdir /config/usb_gadget/g1/functions/ptp.gs1 0770 shell shell

on boot
+    setprop sys.usb.configfs 1
+    #Replace "ci_hdrc.0" with your platform UDC driver as found in /sys/class/udc/
+    setprop sys.usb.controller ci_hdrc.0

Changes for Lollipop (android-5.1.1_r18)

  • Only ADB and MTP can be enabled at the moment from UI/Settings Application for lollipop. PTP works from command line but can not be enabled reliably from UI at the moment. So it is skipped for the time being.

init.rc changes

  • There is this minor ConfigFS change we have introduced in init.rc, wherein instead of starting adbd daemon directly we let "persist.sys.usb.config" property change trigger that for us. This "on property" trigger in "init.usb.rc" will take care of ConfigFS gadget configuration.

 # adbd on at boot in emulator
 on property:ro.kernel.qemu=1
-    start adbd
+    setprop persist.sys.usb.config adb

 service lmkd /system/bin/lmkd
     class core
  • Also evident from above init.rc change is that the system USB properties are not persistent across reboots if we are running in an emulator or using software graphics rendering. That means the system will always start with only adb enabled and you have to manully select MTP/PTP/RNDIS option from the Settings application to enable them.

init.usb.rc changes

  • This is how my init.usb.rc looked like at that time. Supported configurations are ADB only, MTP only, MTP+ADB.
  • You can probably come up with a better version yourself if you follow init.usb.configfs.rc script from AOSP master. Just saying :)

#
# USB configuration common for all android devices
#

on init
    # Create ConfigFS mount point for USB gadgets
    # Add standard gadget entries
    mount configfs none /config
    mkdir /config/usb_gadget/g1
    write /config/usb_gadget/g1/idVendor 0x18D1
    write /config/usb_gadget/g1/idProduct 0x4E26
    mkdir /config/usb_gadget/g1/strings/0x409
    write /config/usb_gadget/g1/strings/0x409/serialnumber 0123459876
    write /config/usb_gadget/g1/strings/0x409/manufacturer Qcom
    write /config/usb_gadget/g1/strings/0x409/product IFC6410
    mkdir /config/usb_gadget/g1/configs/c.1
    mkdir /config/usb_gadget/g1/configs/c.1/strings/0x409
    write /config/usb_gadget/g1/configs/c.1/strings/0x409/configuration "Conf 1"
    write /config/usb_gadget/g1/configs/c.1/MaxPower 120

    # Create adb+ffs gadget function
    mkdir /config/usb_gadget/g1/functions/ffs.adb
    mkdir /dev/usb-ffs 0770 shell shell
    mkdir /dev/usb-ffs/adb 0770 shell shell
    mount functionfs adb /dev/usb-ffs/adb uid=2000,gid=2000

# Used to disable USB when switching states
on property:sys.usb.config=none
    write /config/usb_gadget/g1/UDC ""
    stop adbd
    setprop sys.usb.state ${sys.usb.config}

# adb only gadget configuration
# This is the fallback configuration if the
# USB manager fails to set a standard configuration
on property:sys.usb.config=adb
    stop adbd
    symlink /config/usb_gadget/g1/functions/ffs.adb /config/usb_gadget/g1/configs/c.1/ffs.adb
    start adbd
    #Had to set this property early because userspace expect us to be done with state changes in 1 second.
    setprop sys.usb.state ${sys.usb.config}
    #Add this 2 second wait/delay to calm things down after adbd restart and before we enable UDC.
    wait /dev/socket/waiting
    #Replace "ci_hdrc.0" with your platform UDC driver as found in /sys/class/udc/
    write /config/usb_gadget/g1/UDC ci_hdrc.0

# MTP
on property:sys.usb.config=mtp
    rm /config/usb_gadget/g1/configs/c.1/ffs.adb
    mkdir /config/usb_gadget/g1/functions/mtp.mtp
    symlink /config/usb_gadget/g1/functions/mtp.mtp /config/usb_gadget/g1/configs/c.1/mtp.mtp
    #Replace "ci_hdrc.0" with your platform UDC driver as found in /sys/class/udc/
    write /config/usb_gadget/g1/UDC ci_hdrc.0
    setprop sys.usb.state ${sys.usb.config}

# MTP + ADB
on property:sys.usb.config=mtp,adb
    stop adbd
    symlink /config/usb_gadget/g1/functions/ffs.adb /config/usb_gadget/g1/configs/c.1/ffs.adb
    start adbd
    mkdir /config/usb_gadget/g1/functions/mtp.mtp
    symlink /config/usb_gadget/g1/functions/mtp.mtp /config/usb_gadget/g1/configs/c.1/mtp.mtp
    #Had to set this property early because userspace expect us to be done with state changes in 1 second.
    setprop sys.usb.state ${sys.usb.config}
    #Add this 2 second wait/delay to calm things down after adbd restart and before we enable UDC.
    wait /dev/socket/waiting
    #Replace "ci_hdrc.0" with your platform UDC driver as found in /sys/class/udc/
    write /config/usb_gadget/g1/UDC ci_hdrc.0

# Used to set USB configuration at boot and to switch the configuration
# when changing the default configuration
on property:persist.sys.usb.config=*
    setprop sys.usb.config ${persist.sys.usb.config}

Manual / Command line instructions (Works only for Lollipop at the moment)

ADB gadget configuration

  • Run following commands from Android shell as root.

#Mount ConfigFS and create Gadget
mount -t configfs none /config
mkdir /config/usb_gadget/g1
cd /config/usb_gadget/g1

#Set default Vendor and Product IDs for now
echo 0x18d1 > idVendor
echo 0x4E26 > idProduct

#Create English strings and add random deviceID
mkdir strings/0x409
echo 0123459876 > strings/0x409/serialnumber

#Update following if you want to
echo "Test" > strings/0x409/manufacturer
echo "Test" > strings/0x409/product

#Create gadget configuration
mkdir configs/c.1
mkdir configs/c.1/strings/0x409
echo "Conf 1" > configs/c.1/strings/0x409/configuration
echo 120 > configs/c.1/MaxPower

#Create Adb FunctionFS function
#And link it to the gadget configuration
stop adbd
mkdir functions/ffs.adb
ln -s /config/usb_gadget/g1/functions/ffs.adb /config/usb_gadget/g1/configs/c.1/ffs.adb

#Start adbd application
mkdir -p /dev/usb-ffs/adb
mount -o uid=2000,gid=2000 -t functionfs adb /dev/usb-ffs/adb
start adbd

#Enable the Gadget
#Replace "ci_hdrc.0" with your platform UDC driver as found in /sys/class/udc/
echo "ci_hdrc.0" > /config/usb_gadget/g1/UDC

MTP gadget configuration

  • While ADB was straight forward. MTP is a bit tricky. We have to make sure that we set following properties in on init section of init.rc to notify userspace of USB state early enough before UsbDeviceManager service kicks in.

setprop persist.sys.usb.config mtp
setprop sys.usb.config mtp
setprop sys.usb.state mtp

If not set during on init, adb will be set as default and overwriting later won't help.

  • Run following commands from Android shell as root.

#Mount ConfigFS and create Gadget
mount -t configfs none /config
mkdir /config/usb_gadget/g1
cd /config/usb_gadget/g1

#Set default Vendor and Product IDs for now
echo 0x18d1 > idVendor
echo 0x4E26 > idProduct

#Create English strings and add random deviceID
mkdir strings/0x409
echo 0123459876 > strings/0x409/serialnumber

#Update following if you want to
echo "Test" > strings/0x409/manufacturer
echo "Test" > strings/0x409/product

#Create gadget configuration
mkdir configs/c.1
mkdir configs/c.1/strings/0x409
echo "Conf 1" > configs/c.1/strings/0x409/configuration
echo 120 > configs/c.1/MaxPower
  • Make sure we create MTP function and add (symlink) it in gadget configuration only when the Android boot is complete. You can check that by checking the status of sys.boot_completed property before running the following commands.

#Create MTP function, 
#And link it to the gadget configuration
mkdir /config/usb_gadget/g1/functions/mtp.mtp
ln -s /config/usb_gadget/g1/functions/mtp.mtp /config/usb_gadget/g1/configs/c.1/mtp.mtp

#Enable the Gadget
#Replace "ci_hdrc.0" with your platform UDC driver as found in /sys/class/udc/
echo "ci_hdrc.0" > /config/usb_gadget/g1/UDC

MTP + ADB gadget configuration

  • Like MTP config above make sure that we set following properties in on init section of init.rc to notify userspace of USB state early enough before UsbDeviceManager service kicks in.

setprop persist.sys.usb.config mtp,adb
setprop sys.usb.config mtp,adb
setprop sys.usb.state mtp,adb
  • Run following commands from Android shell as root.

#Mount ConfigFS and create Gadget
mount -t configfs none /config
mkdir /config/usb_gadget/g1
cd /config/usb_gadget/g1

#Set default Vendor and Product IDs for now
echo 0x18d1 > idVendor
echo 0x4E26 > idProduct

#Create English strings and add random deviceID
mkdir strings/0x409
echo 0123459876 > strings/0x409/serialnumber

#Update following if you want to
echo "Test" > strings/0x409/manufacturer
echo "Test" > strings/0x409/product

#Create gadget configuration
mkdir configs/c.1
mkdir configs/c.1/strings/0x409
echo "Conf 1" > configs/c.1/strings/0x409/configuration
echo 120 > configs/c.1/MaxPower

#Create Adb FunctionFS function
#And link it to the gadget configuration
stop adbd
mkdir functions/ffs.adb
ln -s /config/usb_gadget/g1/functions/ffs.adb /config/usb_gadget/g1/configs/c.1/ffs.adb

#Start adbd application
mkdir -p /dev/usb-ffs/adb
mount -o uid=2000,gid=2000 -t functionfs adb /dev/usb-ffs/adb
start adbd
  • Make sure we create MTP function and add (symlink) it in gadget configuration only when the Android boot is complete. You can check that by checking the status of sys.boot_completed property before running the following commands.

#Create MTP function, 
#And link it to the gadget configuration
mkdir /config/usb_gadget/g1/functions/mtp.mtp
ln -s /config/usb_gadget/g1/functions/mtp.mtp /config/usb_gadget/g1/configs/c.1/mtp.mtp

#Enable the Gadget
#Replace "ci_hdrc.0" with your platform UDC driver as found in /sys/class/udc/
echo "ci_hdrc.0" > /config/usb_gadget/g1/UDC

PTP gadget configuration

  • Just like MTP, we have to make sure that we set following properties in on init section of init.rc to notify userspace of USB state early enough before UsbDeviceManager service kicks in.

setprop persist.sys.usb.config ptp
setprop sys.usb.config ptp
setprop sys.usb.state ptp

If not set during on init, adb will be set as default and overwriting later won't help.

  • Run following commands from Android shell as root.

#Mount ConfigFS and create Gadget
mount -t configfs none /config
mkdir /config/usb_gadget/g1
cd /config/usb_gadget/g1

#Set default Vendor and Product IDs for now
echo 0x18d1 > idVendor
echo 0x4E26 > idProduct

#Create English strings and add random deviceID
mkdir strings/0x409
echo 0123459876 > strings/0x409/serialnumber

#Update following if you want to
echo "Test" > strings/0x409/manufacturer
echo "Test" > strings/0x409/product

#Create gadget configuration
mkdir configs/c.1
mkdir configs/c.1/strings/0x409
echo "Conf 1" > configs/c.1/strings/0x409/configuration
echo 120 > configs/c.1/MaxPower
  • Make sure we create PTP function and add (symlink) it in gadget configuration only when the Android boot is complete. You can check that by checking the status of sys.boot_completed property before running the following commands.

#Create MTP and PTP function,
#And link it to the gadget configuration
#Android's PTP implementation piggyback on MTP function so make sure we have MTP function created beforehand.
mkdir /config/usb_gadget/g1/functions/mtp.mtp
mkdir /config/usb_gadget/g1/functions/ptp.ptp
ln -s /config/usb_gadget/g1/functions/ptp.ptp /config/usb_gadget/g1/configs/c.1/ptp.ptp

#Enable the Gadget
#Replace "ci_hdrc.0" with your platform UDC driver as found in /sys/class/udc/
echo "ci_hdrc.0" > /config/usb_gadget/g1/UDC

PTP + ADB gadget configuration

  • Like PTP config above make sure that we set following properties in on init section of init.rc to notify userspace of USB state early enough before UsbDeviceManager service kicks in.

setprop persist.sys.usb.config ptp,adb
setprop sys.usb.config ptp,adb
setprop sys.usb.state ptp,adb
  • Run following commands from Android shell as root.

#Mount ConfigFS and create Gadget
mount -t configfs none /config
mkdir /config/usb_gadget/g1
cd /config/usb_gadget/g1

#Set default Vendor and Product IDs for now
echo 0x18d1 > idVendor
echo 0x4E26 > idProduct

#Create English strings and add random deviceID
mkdir strings/0x409
echo 0123459876 > strings/0x409/serialnumber

#Update following if you want to
echo "Test" > strings/0x409/manufacturer
echo "Test" > strings/0x409/product

#Create gadget configuration
mkdir configs/c.1
mkdir configs/c.1/strings/0x409
echo "Conf 1" > configs/c.1/strings/0x409/configuration
echo 120 > configs/c.1/MaxPower
  • Make sure we create MTP function and add (symlink) it in gadget configuration only when the Android boot is complete. You can check that by checking the status of sys.boot_completed property before running the following commands.

  • Also for PTP + ADB gadget configuration make sure we add or symlink PTP function to the gadget configuration before we add ADB. Symlink order matters here. Not sure why.

#Create MTP and PTP function,
#And link it to the gadget configuration
#Android's PTP implementation piggyback on MTP function so make sure we have MTP function created beforehand.
mkdir /config/usb_gadget/g1/functions/mtp.mtp
mkdir /config/usb_gadget/g1/functions/ptp.ptp
ln -s /config/usb_gadget/g1/functions/ptp.ptp /config/usb_gadget/g1/configs/c.1/ptp.ptp

#Create Adb FunctionFS function
#And link it to the gadget configuration
stop adbd
mkdir functions/ffs.adb
ln -s /config/usb_gadget/g1/functions/ffs.adb /config/usb_gadget/g1/configs/c.1/ffs.adb

#Start adbd application
mkdir -p /dev/usb-ffs/adb
mount -o uid=2000,gid=2000 -t functionfs adb /dev/usb-ffs/adb
start adbd

#Enable the Gadget
#Replace "ci_hdrc.0" with your platform UDC driver as found in /sys/class/udc/
echo "ci_hdrc.0" > /config/usb_gadget/g1/UDC

Known Issues

  • Android's MTP and PTP implementations are mutually exclusive so make sure we have only one of it linked to a configuration at a time from command line. Otherwise it opens up another set of crashes.
  • There are few corner cases where in kernel OOPs while trying out different set of MTP/PTP and ADB configurations in random order.
  • If you are running into waitForState() failures in logcat while doing USB state changes for lollipop then you might want to increase the transition timeout in waitForState() at frameworks/base/services/usb/java/com/android/server/usb/UsbDeviceManager.java.

LMG/Kernel/AndroidConfigFSGadgets (last modified 2016-02-09 13:52:36)