How to enable Android ConfigFS gadgets

From https://wiki.linaro.org/LMG/Kernel/AndroidConfigFSGadgets#Synopsis

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.

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.