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.
Le pilote série du gadget est activé depuis le noyau Linux 2.4, mais ce document suppose que vous utilisez le pilote série du gadget version 2.3 ou ultérieure sur le noyau Linux 2.6.
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.
Ce document suppose que vous êtes familiarisé avec Linux et Windows, savez comment configurer et construire un noyau Linux, exécuter des utilitaires standard, utiliser minicon et HyperTerminal, et gérer les périphériques USB et série. Arrivera également. En outre, vous supposez que le gadget Linux et le pilote USB sont configurés en tant que 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.
Dans la version 2.3 du pilote, le nœud de périphérique majeur / mineur n'était pas défini statiquement. Dans un système basé sur Linux, montez sysfs avec / sys et faites correspondre les fichiers sysfs / sys / class / tty avec le nœud / dev par mbev (si BusyBox), sinon "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.
Le pilote série de gadget est un pilote de gadget USB Linux et un pilote sid de service USB. Il fonctionne sur des systèmes Linux qui ont un périphérique USB situé à côté du matériel: par exemple, avec un PDA, un système Linux embarqué ou une carte de développement USB (en bref, un micro-ordinateur connecté USB comme Arduino ou mbed). 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:
Le pilote série Gadget communique via USB avec le pilote CDC ACM ou le pilote série USB générique fonctionnant sur le PC hos.
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.
Depuis le système Linux côté périphérique, le pilote série du gadget ressemble à un périphérique seirla.
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.
Du point de vue du système côté hôte, le périphérique série du gadget ressemble à un périphérique de classe compatible CDC ACM ou à un périphérique simple spécifique au fournisseur avec un point de terminaison en masse et est utilisé comme tout autre périphérique série.
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.
Le pilote côté hôte peut être un pilote compatible ACM ou un pilote qui peut communiquer avec une simple interface d'entrée / sortie en bloc. La série du gadget est testée avec le pilote Linux ACM, le pilote Windows usbser.sys ACM ou le pilote série générique USB Linux,
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.
Lors de l'exécution du pilote série du gadget et du pilote série ACM / générique côté hôte, vous pouvez communiquer entre l'hôte et le système côté gadget s'ils sont connectés par un câble série.
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.
Le pilote série Gadget fournit uniquement une communication de données non fiable. Il ne gère pas le contrôle de flux ou de nombreuses autres fonctionnalités d'autres périphériques série courants.
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.
Pour utiliser le pilote série Gadget, vous devez définir le "Support for USB Gadgets", "USB Peripheral Controller" (par exemple net2280) et le pilote "Serial Gadget" sur le noyau côté gadget Linux. Tous ces éléments sont répertoriés sous "Prise en charge des gadgets USB" lors de la configuration du noyau. Puis reconstruisez et installez le noyau et le module.
Then you must load the gadget serial driver. To load it as an ACM device (recommended for interoperability), do this:
Ensuite, vous devez charger le pilote srial du gadget. Faites cela pour charger en tant que périphérique CM (recommandé pour l'interopérabilité).
modprobe g_serial
To load it as a vendor specific bulk in/out device, do this:
Lors du chargement en tant que périphérique d'entrée / sortie en bloc spécifique au fournisseur, procédez comme suit.
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.
Cela lira également automatiquement le pilote du contrôleur de périphérique du gadget sous-jacent. Cela devrait être fait chaque fois que le système Linux côté gadget est redémarré. Ajoutez-le au script de démarrage si nécessaire.
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:
Vous devez créer un nœud de périphérique à l'aide de mdev (à partir de busybox) ou udev. Une fois ce pilote de gadget configuré, vous pouvez vous y référer en tant que nœud / dev / ttyGS0:
# 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.
Notez que le nombre majeur (253 ci-dessus) est spécifique au système. Si vous devez créer le nœud / dev manuellement, veuillez utiliser la valeur correcte dans le fichier / sys / class / tty / ttyGS0 / dev.
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.
Si vous voulez connecter le pilote de gadget tôt ou si vous voulez le rendre statique, vous pouvez exécuter "getty" dans l'entrée / etc / inittab. La ligne / dev / ttyGS0 devrait fonctionner comme n'importe quel autre pilote série.
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.
Si la série Gadget est chargée en tant que périphérique ACM, vous devez utiliser le pilote Windows ou Linux ACM du côté hôte. Le numéro de série du gadget est le site de l'appareil d'entrée / sortie en bloc S'il est chargé, vous devez utiliser le pilote série générique Linux côté hôte. Suivez les étapes ci-dessous pour installer le pilote côté hôte.
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.
Pour utiliser le pilote Windows ACM, vous devez disposer d'un fichier «linux-cdc-acm.inf» (fourni dans ce document) pris en charge par toutes les dernières versions de 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.
Lorsque le pilote série du gadget est chargé et que le périphérique USB est connecté à l'hôte Windows avec un câble USB, Windows reconnaît le périphérique série dadget et demande au pilote. Indique à Windows de trouver le pilote dans le dossier contenant le fichier "linux-cdc-acm.inf".
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.
Par exemple, sous Windows XP, l '«Assistant Ajout de nouveau matériel détecté» démarre lorsque le périphérique série du gadget est installé pour la première fois. Sélectionnez «Installer à partir d'une liste ou d'un emplacement spécifique (avancé)». Sur l'écran suivant, sélectionnez "Inclure cet emplacement dans la recherche" et entrez le chemin ou recherchez le chemin contenant le fichier "linux-cdc-acn.inf". Windows avertit que le pilote Gadget Serial n'a pas passé la certification du logo Windows, mais sélectionne «Continuer quand même» pour terminer l'installation du pilote.
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.
Sous Windows XP, lorsque vous ouvrez l'entrée «Ports (COM & LPT)» depuis «Device Manager» (sous «Control Panel», «System», «Hardware»), «Gadget Serial» est le port COM. Il peut être trouvé comme un pilote.
To uninstall the Windows XP driver for “Gadget Serial”, right click on the “Gadget Serial” entry in the “Device Manager” and select “Uninstall”.
Pour désinstaller le pilote Windows XP pour "Gadget Serial", faites un clic droit sur l'entrée "Gadget Serial" dans "Device Manager" et sélectionnez "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”.
Pour utiliser le pilote Linux ACM, définissez «Prise en charge de l'USB côté hôte» et «Prise en charge du modem USB (CDC ACM)» dans le noyau côté hôte Linux.
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:
Une fois que le pilote série du gadget est chargé et que le périphérique USB et l'hôte Linux sont connectés avec un câble USB, le système hôte reconnaîtra le périphérique série du gadget. Par exemple, commande:
cat /sys/kernel/debug/usb/devices
should show something like this::
En conséquence, vous verrez le résultat suivant.
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.
Si le système Linux côté hôte est correctement configuré, le pilote ACM doit se charger automatiquement. La commande "lsmod" indique que le module "acm" est chargé.
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”.
Pour utiliser le pilote Linux ACM, définissez «Prise en charge de l'USB côté hôte», «Prise en charge du convertisseur série USB» et «Prise en charge du modem USB (CDC ACM)» dans le noyau côté hôte Linux.
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:
Une fois que le pilote série du gadget est chargé et que le périphérique USB et l'hôte Linux sont connectés avec un câble USB, le système hôte reconnaîtra le périphérique série du gadget. Par exemple, commande:
cat /sys/kernel/debug/usb/devices
should show something like this::
En conséquence, vous verrez le résultat suivant.
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:
Chargez le pilote usbserial et définissez les paramètres pour reconnaître explicitement le périphérique série du gadget. Par exemple:
echo 0x0525 0xA4A6 >/sys/bus/usb-serial/drivers/generic/new_id
The legacy way is to use module parameters:
La méthode traditionnelle utilise le paramètre de module.
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”.
Si tout fonctionne, usbserial laissera un message dans le journal système, tel que «Gadget Serial converter now attach 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.
Une fois que le pilote série et le pilote hôte du gadget sont installés et que le périphérique et l'hôte du gadget sont connectés par un câble USB, il sera possible de communiquer entre le gadget et le système hôte via USB. Vous pouvez essayer minicon et 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.
En exécutant "minicon -s" avec la taille du gadget, une nouvelle session minicon sera définie. Sous «Configuration du port série», définissez «/ dev / ttygserial» sur «Périphérique série». Réglez le débit en bauds, les bits de données, la parité et les bits d'arrêt sur 9600, 8, aucun paramètre 1-ces, respectivement. Ces paramètres ne sont presque pas pertinents. Dans "Modem et numérotation", supprimez tous les modes et chaînes de numérotation.
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.)
Définissez le minicon de la même manière sur l'hôte Linux exécutant le pilote ACM. À ce stade, utilisez «/ dev / ttyACM0» pour «Périphérique série». (Si vous avez un autre appareil ACM connecté, le nom de l'appareil changera probablement).
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.)
Pour les hôtes Linux exécutant le pilote série générique USB, définissez minicom de la même manière. Cependant, utilisez "/ dev / ttyUSB0" comme "Périphérique série". (Si vous avez un autre périphérique série USB connecté, le nom du périphérique changera probablement).
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.
Sur l'hôte Windows, configurez une nouvelle session HyperTerminal et utilisez le port COM avec Gadget Serial attribué. "Paramètres du port" sera défini automatiquement lorsque le périphérique série du gadget HyperTerminal, il sera donc séparé du paramètre par défaut. Ce ne sont pas si importants.
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.
Si vous configurez et exécutez un minicon avec la taille du gadget, puis configurez et exécutez un minicon ou un HypertTerminal du côté hôte, vous pouvez envoyer et recevoir des données entre les systèmes du côté gadget et du côté hôte. Ce que vous entrez dans la fenêtre du terminal du côté du gadget s'affiche dans la fenêtre du terminal du côté de l'hôte. L'inverse est également vrai. ,
À l'origine, il fait partie du code source du noyau Linux, il sera donc traité comme GPLv2 (reconnaissance qu'il devrait l'être).
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