https://www.kernel.org/doc/html/latest/usb/gadget_serial.html
Linux Gadget Serial Driver v2.0
11/20/2004
(updated 8-May-2008 for v2.3)
License and Disclaimer
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.
This document and the gadget serial driver itself are Copyright (C) 2004 by Al Borchers (alborchers＠steinerpoint.com).
If you have questions, problems, or suggestions for this driver please contact Al Borchers at alborchers＠steinerpoint.com.
Prerequisites
Versions of the gadget serial driver are available for the 2.4 Linux kernels, but this document assumes you are using version 2.3 or later of the gadget serial driver in a 2.6 Linux kernel.
The gadget serial driver has been enabled since the 2.4 Linux kernel, but this document assumes that you are using the gadget serial driver version 2.3 or later on the 2.6 Linux Kernel.
This document assumes that you are familiar with Linux and Windows and know how to configure and build Linux kernels, run standard utilities, use minicom and HyperTerminal, and work with USB and serial devices. It also assumes you configure the Linux gadget and usb drivers as modules.
This document assumes that you are familiar with Linux and Windows, know how to set up and build the Linux Kernel, run standard utilities, use minicon and HyperTerminal, and handle USB and serial devices. Will also arrive. Also, you are assuming that you have Linux gadget and usb driver configured as modules.
With version 2.3 of the driver, major and minor device nodes are no longer statically defined. Your Linux based system should mount sysfs in /sys, and use “mdev” (in Busybox) or “udev” to make the /dev nodes matching the sysfs /sys/class/tty files.
In driver version 2.3, the major / minor device node was not statically defined. On a Linux based system, mount sysfs with / sys and match sysfs / sys / class / tty files with / dev node by mbev (if BusyBox), otherwise "udev".
Overview
The gadget serial driver is a Linux USB gadget driver, a USB device side driver. It runs on a Linux system that has USB device side hardware; for example, a PDA, an embedded Linux system, or a PC with a USB development card.
Gadget serial driver is a Linux USB gadget driver and a USB dervice sid driver. It runs on a Linux system that has a USB device located next to the hardware: for example, with a PDA, an embedded Linux system, or a USB development card. PC.
The gadget serial driver talks over USB to either a CDC ACM driver or a generic USB serial driver running on a host PC:
The Gadget serial driver communicates via USB with either the CDC ACM driver or the generic USB serial driver running on the hos PC.
Host
--------------------------------------
| Host-Side CDC ACM USB Host |
| Operating | or | Controller | USB
| System | Generic USB | Driver |--------
| (Linux or | Serial | and | |
| Windows) Driver USB Stack | |
-------------------------------------- |
|
|
|
Gadget |
-------------------------------------- |
| Gadget USB Periph. | |
| Device-Side | Gadget | Controller | |
| Linux | Serial | Driver |--------
| Operating | Driver | and |
| System USB Stack |
--------------------------------------
On the device-side Linux system, the gadget serial driver looks like a serial device.
From the device-side linux system, the gadget serial driver looks like a seirla device.
On the host-side system, the gadget serial device looks like a CDC ACM compliant class device or a simple vendor specific device with bulk in and bulk out endpoints, and it is treated similarly to other serial devices.
From the perspective of the host-side system, the gadget serial device looks like a CDC ACM compliant class device or a simple vendor specific device with a bulk out endpoint in bulk in and is used like any other serial device.
The host side driver can potentially be any ACM compliant driver or any driver that can talk to a device with a simple bulk in/out interface. Gadget serial has been tested with the Linux ACM driver, the Windows usbser.sys ACM driver, and the Linux USB generic serial driver.
The host side driver can be an ACM compliant driver or a driver that can communicate with a simple bulk in / out interface. Gadget serial is tested with the Linux ACM driver, Windows usbser.sys ACM driver, or the Linux USB generic serial driver,
With the gadget serial driver and the host side ACM or generic serial driver running, you should be able to communicate between the host and the gadget side systems as if they were connected by a serial cable.
When running the Gadget serial driver and the host side ACM / generic serial driver, you can communicate between the host and the gadget side system if they are connected by a serial cable.
The gadget serial driver only provides simple unreliable data communication. It does not yet handle flow control or many other features of normal serial devices.
The Gadget serial driver only provides unreliable data communication. It does not handle flow control or many other features of other common serial devices.
Installing the Gadget Serial Driver
To use the gadget serial driver you must configure the Linux gadget side kernel for “Support for USB Gadgets”, for a “USB Peripheral Controller” (for example, net2280), and for the “Serial Gadget” driver. All this are listed under “USB Gadget Support” when configuring the kernel. Then rebuild and install the kernel or modules.
To use the Gadget serial driver, you need to set the "Support for USB Gadgets", "USB Peripheral Controller" (eg net2280), and the "Serial Gadget" driver to the Linux gadget side kernel. All of these are listed under "USB Gadget Support" when configuring the Kernel. Then rebuild and install the kernel and module.
Then you must load the gadget serial driver. To load it as an ACM device (recommended for interoperability), do this:
Then you have to load the gadget srial driver. Do this to load as a CM device (recommended for interoperability).
modprobe g_serial
To load it as a vendor specific bulk in/out device, do this:
When loading as a vendor specific bulk in / out device, do as follows.
modprobe g_serial use_acm=0
This will also automatically load the underlying gadget peripheral controller driver. This must be done each time you reboot the gadget side Linux system. You can add this to the start up scripts, if desired.
This will also automatically read the underlying gadget peripheral controller driver. This should be done every time the gadget side Linux system reboots. Add it to your start up script if needed.
Your system should use mdev (from busybox) or udev to make the device nodes. After this gadget driver has been set up you should then see a /dev/ttyGS0 node:
You need to create a device node using mdev (from busybox) or udev. Once you have this gadget driver set up, you can refer to it as / dev / ttyGS0 node:
# ls -l /dev/ttyGS0 | cat
crw-rw---- 1 root root 253, 0 May 8 14:10 /dev/ttyGS0
#
Note that the major number (253, above) is system-specific. If you need to create /dev nodes by hand, the right numbers to use will be in the /sys/class/tty/ttyGS0/dev file.
Note that the major number (253 above) is system specific. If you need to create / dev node by hand, please use the correct value in / sys / class / tty / ttyGS0 / dev file.
When you link this gadget driver early, perhaps even statically, you may want to set up an /etc/inittab entry to run “getty” on it. The /dev/ttyGS0 line should work like most any other serial port.
If you want to connect the gadget driver early, or if you want to make it static, you can run "getty" in / etc / inittab entry. The / dev / ttyGS0 line should work like any other serial driver.
If gadget serial is loaded as an ACM device you will want to use either the Windows or Linux ACM driver on the host side. If gadget serial is loaded as a bulk in/out device, you will want to use the Linux generic serial driver on the host side. Follow the appropriate instructions below to install the host side driver.
If Gadget serial is loaded as an ACM device, you need to use either Windows or Linux ACM driver on the host side. Gadget serial is bulk in / out device site If it is loaded, you need to use the Linux generial serial driver on the host side. Follow the steps below to install the host side driver.
Installing the Windows Host ACM Driver
To use the Windows ACM driver you must have the “linux-cdc-acm.inf” file (provided along this document) which supports all recent versions of Windows.
To use the Windows ACM driver, you must have a "linux-cdc-acm.inf" file (provided in this document) that is supported by all latest versions of Windows.
When the gadget serial driver is loaded and the USB device connected to the Windows host with a USB cable, Windows should recognize the gadget serial device and ask for a driver. Tell Windows to find the driver in the folder that contains the “linux-cdc-acm.inf” file.
When the gadget serial driver is loaded and the USB device is connected to the Windows host with a USB cable, Windows will recognize the dadget serial device and ask the driver. Tells Windows to find the driver in the folder that contains the "linux-cdc-acm.inf" file.
For example, on Windows XP, when the gadget serial device is first plugged in, the “Found New Hardware Wizard” starts up. Select “Install from a list or specific location (Advanced)”, then on the next screen select “Include this location in the search” and enter the path or browse to the folder containing the “linux-cdc-acm.inf” file. Windows will complain that the Gadget Serial driver has not passed Windows Logo testing, but select “Continue anyway” and finish the driver installation.
For example, on Windows XP, the "Found New Hardware Wizard" will start when the gadget serial device is installed for the first time. Select "Install from a list or specific location (Adcanced)". On the next screen, select "Include this location in the search" and enter the path or find the path containing the "linux-cdc-acn.inf" file. Windows warns that the Gadget Serial driver has not passed Windows Logo certification, but selects "Continue anyway" to complete the driver installation.
On Windows XP, in the “Device Manager” (under “Control Panel”, “System”, “Hardware”) expand the “Ports (COM & LPT)” entry and you should see “Gadget Serial” listed as the driver for one of the COM ports.
In Windows XP, when you open the "Ports (COM & LPT) entry" from "Device Manager" (under "Control Panel", "System", "Hardware"), "Gadget Serial" is the COM port. It can be found as one driver.
To uninstall the Windows XP driver for “Gadget Serial”, right click on the “Gadget Serial” entry in the “Device Manager” and select “Uninstall”.
To uninstall Windows XP drviver for "Gadget Serial", right-click on the "Gadget Serial" entry in "Device Manager" and select "Uninstall".
Installing the Linux Host ACM Driver
To use the Linux ACM driver you must configure the Linux host side kernel for “Support for Host-side USB” and for “USB Modem (CDC ACM) support”.
To use the Linux ACM driver, set "Support for Host-side USB" and "USB Modem (CDC ACM) support" in the Linux host side kernel.
Once the gadget serial driver is loaded and the USB device connected to the Linux host with a USB cable, the host system should recognize the gadget serial device. For example, the command:
Once the Gadget serial driver is loaded and the USB device and Linux host are connected with a USB cable, the host system will recognize the gadget serial device. For example, command:
cat /sys/kernel/debug/usb/devices
should show something like this::
As a result, you will see the following result.
T: Bus=01 Lev=01 Prnt=01 Port=01 Cnt=02 Dev#= 5 Spd=480 MxCh= 0
D: Ver= 2.00 Cls=02(comm.) Sub=00 Prot=00 MxPS=64 #Cfgs= 1
P: Vendor=0525 ProdID=a4a7 Rev= 2.01
S: Manufacturer=Linux 2.6.8.1 with net2280
S: Product=Gadget Serial
S: SerialNumber=0
C:* #Ifs= 2 Cfg#= 2 Atr=c0 MxPwr= 2mA
I: If#= 0 Alt= 0 #EPs= 1 Cls=02(comm.) Sub=02 Prot=01 Driver=acm
E: Ad=83(I) Atr=03(Int.) MxPS= 8 Ivl=32ms
I: If#= 1 Alt= 0 #EPs= 2 Cls=0a(data ) Sub=00 Prot=00 Driver=acm
E: Ad=81(I) Atr=02(Bulk) MxPS= 512 Ivl=0ms
E: Ad=02(O) Atr=02(Bulk) MxPS= 512 Ivl=0ms
If the host side Linux system is configured properly, the ACM driver should be loaded automatically. The command “lsmod” should show the “acm” module is loaded.
If the host side Linux system is properly configured, the ACM driver should load automatically. The command "lsmod" indicates that the "acm" module is loaded.
Installing the Linux Host Generic USB Serial Driver
To use the Linux generic USB serial driver you must configure the Linux host side kernel for “Support for Host-side USB”, for “USB Serial Converter support”, and for the “USB Generic Serial Driver”.
To use the Linux ACM driver, set "Support for Host-side USB", "USB Serial Converter Support" and "USB Modem (CDC ACM) support" in the Linux host side kernel.
Once the gadget serial driver is loaded and the USB device connected to the Linux host with a USB cable, the host system should recognize the gadget serial device. For example, the command:
Once the Gadget serial driver is loaded and the USB device and Linux host are connected with a USB cable, the host system will recognize the gadget serial device. For example, command:
cat /sys/kernel/debug/usb/devices
should show something like this::
As a result, you will see the following result.
T: Bus=01 Lev=01 Prnt=01 Port=01 Cnt=02 Dev#= 6 Spd=480 MxCh= 0
D: Ver= 2.00 Cls=ff(vend.) Sub=00 Prot=00 MxPS=64 #Cfgs= 1
P: Vendor=0525 ProdID=a4a6 Rev= 2.01
S: Manufacturer=Linux 2.6.8.1 with net2280
S: Product=Gadget Serial
S: SerialNumber=0
C:* #Ifs= 1 Cfg#= 1 Atr=c0 MxPwr= 2mA
I: If#= 0 Alt= 0 #EPs= 2 Cls=0a(data ) Sub=00 Prot=00 Driver=serial
E: Ad=81(I) Atr=02(Bulk) MxPS= 512 Ivl=0ms
E: Ad=02(O) Atr=02(Bulk) MxPS= 512 Ivl=0ms
You must load the usbserial driver and explicitly set its parameters to configure it to recognize the gadget serial device, like this:
Load the usbserial driver and set the parameters to explicitly recognize the gadget serial device. For example:
echo 0x0525 0xA4A6 >/sys/bus/usb-serial/drivers/generic/new_id
The legacy way is to use module parameters:
The traditional method is to use module paramter.
modprobe usbserial vendor=0x0525 product=0xA4A6
If everything is working, usbserial will print a message in the system log saying something like “Gadget Serial converter now attached to ttyUSB0”.
If everything is working, usbserial will leave some message in the system log, such as “Gadget Serial converter now attached to ttyUSB0”.
Testing with Minicom or HyperTerminal
Once the gadget serial driver and the host driver are both installed, and a USB cable connects the gadget device to the host, you should be able to communicate over USB between the gadget and host systems. You can use minicom or HyperTerminal to try this out.
Once both the Gadget serial driver and the host driver are installed and the gadget device and host are connected via a USB cable, it will be possible to communicate between the gadget and the host system via USB. You can try minicon and HyperTerminal.
On the gadget side run “minicom -s” to configure a new minicom session. Under “Serial port setup” set “/dev/ttygserial” as the “Serial Device”. Set baud rate, data bits, parity, and stop bits, to 9600, 8, none, and 1–these settings mostly do not matter. Under “Modem and dialing” erase all the modem and dialing strings.
By executing "minicon -s" with Gadget size, a new minicon session will be set. Under "Serial port setup", set "/ dev / ttygserial" to "Serial Device". Set the baud rate, data bits, parity and stop bits to 9600, 8, none 1-these setting, respectively. These settings are almost irrelevant. In "Modem and dialing", delete all modems and dialing strings.
On a Linux host running the ACM driver, configure minicom similarly but use “/dev/ttyACM0” as the “Serial Device”. (If you have other ACM devices connected, change the device name appropriately.)
Set the minicon in the same way on the Linux host running the ACM driver. At this time, use "/ dev / ttyACM0" for "Serial Device". (If you have another ACM device connected, the device name will probably change).
On a Linux host running the USB generic serial driver, configure minicom similarly, but use “/dev/ttyUSB0” as the “Serial Device”. (If you have other USB serial devices connected, change the device name appropriately.)
For Linux hosts running the USB generic serial driver, set minicom in the same way. However, please use "/ dev / ttyUSB0" as "Serial Device". (If you have another USB serial device connected, the device name will probably change).
On a Windows host configure a new HyperTerminal session to use the COM port assigned to Gadget Serial. The “Port Settings” will be set automatically when HyperTerminal connects to the gadget serial device, so you can leave them set to the default values–these settings mostly do not matter.
For Windows host, set up a new HyperTerminal session and use the COM port with Gadget Serial assigned. "Port Settings" will be set automatically when HyperTerminal gadget serial device, so it will be separated from the default setting. These are not that important.
With minicom configured and running on the gadget side and with minicom or HyperTerminal configured and running on the host side, you should be able to send data back and forth between the gadget side and host side systems. Anything you type on the terminal window on the gadget side should appear in the terminal window on the host side and vice versa.
If you configure and execute a minicon with gadget size, and then configure and execute a minicon or HypertTerminal on the host side, you can send and receive data between the systems on the Gadget side and Host side. What you enter in the terminal window on the gadget side is displayed in the terminal window on the host side. The reverse is also true. ,
Originally, it is a part of the Linux Kernel source code, so it will be treated as GPLv2 (recognition that it should be).
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
Recommended Posts