USB Raw Gadget

https://www.kernel.org/doc/html/latest/usb/raw-gadget.html


Linux Kernel 5.7-rc1からサポートされた、USB Raw Gadget！
やったね！！ユーザー空間でうごくアプリケーションで、USB Gadgetが作れるようになったよ！

---
Docs » USB support » USB Raw Gadget

# USB Raw Gadget

> USB Raw Gadget is a kernel module that provides a userspace interface for the USB Gadget subsystem. Essentially it allows to emulate USB devices from userspace. Enabled with CONFIG_USB_RAW_GADGET. Raw Gadget is currently a strictly debugging feature and shouldn’t be used in production, use GadgetFS instead.

USB Raw Gadgetは、USB Gadget subsystemへのユーザー空間インタフェイスを提供するものです。本質的には、ユーザー空間からUSB deviceをエミュレーションすることを許容します。CONF_USB_RAW_GADGETを有効にしてください。Raw Gadgetは現在、厳密にデバッグ中の機能であり、製品では使わないでください。その代わりに、GadgetFSを使ってください。

# Comparison to GadgetFS

> Raw Gadget is similar to GadgetFS, but provides a more low-level and direct access to the USB Gadget layer for the userspace. The key differences are:

Raw GadgetはGadgetFSに似ていますが、ユーザー空間からUSB Gadget layerへ、低レベルで直接的なアクセスを提供します。主な差分は以下です。

> １. Every USB request is passed to the userspace to get a response, while GadgetFS responds to some USB requests internally based on the provided descriptors. However note, that the UDC driver might respond to some requests on its own and never forward them to the Gadget layer.

１. すべてのUSB要求は、応答を得るためにユーザー空間へ渡されます。GadgetFSでは提供された記述子(descriptor)に応じて、内部的に一部のUSB要求へ応答をします。ただし、UDCドライバーは一部の要求に独自で応答し、それらをGadget Layerに転送しない場合があります。

> ２. GadgetFS performs some sanity checks on the provided USB descriptors, while Raw Gadget allows you to provide arbitrary data as responses to USB requests.

 ２. GadgetFSは提供されたUSB記述子において正当性を確認します。Raw GadgetではUSB要求への応答として任意のデータを提供することができます。

> ３. Raw Gadget provides a way to select a UDC device/driver to bind to, while GadgetFS currently binds to the first available UDC.

 ３. Raw Gadgetでは、バインドしたいUDC device/driverを選択する手段を提供しますが、GadgetFSでは現在、最初に有効なUDCをバインドします。

> ４. Raw Gadget uses predictable endpoint names (handles) across different UDCs (as long as UDCs have enough endpoints of each required transfer type)

４. Raw Gadgetは、異なるUDCを横断して、予想できるendpoint name(handke)を利用します(UDCに必要なとなるそれぞれの転送タイプ.のendpointが十分ある場合に限っては）。

> ５.Raw Gadget has ioctl-based interface instead of a filesystem-based one.

５. Raw Gadgeはfilesystem-basedの代わりに、uictl-baseのインタフェイスを提供します。

# Userspace interface

> To create a Raw Gadget instance open /dev/raw-gadget. Multiple raw-gadget instances (bound to different UDCs) can be used at the same time. The interaction with the opened file happens through the ioctl() calls, see comments in include/uapi/linux/usb/raw_gadget.h for details.

Raw Gadget instanceを作るためには、/dev/raw-gadetを開いてください。複数のraw-gadget instanceを（異なるUDCsのために）同じ時間で利用することができます。開いたファイルとの対話には、ioctl() を呼び出します。詳細については、include/uapi/linux/usb/raw_gadget.hのコメントを参照してください。

> The typical usage of Raw Gadget looks like:

典型的なRaw Gadgetの使い方は以下になります。

>１. Open Raw Gadget instance via /dev/raw-gadget.
２. Initialize the instance via USB_RAW_IOCTL_INIT.
３. Launch the instance with USB_RAW_IOCTL_RUN.
４. In a loop issue USB_RAW_IOCTL_EVENT_FETCH calls to receive events from Raw Gadget and react to those depending on what kind of USB device needs to be emulated.

１．Raw Gadget instanceを、/dev/raw-gadetを介して開く。
２．USB_RAW_IOCTL_INITによって、インスタンスを初期化する。
３．USB_RAW_IOCTL_RUNによって、インスタンスを起動する。
４．RAW_IOCTL_EVENT_FETCHにより、Raw Gadgetからのイベントを受信しながらループを行い、エミュレーションするべきUSB deviceのような反応をする。

# Potential future improvements

> ・Implement ioctl’s for setting/clearing halt status on endpoints.
・Reporting more events (suspend, resume, etc.) through USB_RAW_IOCTL_EVENT_FETCH.
・Support O_NONBLOCK I/O.

・endpointの停止ステータスを設定/クリアするための、ioctlの実装
・USB_RAW_IOCTL_EVENT_FETCHを介しての様々なイベント(suspend, resume, 他）のレポート。
・O_NONBLOCK I/Oのサポート。

---
もともと、Linux Kernelのソースコードの一部なので、GPLv2扱いになる（はずの認識）。

> https://www.kernel.org/doc/html/latest/index.html
> 
> Licensing documentation
> 
> The following describes the license of the Linux kernel source code (GPLv2), how to properly mark the license of individual files in the source tree, as well as links to the full license text.
> 
> https://www.kernel.org/doc/html/latest/process/license-rules.html#kernel-licensing