code:
=============================
USB 7-Segment Numeric Display
=============================

Manufactured by Delcom Engineering

Device Information
------------------
USB VENDOR_ID	0x0fc5
USB PRODUCT_ID	0x1227
Both the 6 character and 8 character displays have PRODUCT_ID,
and according to Delcom Engineering no queryable information
can be obtained from the device to tell them apart.

Device Modes
------------
By default, the driver assumes the display is only 6 characters
The mode for 6 characters is:

	MSB 0x06; LSB 0x3f

For the 8 character display:

	MSB 0x08; LSB 0xff

The device can accept "text" either in raw, hex, or ascii textmode.
raw controls each segment manually,
hex expects a value between 0-15 per character,
ascii expects a value between '0'-'9' and 'A'-'F'.
The default is ascii.

Device Operation
----------------
1.	Turn on the device:
	echo 1 > /sys/bus/usb/.../powered
2.	Set the device's mode:
	echo $mode_msb > /sys/bus/usb/.../mode_msb
	echo $mode_lsb > /sys/bus/usb/.../mode_lsb
3.	Set the textmode:
	echo $textmode > /sys/bus/usb/.../textmode
4.	set the text (for example):
	echo "123ABC" > /sys/bus/usb/.../text (ascii)
	echo "A1B2" > /sys/bus/usb/.../text (ascii)
	echo -ne "\x01\x02\x03" > /sys/bus/usb/.../text (hex)
5.	Set the decimal places.
	The device has either 6 or 8 decimal points.
	to set the nth decimal place calculate 10 ** n
	and echo it in to /sys/bus/usb/.../decimals
	To set multiple decimals points sum up each power.
	For example, to set the 0th and 3rd decimal place
	echo 1001 > /sys/bus/usb/.../decimals


code:
================
mtouchusb driver
================

Changes
=======

- 0.3 - Created based off of scanner & INSTALL from the original touchscreen
  driver on freecode (http://freecode.com/projects/3mtouchscreendriver)
- Amended for linux-2.4.18, then 2.4.19

- 0.5 - Complete rewrite using Linux Input in 2.6.3
  Unfortunately no calibration support at this time

- 1.4 - Multiple changes to support the EXII 5000UC and house cleaning
  Changed reset from standard USB dev reset to vendor reset
  Changed data sent to host from compensated to raw coordinates
  Eliminated vendor/product module params
  Performed multiple successful tests with an EXII-5010UC

Supported Hardware
==================

::

        All controllers have the Vendor: 0x0596 & Product: 0x0001

        Controller Description          Part Number
        ------------------------------------------------------

        USB Capacitive - Pearl Case     14-205  (Discontinued)
        USB Capacitive - Black Case     14-124  (Discontinued)
        USB Capacitive - No Case        14-206  (Discontinued)

        USB Capacitive - Pearl Case     EXII-5010UC
        USB Capacitive - Black Case     EXII-5030UC
        USB Capacitive - No Case        EXII-5050UC

Driver Notes
============

Installation is simple, you only need to add Linux Input, Linux USB, and the
driver to the kernel.  The driver can also be optionally built as a module.

This driver appears to be one of possible 2 Linux USB Input Touchscreen
drivers.  Although 3M produces a binary only driver available for
download, I persist in updating this driver since I would like to use the
touchscreen for embedded apps using QTEmbedded, DirectFB, etc. So I feel the
logical choice is to use Linux Input.

Currently there is no way to calibrate the device via this driver.  Even if
the device could be calibrated, the driver pulls to raw coordinate data from
the controller.  This means calibration must be performed within the
userspace.

The controller screen resolution is now 0 to 16384 for both X and Y reporting
the raw touch data.  This is the same for the old and new capacitive USB
controllers.

Perhaps at some point an abstract function will be placed into evdev so
generic functions like calibrations, resets, and vendor information can be
requested from the userspace (And the drivers would handle the vendor specific
tasks).

TODO
====

Implement a control urb again to handle requests to and from the device
such as calibration, etc once/if it becomes available.

Disclaimer
==========

I am not a MicroTouch/3M employee, nor have I ever been.  3M does not support
this driver!  If you want touch drivers only supported within X, please go to:

http://www.3m.com/3MTouchSystems/

Thanks
======

A huge thank you to 3M Touch Systems for the EXII-5010UC controllers for
testing!

repo_name: angery/linux


code:
====
OHCI
====

23-Aug-2002

The "ohci-hcd" driver is a USB Host Controller Driver (HCD) that is derived
from the "usb-ohci" driver from the 2.4 kernel series.  The "usb-ohci" code
was written primarily by Roman Weissgaerber <weissg@vienna.at> but with
contributions from many others (read its copyright/licencing header).

It supports the "Open Host Controller Interface" (OHCI), which standardizes
hardware register protocols used to talk to USB 1.1 host controllers.  As
compared to the earlier "Universal Host Controller Interface" (UHCI) from
Intel, it pushes more intelligence into the hardware.  USB 1.1 controllers
from vendors other than Intel and VIA generally use OHCI.

Changes since the 2.4 kernel include

	- improved robustness; bugfixes; and less overhead
	- supports the updated and simplified usbcore APIs
	- interrupt transfers can be larger, and can be queued
	- less code, by using the upper level "hcd" framework
	- supports some non-PCI implementations of OHCI
	- ... more

The "ohci-hcd" driver handles all USB 1.1 transfer types.  Transfers of all
types can be queued.  That was also true in "usb-ohci", except for interrupt
transfers.  Previously, using periods of one frame would risk data loss due
to overhead in IRQ processing.  When interrupt transfers are queued, those
risks can be minimized by making sure the hardware always has transfers to
work on while the OS is getting around to the relevant IRQ processing.

- David Brownell
  <dbrownell@users.sourceforge.net>


code:
==============
USB Raw Gadget
==============

USB Raw Gadget is a gadget driver that gives userspace low-level control over
the gadget's communication process.

Like any other gadget driver, Raw Gadget implements USB devices via the
USB gadget API. Unlike most gadget drivers, Raw Gadget does not implement
any concrete USB functions itself but requires userspace to do that.

Raw Gadget is currently a strictly debugging feature and should not be used
in production. Use GadgetFS instead.

Enabled with CONFIG_USB_RAW_GADGET.

Comparison to GadgetFS
~~~~~~~~~~~~~~~~~~~~~~

Raw Gadget is similar to GadgetFS but provides more direct access to the
USB gadget layer for userspace. The key differences are:

1. Raw Gadget passes every USB request to userspace to get a response, while
   GadgetFS responds to some USB requests internally based on the provided
   descriptors. Note that the UDC driver might respond to some requests on
   its own and never forward them to the gadget layer.

2. Raw Gadget allows providing arbitrary data as responses to USB requests,
   while GadgetFS performs sanity checks on the provided USB descriptors.
   This makes Raw Gadget suitable for fuzzing by providing malformed data as
   responses to USB requests.

3. Raw Gadget provides a way to select a UDC device/driver to bind to,
   while GadgetFS currently binds to the first available UDC. This allows
   having multiple Raw Gadget instances bound to different UDCs.

4. Raw Gadget explicitly exposes information about endpoints addresses and
   capabilities. This allows the user to write UDC-agnostic gadgets.

5. Raw Gadget has an ioctl-based interface instead of a filesystem-based
   one.

Userspace interface
~~~~~~~~~~~~~~~~~~~

The user can interact with Raw Gadget by opening ``/dev/raw-gadget`` and
issuing ioctl calls; see the comments in include/uapi/linux/usb/raw_gadget.h
for details. Multiple Raw Gadget instances (bound to different UDCs) can be
used at the same time.

A typical usage scenario of Raw Gadget:

1. Create a Raw Gadget instance by opening ``/dev/raw-gadget``.
2. Initialize the instance via ``USB_RAW_IOCTL_INIT``.
3. Launch the instance with ``USB_RAW_IOCTL_RUN``.
4. In a loop issue ``USB_RAW_IOCTL_EVENT_FETCH`` to receive events from
   Raw Gadget and react to those depending on what kind of USB gadget must
   be implemented.

Note that some UDC drivers have fixed addresses assigned to endpoints, and
therefore arbitrary endpoint addresses cannot be used in the descriptors.
Nevertheless, Raw Gadget provides a UDC-agnostic way to write USB gadgets.
Once ``USB_RAW_EVENT_CONNECT`` is received via ``USB_RAW_IOCTL_EVENT_FETCH``,
``USB_RAW_IOCTL_EPS_INFO`` can be used to find out information about the
endpoints that the UDC driver has. Based on that, userspace must choose UDC
endpoints for the gadget and assign addresses in the endpoint descriptors
correspondingly.

Raw Gadget usage examples and a test suite:

https://github.com/xairy/raw-gadget

Internal details
~~~~~~~~~~~~~~~~

Every Raw Gadget endpoint read/write ioctl submits a USB request and waits
until its completion. This is done deliberately to assist with coverage-guided
fuzzing by having a single syscall fully process a single USB request. This
feature must be kept in the implementation.

Potential future improvements
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

- Report more events (suspend, resume, etc.) through
  ``USB_RAW_IOCTL_EVENT_FETCH``.

- Support ``O_NONBLOCK`` I/O. This would be another mode of operation, where
  Raw Gadget would not wait until the completion of each USB request.

- Support USB 3 features (accept SS endpoint companion descriptor when
  enabling endpoints; allow providing ``stream_id`` for bulk transfers).

- Support ISO transfer features (expose ``frame_number`` for completed
  requests).


code:
Linux CDC ACM inf
-----------------

.. include:: linux-cdc-acm.inf
    :literal:

Linux inf
---------

.. include:: linux.inf
    :literal:

USB devfs drop permissions source
---------------------------------

.. literalinclude:: usbdevfs-drop-permissions.c
    :language: c

Credits
-------

.. include:: CREDITS
    :literal:


code:
==============
USB references
==============

2008-Mar-7

For USB help other than the readme files that are located in
`Documentation/usb/*`, see the following:

- Linux-USB project:  http://www.linux-usb.org
  mirrors at          http://usb.in.tum.de/linux-usb/
  and                 http://it.linux-usb.org
- Linux USB Guide:    http://linux-usb.sourceforge.net
- Linux-USB device overview (working devices and drivers):
  http://www.qbik.ch/usb/devices/

The Linux-USB mailing list is at linux-usb@vger.kernel.org


code:
==========
USB serial
==========

Introduction
============

  The USB serial driver currently supports a number of different USB to
  serial converter products, as well as some devices that use a serial
  interface from userspace to talk to the device.

  See the individual product section below for specific information about
  the different devices.

Configuration
=============

  Currently the driver can handle up to 256 different serial interfaces at
  one time.

    The major number that the driver uses is 188 so to use the driver,
    create the following nodes::

	mknod /dev/ttyUSB0 c 188 0
	mknod /dev/ttyUSB1 c 188 1
	mknod /dev/ttyUSB2 c 188 2
	mknod /dev/ttyUSB3 c 188 3
		.
		.
		.
	mknod /dev/ttyUSB254 c 188 254
	mknod /dev/ttyUSB255 c 188 255

  When the device is connected and recognized by the driver, the driver
  will print to the system log, which node(s) the device has been bound
  to.

Specific Devices Supported
==========================

ConnectTech WhiteHEAT 4 port converter
--------------------------------------

  ConnectTech has been very forthcoming with information about their
  device, including providing a unit to test with.

  The driver is officially supported by Connect Tech Inc.
  http://www.connecttech.com

  For any questions or problems with this driver, please contact
  Connect Tech's Support Department at support@connecttech.com

HandSpring Visor, Palm USB, and Clié USB driver
-----------------------------------------------

  This driver works with all HandSpring USB, Palm USB, and Sony Clié USB
  devices.

  Only when the device tries to connect to the host, will the device show
  up to the host as a valid USB device. When this happens, the device is
  properly enumerated, assigned a port, and then communication _should_ be
  possible. The driver cleans up properly when the device is removed, or
  the connection is canceled on the device.

  NOTE:
    This means that in order to talk to the device, the sync button must be
    pressed BEFORE trying to get any program to communicate to the device.
    This goes against the current documentation for pilot-xfer and other
    packages, but is the only way that it will work due to the hardware
    in the device.

  When the device is connected, try talking to it on the second port
  (this is usually /dev/ttyUSB1 if you do not have any other usb-serial
  devices in the system.) The system log should tell you which port is
  the port to use for the HotSync transfer. The "Generic" port can be used
  for other device communication, such as a PPP link.

  For some Sony Clié devices, /dev/ttyUSB0 must be used to talk to the
  device.  This is true for all OS version 3.5 devices, and most devices
  that have had a flash upgrade to a newer version of the OS.  See the
  kernel system log for information on which is the correct port to use.

  If after pressing the sync button, nothing shows up in the system log,
  try resetting the device, first a hot reset, and then a cold reset if
  necessary.  Some devices need this before they can talk to the USB port
  properly.

  Devices that are not compiled into the kernel can be specified with module
  parameters.  e.g. modprobe visor vendor=0x54c product=0x66

  There is a webpage and mailing lists for this portion of the driver at:
  http://sourceforge.net/projects/usbvisor/

  For any questions or problems with this driver, please contact Greg
  Kroah-Hartman at greg@kroah.com

PocketPC PDA Driver
-------------------

  This driver can be used to connect to Compaq iPAQ, HP Jornada, Casio EM500
  and other PDAs running Windows CE 3.0 or PocketPC 2002 using a USB
  cable/cradle.
  Most devices supported by ActiveSync are supported out of the box.
  For others, please use module parameters to specify the product and vendor
  id. e.g. modprobe ipaq vendor=0x3f0 product=0x1125

  The driver presents a serial interface (usually on /dev/ttyUSB0) over
  which one may run ppp and establish a TCP/IP link to the PDA. Once this
  is done, you can transfer files, backup, download email etc. The most
  significant advantage of using USB is speed - I can get 73 to 113
  kbytes/sec for download/upload to my iPAQ.

  This driver is only one of a set of components required to utilize
  the USB connection. Please visit http://synce.sourceforge.net which
  contains the necessary packages and a simple step-by-step howto.

  Once connected, you can use Win CE programs like ftpView, Pocket Outlook
  from the PDA and xcerdisp, synce utilities from the Linux side.

  To use Pocket IE, follow the instructions given at
  http://www.tekguru.co.uk/EM500/usbtonet.htm to achieve the same thing
  on Win98. Omit the proxy server part; Linux is quite capable of forwarding
  packets unlike Win98. Another modification is required at least for the
  iPAQ - disable autosync by going to the Start/Settings/Connections menu
  and unchecking the "Automatically synchronize ..." box. Go to
  Start/Programs/Connections, connect the cable and select "usbdial" (or
  whatever you named your new USB connection). You should finally wind
  up with a "Connected to usbdial" window with status shown as connected.
  Now start up PIE and browse away.

  If it doesn't work for some reason, load both the usbserial and ipaq module
  with the module parameter "debug" set to 1 and examine the system log.
  You can also try soft-resetting your PDA before attempting a connection.

  Other functionality may be possible depending on your PDA. According to
  Wes Cilldhaire <billybobjoehenrybob@hotmail.com>, with the Toshiba E570,
  ...if you boot into the bootloader (hold down the power when hitting the
  reset button, continuing to hold onto the power until the bootloader screen
  is displayed), then put it in the cradle with the ipaq driver loaded, open
  a terminal on /dev/ttyUSB0, it gives you a "USB Reflash" terminal, which can
  be used to flash the ROM, as well as the microP code..  so much for needing
  Toshiba's $350 serial cable for flashing!! :D
  NOTE: This has NOT been tested. Use at your own risk.

  For any questions or problems with the driver, please contact Ganesh
  Varadarajan <ganesh@veritas.com>

Keyspan PDA Serial Adapter
--------------------------

  Single port DB-9 serial adapter, pushed as a PDA adapter for iMacs (mostly
  sold in Macintosh catalogs, comes in a translucent white/green dongle).
  Fairly simple device. Firmware is homebrew.
  This driver also works for the Xircom/Entrega single port serial adapter.

  Current status:

   Things that work:
     - basic input/output (tested with 'cu')
     - blocking write when serial line can't keep up
     - changing baud rates (up to 115200)
     - getting/setting modem control pins (TIOCM{GET,SET,BIS,BIC})
     - sending break (although duration looks suspect)

   Things that don't:
     - device strings (as logged by kernel) have trailing binary garbage
     - device ID isn't right, might collide with other Keyspan products
     - changing baud rates ought to flush tx/rx to avoid mangled half characters

   Big Things on the todo list:
     - parity, 7 vs 8 bits per char, 1 or 2 stop bits
     - HW flow control
     - not all of the standard USB descriptors are handled:
       Get_Status, Set_Feature, O_NONBLOCK, select()

  For any questions or problems with this driver, please contact Brian
  Warner at warner@lothar.com

Keyspan USA-series Serial Adapters
----------------------------------

  Single, Dual and Quad port adapters - driver uses Keyspan supplied
  firmware and is being developed with their support.

  Current status:

    The USA-18X, USA-28X, USA-19, USA-19W and USA-49W are supported and
    have been pretty thoroughly tested at various baud rates with 8-N-1
    character settings.  Other character lengths and parity setups are
    presently untested.

    The USA-28 isn't yet supported though doing so should be pretty
    straightforward.  Contact the maintainer if you require this
    functionality.

  More information is available at:

        http://www.carnationsoftware.com/carnation/Keyspan.html

  For any questions or problems with this driver, please contact Hugh
  Blemings at hugh@misc.nu

FTDI Single Port Serial Driver
------------------------------

  This is a single port DB-25 serial adapter.

  Devices supported include:

                - TripNav TN-200 USB GPS
                - Navis Engineering Bureau CH-4711 USB GPS

  For any questions or problems with this driver, please contact Bill Ryder.

ZyXEL omni.net lcd plus ISDN TA
-------------------------------

  This is an ISDN TA. Please report both successes and troubles to
  azummo@towertech.it

Cypress M8 CY4601 Family Serial Driver
--------------------------------------

  This driver was in most part developed by Neil "koyama" Whelchel.  It
  has been improved since that previous form to support dynamic serial
  line settings and improved line handling.  The driver is for the most
  part stable and has been tested on an smp machine. (dual p2)

    Chipsets supported under CY4601 family:

		CY7C63723, CY7C63742, CY7C63743, CY7C64013

    Devices supported:

		- DeLorme's USB Earthmate GPS (SiRF Star II lp arch)
		- Cypress HID->COM RS232 adapter

		Note:
			Cypress Semiconductor claims no affiliation with the
			hid->com device.

     Most devices using chipsets under the CY4601 family should
     work with the driver.  As long as they stay true to the CY4601
     usbserial specification.

    Technical notes:

        The Earthmate starts out at 4800 8N1 by default... the driver will
	upon start init to this setting.  usbserial core provides the rest
	of the termios settings, along with some custom termios so that the
	output is in proper format and parsable.

	The device can be put into sirf mode by issuing NMEA command::

		$PSRF100,<protocol>,<baud>,<databits>,<stopbits>,<parity>*CHECKSUM
		$PSRF100,0,9600,8,1,0*0C

		It should then be sufficient to change the port termios to match this
		to begin communicating.

	As far as I can tell it supports pretty much every sirf command as
	documented online available with firmware 2.31, with some unknown
	message ids.

	The hid->com adapter can run at a maximum baud of 115200bps.  Please note
	that the device has trouble or is incapable of raising line voltage properly.
	It will be fine with null modem links, as long as you do not try to link two
	together without hacking the adapter to set the line high.

	The driver is smp safe.  Performance with the driver is rather low when using
	it for transferring files.  This is being worked on, but I would be willing to
	accept patches.  An urb queue or packet buffer would likely fit the bill here.

	If you have any questions, problems, patches, feature requests, etc. you can
	contact me here via email:

					dignome@gmail.com

		(your problems/patches can alternately be submitted to usb-devel)

Digi AccelePort Driver
----------------------

  This driver supports the Digi AccelePort USB 2 and 4 devices, 2 port
  (plus a parallel port) and 4 port USB serial converters.  The driver
  does NOT yet support the Digi AccelePort USB 8.

  This driver works under SMP with the usb-uhci driver.  It does not
  work under SMP with the uhci driver.

  The driver is generally working, though we still have a few more ioctls
  to implement and final testing and debugging to do.  The parallel port
  on the USB 2 is supported as a serial to parallel converter; in other
  words, it appears as another USB serial port on Linux, even though
  physically it is really a parallel port.  The Digi Acceleport USB 8
  is not yet supported.

  Please contact Peter Berger (pberger@brimson.com) or Al Borchers
  (alborchers@steinerpoint.com) for questions or problems with this
  driver.

Belkin USB Serial Adapter F5U103
--------------------------------

  Single port DB-9/PS-2 serial adapter from Belkin with firmware by eTEK Labs.
  The Peracom single port serial adapter also works with this driver, as
  well as the GoHubs adapter.

  Current status:

    The following have been tested and work:

      - Baud rate    300-230400
      - Data bits    5-8
      - Stop bits    1-2
      - Parity       N,E,O,M,S
      - Handshake    None, Software (XON/XOFF), Hardware (CTSRTS,CTSDTR) [1]_
      - Break        Set and clear
      - Line control Input/Output query and control [2]_

  .. [1]
         Hardware input flow control is only enabled for firmware
         levels above 2.06.  Read source code comments describing Belkin
         firmware errata.  Hardware output flow control is working for all
         firmware versions.

  .. [2]
         Queries of inputs (CTS,DSR,CD,RI) show the last
         reported state.  Queries of outputs (DTR,RTS) show the last
         requested state and may not reflect current state as set by
         automatic hardware flow control.

  TO DO List:
    - Add true modem control line query capability.  Currently tracks the
      states reported by the interrupt and the states requested.
    - Add error reporting back to application for UART error conditions.
    - Add support for flush ioctls.
    - Add everything else that is missing :)

  For any questions or problems with this driver, please contact William
  Greathouse at wgreathouse@smva.com

Empeg empeg-car Mark I/II Driver
--------------------------------

  This is an experimental driver to provide connectivity support for the
  client synchronization tools for an Empeg empeg-car mp3 player.

  Tips:
    * Don't forget to create the device nodes for ttyUSB{0,1,2,...}
    * modprobe empeg (modprobe is your friend)
    * emptool --usb /dev/ttyUSB0 (or whatever you named your device node)

  For any questions or problems with this driver, please contact Gary
  Brubaker at xavyer@ix.netcom.com

MCT USB Single Port Serial Adapter U232
---------------------------------------

  This driver is for the MCT USB-RS232 Converter (25 pin, Model No.
  U232-P25) from Magic Control Technology Corp. (there is also a 9 pin
  Model No. U232-P9). More information about this device can be found at
  the manufacturer's web-site: http://www.mct.com.tw.

  The driver is generally working, though it still needs some more testing.
  It is derived from the Belkin USB Serial Adapter F5U103 driver and its
  TODO list is valid for this driver as well.

  This driver has also been found to work for other products, which have
  the same Vendor ID but different Product IDs. Sitecom's U232-P25 serial
  converter uses Product ID 0x230 and Vendor ID 0x711 and works with this
  driver. Also, D-Link's DU-H3SP USB BAY also works with this driver.

  For any questions or problems with this driver, please contact Wolfgang
  Grandegger at wolfgang@ces.ch

Inside Out Networks Edgeport Driver
-----------------------------------

  This driver supports all devices made by Inside Out Networks, specifically
  the following models:

       - Edgeport/4
       - Rapidport/4
       - Edgeport/4t
       - Edgeport/2
       - Edgeport/4i
       - Edgeport/2i
       - Edgeport/421
       - Edgeport/21
       - Edgeport/8
       - Edgeport/8 Dual
       - Edgeport/2D8
       - Edgeport/4D8
       - Edgeport/8i
       - Edgeport/2 DIN
       - Edgeport/4 DIN
       - Edgeport/16 Dual

  For any questions or problems with this driver, please contact Greg
  Kroah-Hartman at greg@kroah.com

REINER SCT cyberJack pinpad/e-com USB chipcard reader
-----------------------------------------------------

  Interface to ISO 7816 compatible contactbased chipcards, e.g. GSM SIMs.

  Current status:

    This is the kernel part of the driver for this USB card reader.
    There is also a user part for a CT-API driver available. A site
    for downloading is TBA. For now, you can request it from the
    maintainer (linux-usb@sii.li).

  For any questions or problems with this driver, please contact
  linux-usb@sii.li

Prolific PL2303 Driver
----------------------

  This driver supports any device that has the PL2303 chip from Prolific
  in it.  This includes a number of single port USB to serial converters,
  more than 70% of USB GPS devices (in 2010), and some USB UPSes. Devices
  from Aten (the UC-232) and IO-Data work with this driver, as does
  the DCU-11 mobile-phone cable.

  For any questions or problems with this driver, please contact Greg
  Kroah-Hartman at greg@kroah.com

KL5KUSB105 chipset / PalmConnect USB single-port adapter
--------------------------------------------------------

Current status:

  The driver was put together by looking at the usb bus transactions
  done by Palm's driver under Windows, so a lot of functionality is
  still missing.  Notably, serial ioctls are sometimes faked or not yet
  implemented.  Support for finding out about DSR and CTS line status is
  however implemented (though not nicely), so your favorite autopilot(1)
  and pilot-manager -daemon calls will work.  Baud rates up to 115200
  are supported, but handshaking (software or hardware) is not, which is
  why it is wise to cut down on the rate used is wise for large
  transfers until this is settled.

  See http://www.uuhaus.de/linux/palmconnect.html for up-to-date
  information on this driver.

Winchiphead CH341 Driver
------------------------

  This driver is for the Winchiphead CH341 USB-RS232 Converter. This chip
  also implements an IEEE 1284 parallel port, I2C and SPI, but that is not
  supported by the driver. The protocol was analyzed from the behaviour
  of the Windows driver, no datasheet is available at present.

  The manufacturer's website: http://www.winchiphead.com/.

  For any questions or problems with this driver, please contact
  frank@kingswood-consulting.co.uk.

Moschip MCS7720, MCS7715 driver
-------------------------------

  These chips are present in devices sold by various manufacturers, such as Syba
  and Cables Unlimited.  There may be others.  The 7720 provides two serial
  ports, and the 7715 provides one serial and one standard PC parallel port.
  Support for the 7715's parallel port is enabled by a separate option, which
  will not appear unless parallel port support is first enabled at the top-level
  of the Device Drivers config menu.  Currently only compatibility mode is
  supported on the parallel port (no ECP/EPP).

  TODO:
    - Implement ECP/EPP modes for the parallel port.
    - Baud rates higher than 115200 are currently broken.
    - Devices with a single serial port based on the Moschip MCS7703 may work
      with this driver with a simple addition to the usb_device_id table.  I
      don't have one of these devices, so I can't say for sure.

Generic Serial driver
---------------------

  If your device is not one of the above listed devices, compatible with
  the above models, you can try out the "generic" interface. This
  interface does not provide any type of control messages sent to the
  device, and does not support any kind of device flow control. All that
  is required of your device is that it has at least one bulk in endpoint,
  or one bulk out endpoint.

  To enable the generic driver to recognize your device, provide::

	echo <vid> <pid> >/sys/bus/usb-serial/drivers/generic/new_id

  where the <vid> and <pid> is replaced with the hex representation of your
  device's vendor id and product id.
  If the driver is compiled as a module you can also provide one id when
  loading the module::

	insmod usbserial vendor=0x#### product=0x####

  This driver has been successfully used to connect to the NetChip USB
  development board, providing a way to develop USB firmware without
  having to write a custom driver.

  For any questions or problems with this driver, please contact Greg
  Kroah-Hartman at greg@kroah.com

Contact
=======

  If anyone has any problems using these drivers, with any of the above
  specified products, please contact the specific driver's author listed
  above, or join the Linux-USB mailing list (information on joining the
  mailing list, as well as a link to its searchable archive is at
  http://www.linux-usb.org/ )

Greg Kroah-Hartman
greg@kroah.com


code:
#include <sys/ioctl.h>
#include <sys/types.h>
#include <sys/stat.h>
#include <fcntl.h>
#include <stdio.h>
#include <errno.h>
#include <string.h>
#include <inttypes.h>
#include <unistd.h>

#include <linux/usbdevice_fs.h>

/* For building without an updated set of headers */
#ifndef USBDEVFS_DROP_PRIVILEGES
#define USBDEVFS_DROP_PRIVILEGES		_IOW('U', 30, __u32)
#define USBDEVFS_CAP_DROP_PRIVILEGES		0x40
#endif

void drop_privileges(int fd, uint32_t mask)
{
	int res;

	res = ioctl(fd, USBDEVFS_DROP_PRIVILEGES, &mask);
	if (res)
		printf("ERROR: USBDEVFS_DROP_PRIVILEGES returned %d\n", res);
	else
		printf("OK: privileges dropped!\n");
}

void reset_device(int fd)
{
	int res;

	res = ioctl(fd, USBDEVFS_RESET);
	if (!res)
		printf("OK: USBDEVFS_RESET succeeded\n");
	else
		printf("ERROR: reset failed! (%d - %s)\n",
		       -res, strerror(-res));
}

void claim_some_intf(int fd)
{
	int i, res;

	for (i = 0; i < 4; i++) {
		res = ioctl(fd, USBDEVFS_CLAIMINTERFACE, &i);
		if (!res)
			printf("OK: claimed if %d\n", i);
		else
			printf("ERROR claiming if %d (%d - %s)\n",
			       i, -res, strerror(-res));
	}
}

int main(int argc, char *argv[])
{
	uint32_t mask, caps;
	int c, fd;

	fd = open(argv[1], O_RDWR);
	if (fd < 0) {
		printf("Failed to open file\n");
		goto err_fd;
	}

	/*
	 * check if dropping privileges is supported,
	 * bail on systems where the capability is not present
	 */
	ioctl(fd, USBDEVFS_GET_CAPABILITIES, &caps);
	if (!(caps & USBDEVFS_CAP_DROP_PRIVILEGES)) {
		printf("DROP_PRIVILEGES not supported\n");
		goto err;
	}

	/*
	 * Drop privileges but keep the ability to claim all
	 * free interfaces (i.e., those not used by kernel drivers)
	 */
	drop_privileges(fd, -1U);

	printf("Available options:\n"
		"[0] Exit now\n"
		"[1] Reset device. Should fail if device is in use\n"
		"[2] Claim 4 interfaces. Should succeed where not in use\n"
		"[3] Narrow interface permission mask\n"
		"Which option shall I run?: ");

	while (scanf("%d", &c) == 1) {
		switch (c) {
		case 0:
			goto exit;
		case 1:
			reset_device(fd);
			break;
		case 2:
			claim_some_intf(fd);
			break;
		case 3:
			printf("Insert new mask: ");
			scanf("%x", &mask);
			drop_privileges(fd, mask);
			break;
		default:
			printf("I don't recognize that\n");
		}

		printf("Which test shall I run next?: ");
	}

exit:
	close(fd);
	return 0;

err:
	close(fd);
err_fd:
	return 1;
}


code:
===============
USB/IP protocol
===============

Architecture
============

The USB/IP protocol follows a server/client architecture. The server exports the
USB devices and the clients import them. The device driver for the exported
USB device runs on the client machine.

The client may ask for the list of the exported USB devices. To get the list the
client opens a TCP/IP connection to the server, and sends an OP_REQ_DEVLIST
packet on top of the TCP/IP connection (so the actual OP_REQ_DEVLIST may be sent
in one or more pieces at the low level transport layer). The server sends back
the OP_REP_DEVLIST packet which lists the exported USB devices. Finally the
TCP/IP connection is closed.

::

 virtual host controller                                 usb host
      "client"                                           "server"
  (imports USB devices)                             (exports USB devices)
          |                                                 |
          |                  OP_REQ_DEVLIST                 |
          | ----------------------------------------------> |
          |                                                 |
          |                  OP_REP_DEVLIST                 |
          | <---------------------------------------------- |
          |                                                 |

Once the client knows the list of exported USB devices it may decide to use one
of them. First the client opens a TCP/IP connection to the server and
sends an OP_REQ_IMPORT packet. The server replies with OP_REP_IMPORT. If the
import was successful the TCP/IP connection remains open and will be used
to transfer the URB traffic between the client and the server. The client may
send two types of packets: the USBIP_CMD_SUBMIT to submit an URB, and
USBIP_CMD_UNLINK to unlink a previously submitted URB. The answers of the
server may be USBIP_RET_SUBMIT and USBIP_RET_UNLINK respectively.

::

 virtual host controller                                 usb host
      "client"                                           "server"
  (imports USB devices)                             (exports USB devices)
          |                                                 |
          |                  OP_REQ_IMPORT                  |
          | ----------------------------------------------> |
          |                                                 |
          |                  OP_REP_IMPORT                  |
          | <---------------------------------------------- |
          |                                                 |
          |                                                 |
          |            USBIP_CMD_SUBMIT(seqnum = n)         |
          | ----------------------------------------------> |
          |                                                 |
          |            USBIP_RET_SUBMIT(seqnum = n)         |
          | <---------------------------------------------- |
          |                        .                        |
          |                        :                        |
          |                                                 |
          |            USBIP_CMD_SUBMIT(seqnum = m)         |
          | ----------------------------------------------> |
          |                                                 |
          |            USBIP_CMD_SUBMIT(seqnum = m+1)       |
          | ----------------------------------------------> |
          |                                                 |
          |            USBIP_CMD_SUBMIT(seqnum = m+2)       |
          | ----------------------------------------------> |
          |                                                 |
          |            USBIP_RET_SUBMIT(seqnum = m)         |
          | <---------------------------------------------- |
          |                                                 |
          |            USBIP_CMD_SUBMIT(seqnum = m+3)       |
          | ----------------------------------------------> |
          |                                                 |
          |            USBIP_RET_SUBMIT(seqnum = m+1)       |
          | <---------------------------------------------- |
          |                                                 |
          |            USBIP_CMD_SUBMIT(seqnum = m+4)       |
          | ----------------------------------------------> |
          |                                                 |
          |            USBIP_RET_SUBMIT(seqnum = m+2)       |
          | <---------------------------------------------- |
          |                        .                        |
          |                        :                        |

For UNLINK, note that after a successful USBIP_RET_UNLINK, the unlinked URB
submission would not have a corresponding USBIP_RET_SUBMIT (this is explained in
function stub_recv_cmd_unlink of drivers/usb/usbip/stub_rx.c).

::

 virtual host controller                                 usb host
      "client"                                           "server"
  (imports USB devices)                             (exports USB devices)
          |                                                 |
          |            USBIP_CMD_SUBMIT(seqnum = p)         |
          | ----------------------------------------------> |
          |                                                 |
          |               USBIP_CMD_UNLINK                  |
          |         (seqnum = p+1, unlink_seqnum = p)       |
          | ----------------------------------------------> |
          |                                                 |
          |               USBIP_RET_UNLINK                  |
          |        (seqnum = p+1, status = -ECONNRESET)     |
          | <---------------------------------------------- |
          |                                                 |
          |         Note: No USBIP_RET_SUBMIT(seqnum = p)   |
          | <--X---X---X---X---X---X---X---X---X---X---X--- |
          |                        .                        |
          |                        :                        |
          |                                                 |
          |            USBIP_CMD_SUBMIT(seqnum = q)         |
          | ----------------------------------------------> |
          |                                                 |
          |            USBIP_RET_SUBMIT(seqnum = q)         |
          | <---------------------------------------------- |
          |                                                 |
          |               USBIP_CMD_UNLINK                  |
          |         (seqnum = q+1, unlink_seqnum = q)       |
          | ----------------------------------------------> |
          |                                                 |
          |               USBIP_RET_UNLINK                  |
          |           (seqnum = q+1, status = 0)            |
          | <---------------------------------------------- |
          |                                                 |

The fields are in network (big endian) byte order meaning that the most significant
byte (MSB) is stored at the lowest address.

Protocol Version
================

The documented USBIP version is v1.1.1. The binary representation of this
version in message headers is 0x0111.

This is defined in tools/usb/usbip/configure.ac

Message Format
==============

OP_REQ_DEVLIST:
	Retrieve the list of exported USB devices.

+-----------+--------+------------+---------------------------------------------------+
| Offset    | Length | Value      | Description                                       |
+===========+========+============+===================================================+
| 0         | 2      |            | USBIP version                                     |
+-----------+--------+------------+---------------------------------------------------+
| 2         | 2      | 0x8005     | Command code: Retrieve the list of exported USB   |
|           |        |            | devices.                                          |
+-----------+--------+------------+---------------------------------------------------+
| 4         | 4      | 0x00000000 | Status: unused, shall be set to 0                 |
+-----------+--------+------------+---------------------------------------------------+

OP_REP_DEVLIST:
	Reply with the list of exported USB devices.

+-----------+--------+------------+---------------------------------------------------+
| Offset    | Length | Value      | Description                                       |
+===========+========+============+===================================================+
| 0         | 2      |            | USBIP version                                     |
+-----------+--------+------------+---------------------------------------------------+
| 2         | 2      | 0x0005     | Reply code: The list of exported USB devices.     |
+-----------+--------+------------+---------------------------------------------------+
| 4         | 4      | 0x00000000 | Status: 0 for OK                                  |
+-----------+--------+------------+---------------------------------------------------+
| 8         | 4      | n          | Number of exported devices: 0 means no exported   |
|           |        |            | devices.                                          |
+-----------+--------+------------+---------------------------------------------------+
| 0x0C      |        |            | From now on the exported n devices are described, |
|           |        |            | if any. If no devices are exported the message    |
|           |        |            | ends with the previous "number of exported        |
|           |        |            | devices" field.                                   |
+-----------+--------+------------+---------------------------------------------------+
|           | 256    |            | path: Path of the device on the host exporting the|
|           |        |            | USB device, string closed with zero byte, e.g.    |
|           |        |            | "/sys/devices/pci0000:00/0000:00:1d.1/usb3/3-2"   |
|           |        |            | The unused bytes shall be filled with zero        |
|           |        |            | bytes.                                            |
+-----------+--------+------------+---------------------------------------------------+
| 0x10C     | 32     |            | busid: Bus ID of the exported device, string      |
|           |        |            | closed with zero byte, e.g. "3-2". The unused     |
|           |        |            | bytes shall be filled with zero bytes.            |
+-----------+--------+------------+---------------------------------------------------+
| 0x12C     | 4      |            | busnum                                            |
+-----------+--------+------------+---------------------------------------------------+
| 0x130     | 4      |            | devnum                                            |
+-----------+--------+------------+---------------------------------------------------+
| 0x134     | 4      |            | speed                                             |
+-----------+--------+------------+---------------------------------------------------+
| 0x138     | 2      |            | idVendor                                          |
+-----------+--------+------------+---------------------------------------------------+
| 0x13A     | 2      |            | idProduct                                         |
+-----------+--------+------------+---------------------------------------------------+
| 0x13C     | 2      |            | bcdDevice                                         |
+-----------+--------+------------+---------------------------------------------------+
| 0x13E     | 1      |            | bDeviceClass                                      |
+-----------+--------+------------+---------------------------------------------------+
| 0x13F     | 1      |            | bDeviceSubClass                                   |
+-----------+--------+------------+---------------------------------------------------+
| 0x140     | 1      |            | bDeviceProtocol                                   |
+-----------+--------+------------+---------------------------------------------------+
| 0x141     | 1      |            | bConfigurationValue                               |
+-----------+--------+------------+---------------------------------------------------+
| 0x142     | 1      |            | bNumConfigurations                                |
+-----------+--------+------------+---------------------------------------------------+
| 0x143     | 1      |            | bNumInterfaces                                    |
+-----------+--------+------------+---------------------------------------------------+
| 0x144     |        | m_0        | From now on each interface is described, all      |
|           |        |            | together bNumInterfaces times, with the following |
|           |        |            | 4 fields:                                         |
+-----------+--------+------------+---------------------------------------------------+
|           | 1      |            | bInterfaceClass                                   |
+-----------+--------+------------+---------------------------------------------------+
| 0x145     | 1      |            | bInterfaceSubClass                                |
+-----------+--------+------------+---------------------------------------------------+
| 0x146     | 1      |            | bInterfaceProtocol                                |
+-----------+--------+------------+---------------------------------------------------+
| 0x147     | 1      |            | padding byte for alignment, shall be set to zero  |
+-----------+--------+------------+---------------------------------------------------+
| 0xC +     |        |            | The second exported USB device starts at i=1      |
| i*0x138 + |        |            | with the path field.                              |
| m_(i-1)*4 |        |            |                                                   |
+-----------+--------+------------+---------------------------------------------------+

OP_REQ_IMPORT:
	Request to import (attach) a remote USB device.

+-----------+--------+------------+---------------------------------------------------+
| Offset    | Length | Value      | Description                                       |
+===========+========+============+===================================================+
| 0         | 2      |            | USBIP version                                     |
+-----------+--------+------------+---------------------------------------------------+
| 2         | 2      | 0x8003     | Command code: import a remote USB device.         |
+-----------+--------+------------+---------------------------------------------------+
| 4         | 4      | 0x00000000 | Status: unused, shall be set to 0                 |
+-----------+--------+------------+---------------------------------------------------+
| 8         | 32     |            | busid: the busid of the exported device on the    |
|           |        |            | remote host. The possible values are taken        |
|           |        |            | from the message field OP_REP_DEVLIST.busid.      |
|           |        |            | A string closed with zero, the unused bytes       |
|           |        |            | shall be filled with zeros.                       |
+-----------+--------+------------+---------------------------------------------------+

OP_REP_IMPORT:
	Reply to import (attach) a remote USB device.

+-----------+--------+------------+---------------------------------------------------+
| Offset    | Length | Value      | Description                                       |
+===========+========+============+===================================================+
| 0         | 2      |            | USBIP version                                     |
+-----------+--------+------------+---------------------------------------------------+
| 2         | 2      | 0x0003     | Reply code: Reply to import.                      |
+-----------+--------+------------+---------------------------------------------------+
| 4         | 4      | 0x00000000 | Status:                                           |
|           |        |            |                                                   |
|           |        |            |   - 0 for OK                                      |
|           |        |            |   - 1 for error                                   |
+-----------+--------+------------+---------------------------------------------------+
| 8         |        |            | From now on comes the details of the imported     |
|           |        |            | device, if the previous status field was OK (0),  |
|           |        |            | otherwise the reply ends with the status field.   |
+-----------+--------+------------+---------------------------------------------------+
|           | 256    |            | path: Path of the device on the host exporting the|
|           |        |            | USB device, string closed with zero byte, e.g.    |
|           |        |            | "/sys/devices/pci0000:00/0000:00:1d.1/usb3/3-2"   |
|           |        |            | The unused bytes shall be filled with zero        |
|           |        |            | bytes.                                            |
+-----------+--------+------------+---------------------------------------------------+
| 0x108     | 32     |            | busid: Bus ID of the exported device, string      |
|           |        |            | closed with zero byte, e.g. "3-2". The unused     |
|           |        |            | bytes shall be filled with zero bytes.            |
+-----------+--------+------------+---------------------------------------------------+
| 0x128     | 4      |            | busnum                                            |
+-----------+--------+------------+---------------------------------------------------+
| 0x12C     | 4      |            | devnum                                            |
+-----------+--------+------------+---------------------------------------------------+
| 0x130     | 4      |            | speed                                             |
+-----------+--------+------------+---------------------------------------------------+
| 0x134     | 2      |            | idVendor                                          |
+-----------+--------+------------+---------------------------------------------------+
| 0x136     | 2      |            | idProduct                                         |
+-----------+--------+------------+---------------------------------------------------+
| 0x138     | 2      |            | bcdDevice                                         |
+-----------+--------+------------+---------------------------------------------------+
| 0x139     | 1      |            | bDeviceClass                                      |
+-----------+--------+------------+---------------------------------------------------+
| 0x13A     | 1      |            | bDeviceSubClass                                   |
+-----------+--------+------------+---------------------------------------------------+
| 0x13B     | 1      |            | bDeviceProtocol                                   |
+-----------+--------+------------+---------------------------------------------------+
| 0x13C     | 1      |            | bConfigurationValue                               |
+-----------+--------+------------+---------------------------------------------------+
| 0x13D     | 1      |            | bNumConfigurations                                |
+-----------+--------+------------+---------------------------------------------------+
| 0x13E     | 1      |            | bNumInterfaces                                    |
+-----------+--------+------------+---------------------------------------------------+

The following four commands have a common basic header called
'usbip_header_basic', and their headers, called 'usbip_header' (before
transfer_buffer payload), have the same length, therefore paddings are needed.

usbip_header_basic:

+-----------+--------+---------------------------------------------------+
| Offset    | Length | Description                                       |
+===========+========+===================================================+
| 0         | 4      | command                                           |
+-----------+--------+---------------------------------------------------+
| 4         | 4      | seqnum: sequential number that identifies requests|
|           |        | and corresponding responses;                      |
|           |        | incremented per connection                        |
+-----------+--------+---------------------------------------------------+
| 8         | 4      | devid: specifies a remote USB device uniquely     |
|           |        | instead of busnum and devnum;                     |
|           |        | for client (request), this value is               |
|           |        | ((busnum << 16) | devnum);                        |
|           |        | for server (response), this shall be set to 0     |
+-----------+--------+---------------------------------------------------+
| 0xC       | 4      | direction:                                        |
|           |        |                                                   |
|           |        |    - 0: USBIP_DIR_OUT                             |
|           |        |    - 1: USBIP_DIR_IN                              |
|           |        |                                                   |
|           |        | only used by client, for server this shall be 0   |
+-----------+--------+---------------------------------------------------+
| 0x10      | 4      | ep: endpoint number                               |
|           |        | only used by client, for server this shall be 0;  |
|           |        | for UNLINK, this shall be 0                       |
+-----------+--------+---------------------------------------------------+

USBIP_CMD_SUBMIT:
	Submit an URB

+-----------+--------+---------------------------------------------------+
| Offset    | Length | Description                                       |
+===========+========+===================================================+
| 0         | 20     | usbip_header_basic, 'command' shall be 0x00000001 |
+-----------+--------+---------------------------------------------------+
| 0x14      | 4      | transfer_flags: possible values depend on the     |
|           |        | USBIP_URB transfer_flags.                         |
|           |        | Refer to include/uapi/linux/usbip.h and           |
|           |        | Documentation/driver-api/usb/URB.rst.             |
|           |        | Refer to usbip_pack_cmd_submit() and              |
|           |        | tweak_transfer_flags() in drivers/usb/usbip/      |
|           |        | usbip_common.c.                                   |
+-----------+--------+---------------------------------------------------+
| 0x18      | 4      | transfer_buffer_length:                           |
|           |        | use URB transfer_buffer_length                    |
+-----------+--------+---------------------------------------------------+
| 0x1C      | 4      | start_frame: use URB start_frame;                 |
|           |        | initial frame for ISO transfer;                   |
|           |        | shall be set to 0 if not ISO transfer             |
+-----------+--------+---------------------------------------------------+
| 0x20      | 4      | number_of_packets: number of ISO packets;         |
|           |        | shall be set to 0xffffffff if not ISO transfer    |
+-----------+--------+---------------------------------------------------+
| 0x24      | 4      | interval: maximum time for the request on the     |
|           |        | server-side host controller                       |
+-----------+--------+---------------------------------------------------+
| 0x28      | 8      | setup: data bytes for USB setup, filled with      |
|           |        | zeros if not used.                                |
+-----------+--------+---------------------------------------------------+
| 0x30      | n      | transfer_buffer.                                  |
|           |        | If direction is USBIP_DIR_OUT then n equals       |
|           |        | transfer_buffer_length; otherwise n equals 0.     |
|           |        | For ISO transfers the padding between each ISO    |
|           |        | packets is not transmitted.                       |
+-----------+--------+---------------------------------------------------+
| 0x30+n    | m      | iso_packet_descriptor                             |
+-----------+--------+---------------------------------------------------+

USBIP_RET_SUBMIT:
	Reply for submitting an URB

+-----------+--------+---------------------------------------------------+
| Offset    | Length | Description                                       |
+===========+========+===================================================+
| 0         | 20     | usbip_header_basic, 'command' shall be 0x00000003 |
+-----------+--------+---------------------------------------------------+
| 0x14      | 4      | status: zero for successful URB transaction,      |
|           |        | otherwise some kind of error happened.            |
+-----------+--------+---------------------------------------------------+
| 0x18      | 4      | actual_length: number of URB data bytes;          |
|           |        | use URB actual_length                             |
+-----------+--------+---------------------------------------------------+
| 0x1C      | 4      | start_frame: use URB start_frame;                 |
|           |        | initial frame for ISO transfer;                   |
|           |        | shall be set to 0 if not ISO transfer             |
+-----------+--------+---------------------------------------------------+
| 0x20      | 4      | number_of_packets: number of ISO packets;         |
|           |        | shall be set to 0xffffffff if not ISO transfer    |
+-----------+--------+---------------------------------------------------+
| 0x24      | 4      | error_count                                       |
+-----------+--------+---------------------------------------------------+
| 0x28      | 8      | padding, shall be set to 0                        |
+-----------+--------+---------------------------------------------------+
| 0x30      | n      | transfer_buffer.                                  |
|           |        | If direction is USBIP_DIR_IN then n equals        |
|           |        | actual_length; otherwise n equals 0.              |
|           |        | For ISO transfers the padding between each ISO    |
|           |        | packets is not transmitted.                       |
+-----------+--------+---------------------------------------------------+
| 0x30+n    | m      | iso_packet_descriptor                             |
+-----------+--------+---------------------------------------------------+

USBIP_CMD_UNLINK:
	Unlink an URB

+-----------+--------+---------------------------------------------------+
| Offset    | Length | Description                                       |
+===========+========+===================================================+
| 0         | 20     | usbip_header_basic, 'command' shall be 0x00000002 |
+-----------+--------+---------------------------------------------------+
| 0x14      | 4      | unlink_seqnum, of the SUBMIT request to unlink    |
+-----------+--------+---------------------------------------------------+
| 0x18      | 24     | padding, shall be set to 0                        |
+-----------+--------+---------------------------------------------------+

USBIP_RET_UNLINK:
	Reply for URB unlink

+-----------+--------+---------------------------------------------------+
| Offset    | Length | Description                                       |
+===========+========+===================================================+
| 0         | 20     | usbip_header_basic, 'command' shall be 0x00000004 |
+-----------+--------+---------------------------------------------------+
| 0x14      | 4      | status: This is similar to the status of          |
|           |        | USBIP_RET_SUBMIT (share the same memory offset).  |
|           |        | When UNLINK is successful, status is -ECONNRESET; |
|           |        | when USBIP_CMD_UNLINK is after USBIP_RET_SUBMIT   |
|           |        | status is 0                                       |
+-----------+--------+---------------------------------------------------+
| 0x18      | 24     | padding, shall be set to 0                        |
+-----------+--------+---------------------------------------------------+

EXAMPLE
=======

  The following data is captured from wire with Human Interface Devices (HID)
  payload

::

  CmdIntrIN:  00000001 00000d05 0001000f 00000001 00000001 00000200 00000040 ffffffff 00000000 00000004 00000000 00000000
  CmdIntrOUT: 00000001 00000d06 0001000f 00000000 00000001 00000000 00000040 ffffffff 00000000 00000004 00000000 00000000
              ffffffff860008a784ce5ae212376300000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
  RetIntrOut: 00000003 00000d06 00000000 00000000 00000000 00000000 00000040 ffffffff 00000000 00000000 00000000 00000000
  RetIntrIn:  00000003 00000d05 00000000 00000000 00000000 00000000 00000040 ffffffff 00000000 00000000 00000000 00000000
              ffffffff860011a784ce5ae2123763612891b1020100000400000000000000000000000000000000000000000000000000000000000000000000000000000000


code:
======
usbmon
======

Introduction
============

The name "usbmon" in lowercase refers to a facility in kernel which is
used to collect traces of I/O on the USB bus. This function is analogous
to a packet socket used by network monitoring tools such as tcpdump(1)
or Ethereal. Similarly, it is expected that a tool such as usbdump or
USBMon (with uppercase letters) is used to examine raw traces produced
by usbmon.

The usbmon reports requests made by peripheral-specific drivers to Host
Controller Drivers (HCD). So, if HCD is buggy, the traces reported by
usbmon may not correspond to bus transactions precisely. This is the same
situation as with tcpdump.

Two APIs are currently implemented: "text" and "binary". The binary API
is available through a character device in /dev namespace and is an ABI.
The text API is deprecated since 2.6.35, but available for convenience.

How to use usbmon to collect raw text traces
============================================

Unlike the packet socket, usbmon has an interface which provides traces
in a text format. This is used for two purposes. First, it serves as a
common trace exchange format for tools while more sophisticated formats
are finalized. Second, humans can read it in case tools are not available.

To collect a raw text trace, execute following steps.

1. Prepare
----------

Mount debugfs (it has to be enabled in your kernel configuration), and
load the usbmon module (if built as module). The second step is skipped
if usbmon is built into the kernel::

	# mount -t debugfs none_debugs /sys/kernel/debug
	# modprobe usbmon
	#

Verify that bus sockets are present::

	# ls /sys/kernel/debug/usb/usbmon
	0s  0u  1s  1t  1u  2s  2t  2u  3s  3t  3u  4s  4t  4u
	#

Now you can choose to either use the socket '0u' (to capture packets on all
buses), and skip to step #3, or find the bus used by your device with step #2.
This allows to filter away annoying devices that talk continuously.

2. Find which bus connects to the desired device
------------------------------------------------

Run "cat /sys/kernel/debug/usb/devices", and find the T-line which corresponds
to the device. Usually you do it by looking for the vendor string. If you have
many similar devices, unplug one and compare the two
/sys/kernel/debug/usb/devices outputs. The T-line will have a bus number.

Example::

  T:  Bus=03 Lev=01 Prnt=01 Port=00 Cnt=01 Dev#=  2 Spd=12  MxCh= 0
  D:  Ver= 1.10 Cls=00(>ifc ) Sub=00 Prot=00 MxPS= 8 #Cfgs=  1
  P:  Vendor=0557 ProdID=2004 Rev= 1.00
  S:  Manufacturer=ATEN
  S:  Product=UC100KM V2.00

"Bus=03" means it's bus 3. Alternatively, you can look at the output from
"lsusb" and get the bus number from the appropriate line. Example:

Bus 003 Device 002: ID 0557:2004 ATEN UC100KM V2.00

3. Start 'cat'
--------------

::

	# cat /sys/kernel/debug/usb/usbmon/3u > /tmp/1.mon.out

to listen on a single bus, otherwise, to listen on all buses, type::

	# cat /sys/kernel/debug/usb/usbmon/0u > /tmp/1.mon.out

This process will read until it is killed. Naturally, the output can be
redirected to a desirable location. This is preferred, because it is going
to be quite long.

4. Perform the desired operation on the USB bus
-----------------------------------------------

This is where you do something that creates the traffic: plug in a flash key,
copy files, control a webcam, etc.

5. Kill cat
-----------

Usually it's done with a keyboard interrupt (Control-C).

At this point the output file (/tmp/1.mon.out in this example) can be saved,
sent by e-mail, or inspected with a text editor. In the last case make sure
that the file size is not excessive for your favourite editor.

Raw text data format
====================

Two formats are supported currently: the original, or '1t' format, and
the '1u' format. The '1t' format is deprecated in kernel 2.6.21. The '1u'
format adds a few fields, such as ISO frame descriptors, interval, etc.
It produces slightly longer lines, but otherwise is a perfect superset
of '1t' format.

If it is desired to recognize one from the other in a program, look at the
"address" word (see below), where '1u' format adds a bus number. If 2 colons
are present, it's the '1t' format, otherwise '1u'.

Any text format data consists of a stream of events, such as URB submission,
URB callback, submission error. Every event is a text line, which consists
of whitespace separated words. The number or position of words may depend
on the event type, but there is a set of words, common for all types.

Here is the list of words, from left to right:

- URB Tag. This is used to identify URBs, and is normally an in-kernel address
  of the URB structure in hexadecimal, but can be a sequence number or any
  other unique string, within reason.

- Timestamp in microseconds, a decimal number. The timestamp's resolution
  depends on available clock, and so it can be much worse than a microsecond
  (if the implementation uses jiffies, for example).

- Event Type. This type refers to the format of the event, not URB type.
  Available types are: S - submission, C - callback, E - submission error.

- "Address" word (formerly a "pipe"). It consists of four fields, separated by
  colons: URB type and direction, Bus number, Device address, Endpoint number.
  Type and direction are encoded with two bytes in the following manner:

    == ==   =============================
    Ci Co   Control input and output
    Zi Zo   Isochronous input and output
    Ii Io   Interrupt input and output
    Bi Bo   Bulk input and output
    == ==   =============================

  Bus number, Device address, and Endpoint are decimal numbers, but they may
  have leading zeros, for the sake of human readers.

- URB Status word. This is either a letter, or several numbers separated
  by colons: URB status, interval, start frame, and error count. Unlike the
  "address" word, all fields save the status are optional. Interval is printed
  only for interrupt and isochronous URBs. Start frame is printed only for
  isochronous URBs. Error count is printed only for isochronous callback
  events.

  The status field is a decimal number, sometimes negative, which represents
  a "status" field of the URB. This field makes no sense for submissions, but
  is present anyway to help scripts with parsing. When an error occurs, the
  field contains the error code.

  In case of a submission of a Control packet, this field contains a Setup Tag
  instead of an group of numbers. It is easy to tell whether the Setup Tag is
  present because it is never a number. Thus if scripts find a set of numbers
  in this word, they proceed to read Data Length (except for isochronous URBs).
  If they find something else, like a letter, they read the setup packet before
  reading the Data Length or isochronous descriptors.

- Setup packet, if present, consists of 5 words: one of each for bmRequestType,
  bRequest, wValue, wIndex, wLength, as specified by the USB Specification 2.0.
  These words are safe to decode if Setup Tag was 's'. Otherwise, the setup
  packet was present, but not captured, and the fields contain filler.

- Number of isochronous frame descriptors and descriptors themselves.
  If an Isochronous transfer event has a set of descriptors, a total number
  of them in an URB is printed first, then a word per descriptor, up to a
  total of 5. The word consists of 3 colon-separated decimal numbers for
  status, offset, and length respectively. For submissions, initial length
  is reported. For callbacks, actual length is reported.

- Data Length. For submissions, this is the requested length. For callbacks,
  this is the actual length.

- Data tag. The usbmon may not always capture data, even if length is nonzero.
  The data words are present only if this tag is '='.

- Data words follow, in big endian hexadecimal format. Notice that they are
  not machine words, but really just a byte stream split into words to make
  it easier to read. Thus, the last word may contain from one to four bytes.
  The length of collected data is limited and can be less than the data length
  reported in the Data Length word. In the case of an Isochronous input (Zi)
  completion where the received data is sparse in the buffer, the length of
  the collected data can be greater than the Data Length value (because Data
  Length counts only the bytes that were received whereas the Data words
  contain the entire transfer buffer).

Examples:

An input control transfer to get a port status::

  d5ea89a0 3575914555 S Ci:1:001:0 s a3 00 0000 0003 0004 4 <
  d5ea89a0 3575914560 C Ci:1:001:0 0 4 = 01050000

An output bulk transfer to send a SCSI command 0x28 (READ_10) in a 31-byte
Bulk wrapper to a storage device at address 5::

  dd65f0e8 4128379752 S Bo:1:005:2 -115 31 = 55534243 ad000000 00800000 80010a28 20000000 20000040 00000000 000000
  dd65f0e8 4128379808 C Bo:1:005:2 0 31 >

Raw binary format and API
=========================

The overall architecture of the API is about the same as the one above,
only the events are delivered in binary format. Each event is sent in
the following structure (its name is made up, so that we can refer to it)::

  struct usbmon_packet {
	u64 id;			/*  0: URB ID - from submission to callback */
	unsigned char type;	/*  8: Same as text; extensible. */
	unsigned char xfer_type; /*    ISO (0), Intr, Control, Bulk (3) */
	unsigned char epnum;	/*     Endpoint number and transfer direction */
	unsigned char devnum;	/*     Device address */
	u16 busnum;		/* 12: Bus number */
	char flag_setup;	/* 14: Same as text */
	char flag_data;		/* 15: Same as text; Binary zero is OK. */
	s64 ts_sec;		/* 16: gettimeofday */
	s32 ts_usec;		/* 24: gettimeofday */
	int status;		/* 28: */
	unsigned int length;	/* 32: Length of data (submitted or actual) */
	unsigned int len_cap;	/* 36: Delivered length */
	union {			/* 40: */
		unsigned char setup[SETUP_LEN];	/* Only for Control S-type */
		struct iso_rec {		/* Only for ISO */
			int error_count;
			int numdesc;
		} iso;
	} s;
	int interval;		/* 48: Only for Interrupt and ISO */
	int start_frame;	/* 52: For ISO */
	unsigned int xfer_flags; /* 56: copy of URB's transfer_flags */
	unsigned int ndesc;	/* 60: Actual number of ISO descriptors */
  };				/* 64 total length */

These events can be received from a character device by reading with read(2),
with an ioctl(2), or by accessing the buffer with mmap. However, read(2)
only returns first 48 bytes for compatibility reasons.

The character device is usually called /dev/usbmonN, where N is the USB bus
number. Number zero (/dev/usbmon0) is special and means "all buses".
Note that specific naming policy is set by your Linux distribution.

If you create /dev/usbmon0 by hand, make sure that it is owned by root
and has mode 0600. Otherwise, unprivileged users will be able to snoop
keyboard traffic.

The following ioctl calls are available, with MON_IOC_MAGIC 0x92:

 MON_IOCQ_URB_LEN, defined as _IO(MON_IOC_MAGIC, 1)

This call returns the length of data in the next event. Note that majority of
events contain no data, so if this call returns zero, it does not mean that
no events are available.

 MON_IOCG_STATS, defined as _IOR(MON_IOC_MAGIC, 3, struct mon_bin_stats)

The argument is a pointer to the following structure::

  struct mon_bin_stats {
	u32 queued;
	u32 dropped;
  };

The member "queued" refers to the number of events currently queued in the
buffer (and not to the number of events processed since the last reset).

The member "dropped" is the number of events lost since the last call
to MON_IOCG_STATS.

 MON_IOCT_RING_SIZE, defined as _IO(MON_IOC_MAGIC, 4)

This call sets the buffer size. The argument is the size in bytes.
The size may be rounded down to the next chunk (or page). If the requested
size is out of [unspecified] bounds for this kernel, the call fails with
-EINVAL.

 MON_IOCQ_RING_SIZE, defined as _IO(MON_IOC_MAGIC, 5)

This call returns the current size of the buffer in bytes.

 MON_IOCX_GET, defined as _IOW(MON_IOC_MAGIC, 6, struct mon_get_arg)
 MON_IOCX_GETX, defined as _IOW(MON_IOC_MAGIC, 10, struct mon_get_arg)

These calls wait for events to arrive if none were in the kernel buffer,
then return the first event. The argument is a pointer to the following
structure::

  struct mon_get_arg {
	struct usbmon_packet *hdr;
	void *data;
	size_t alloc;		/* Length of data (can be zero) */
  };

Before the call, hdr, data, and alloc should be filled. Upon return, the area
pointed by hdr contains the next event structure, and the data buffer contains
the data, if any. The event is removed from the kernel buffer.

The MON_IOCX_GET copies 48 bytes to hdr area, MON_IOCX_GETX copies 64 bytes.

 MON_IOCX_MFETCH, defined as _IOWR(MON_IOC_MAGIC, 7, struct mon_mfetch_arg)

This ioctl is primarily used when the application accesses the buffer
with mmap(2). Its argument is a pointer to the following structure::

  struct mon_mfetch_arg {
	uint32_t *offvec;	/* Vector of events fetched */
	uint32_t nfetch;	/* Number of events to fetch (out: fetched) */
	uint32_t nflush;	/* Number of events to flush */
  };

The ioctl operates in 3 stages.

First, it removes and discards up to nflush events from the kernel buffer.
The actual number of events discarded is returned in nflush.

Second, it waits for an event to be present in the buffer, unless the pseudo-
device is open with O_NONBLOCK.

Third, it extracts up to nfetch offsets into the mmap buffer, and stores
them into the offvec. The actual number of event offsets is stored into
the nfetch.

 MON_IOCH_MFLUSH, defined as _IO(MON_IOC_MAGIC, 8)

This call removes a number of events from the kernel buffer. Its argument
is the number of events to remove. If the buffer contains fewer events
than requested, all events present are removed, and no error is reported.
This works when no events are available too.

 FIONBIO

The ioctl FIONBIO may be implemented in the future, if there's a need.

In addition to ioctl(2) and read(2), the special file of binary API can
be polled with select(2) and poll(2). But lseek(2) does not work.

* Memory-mapped access of the kernel buffer for the binary API

The basic idea is simple:

To prepare, map the buffer by getting the current size, then using mmap(2).
Then, execute a loop similar to the one written in pseudo-code below::

   struct mon_mfetch_arg fetch;
   struct usbmon_packet *hdr;
   int nflush = 0;
   for (;;) {
      fetch.offvec = vec; // Has N 32-bit words
      fetch.nfetch = N;   // Or less than N
      fetch.nflush = nflush;
      ioctl(fd, MON_IOCX_MFETCH, &fetch);   // Process errors, too
      nflush = fetch.nfetch;       // This many packets to flush when done
      for (i = 0; i < nflush; i++) {
         hdr = (struct ubsmon_packet *) &mmap_area[vec[i]];
         if (hdr->type == '@')     // Filler packet
            continue;
         caddr_t data = &mmap_area[vec[i]] + 64;
         process_packet(hdr, data);
      }
   }

Thus, the main idea is to execute only one ioctl per N events.

Although the buffer is circular, the returned headers and data do not cross
the end of the buffer, so the above pseudo-code does not need any gathering.


code:
========================================================
OpenCAPI (Open Coherent Accelerator Processor Interface)
========================================================

OpenCAPI is an interface between processors and accelerators. It aims
at being low-latency and high-bandwidth. The specification is
developed by the `OpenCAPI Consortium <http://opencapi.org/>`_.

It allows an accelerator (which could be an FPGA, ASICs, ...) to access
the host memory coherently, using virtual addresses. An OpenCAPI
device can also host its own memory, that can be accessed from the
host.

OpenCAPI is known in linux as 'ocxl', as the open, processor-agnostic
evolution of 'cxl' (the driver for the IBM CAPI interface for
powerpc), which was named that way to avoid confusion with the ISDN
CAPI subsystem.

High-level view
===============

OpenCAPI defines a Data Link Layer (DL) and Transaction Layer (TL), to
be implemented on top of a physical link. Any processor or device
implementing the DL and TL can start sharing memory.

::

  +-----------+                         +-------------+
  |           |                         |             |
  |           |                         | Accelerated |
  | Processor |                         |  Function   |
  |           |  +--------+             |    Unit     |  +--------+
  |           |--| Memory |             |    (AFU)    |--| Memory |
  |           |  +--------+             |             |  +--------+
  +-----------+                         +-------------+
       |                                       |
  +-----------+                         +-------------+
  |    TL     |                         |    TLX      |
  +-----------+                         +-------------+
       |                                       |
  +-----------+                         +-------------+
  |    DL     |                         |    DLX      |
  +-----------+                         +-------------+
       |                                       |
       |                   PHY                 |
       +---------------------------------------+

Device discovery
================

OpenCAPI relies on a PCI-like configuration space, implemented on the
device. So the host can discover AFUs by querying the config space.

OpenCAPI devices in Linux are treated like PCI devices (with a few
caveats). The firmware is expected to abstract the hardware as if it
was a PCI link. A lot of the existing PCI infrastructure is reused:
devices are scanned and BARs are assigned during the standard PCI
enumeration. Commands like 'lspci' can therefore be used to see what
devices are available.

The configuration space defines the AFU(s) that can be found on the
physical adapter, such as its name, how many memory contexts it can
work with, the size of its MMIO areas, ...

MMIO
====

OpenCAPI defines two MMIO areas for each AFU:

* the global MMIO area, with registers pertinent to the whole AFU.
* a per-process MMIO area, which has a fixed size for each context.

AFU interrupts
==============

OpenCAPI includes the possibility for an AFU to send an interrupt to a
host process. It is done through a 'intrp_req' defined in the
Transaction Layer, specifying a 64-bit object handle which defines the
interrupt.

The driver allows a process to allocate an interrupt and obtain its
64-bit object handle, that can be passed to the AFU.

char devices
============

The driver creates one char device per AFU found on the physical
device. A physical device may have multiple functions and each
function can have multiple AFUs. At the time of this writing though,
it has only been tested with devices exporting only one AFU.

Char devices can be found in /dev/ocxl/ and are named as:
/dev/ocxl/<AFU name>.<location>.<index>

where <AFU name> is a max 20-character long name, as found in the
config space of the AFU.
<location> is added by the driver and can help distinguish devices
when a system has more than one instance of the same OpenCAPI device.
<index> is also to help distinguish AFUs in the unlikely case where a
device carries multiple copies of the same AFU.

Sysfs class
===========

An ocxl class is added for the devices representing the AFUs. See
/sys/class/ocxl. The layout is described in
Documentation/ABI/testing/sysfs-class-ocxl

User API
========

open
----

Based on the AFU definition found in the config space, an AFU may
support working with more than one memory context, in which case the
associated char device may be opened multiple times by different
processes.

ioctl
-----

OCXL_IOCTL_ATTACH:

  Attach the memory context of the calling process to the AFU so that
  the AFU can access its memory.

OCXL_IOCTL_IRQ_ALLOC:

  Allocate an AFU interrupt and return an identifier.

OCXL_IOCTL_IRQ_FREE:

  Free a previously allocated AFU interrupt.

OCXL_IOCTL_IRQ_SET_FD:

  Associate an event fd to an AFU interrupt so that the user process
  can be notified when the AFU sends an interrupt.

OCXL_IOCTL_GET_METADATA:

  Obtains configuration information from the card, such at the size of
  MMIO areas, the AFU version, and the PASID for the current context.

OCXL_IOCTL_ENABLE_P9_WAIT:

  Allows the AFU to wake a userspace thread executing 'wait'. Returns
  information to userspace to allow it to configure the AFU. Note that
  this is only available on POWER9.

OCXL_IOCTL_GET_FEATURES:

  Reports on which CPU features that affect OpenCAPI are usable from
  userspace.

mmap
----

A process can mmap the per-process MMIO area for interactions with the
AFU.


code:
.. SPDX-License-Identifier: GPL-2.0

eBPF Userspace API
==================

eBPF is a kernel mechanism to provide a sandboxed runtime environment in the
Linux kernel for runtime extension and instrumentation without changing kernel
source code or loading kernel modules. eBPF programs can be attached to various
kernel subsystems, including networking, tracing and Linux security modules
(LSM).

For internal kernel documentation on eBPF, see Documentation/bpf/index.rst.

.. toctree::
   :maxdepth: 1

   syscall


code:
.. SPDX-License-Identifier: GPL-2.0

eBPF Syscall
------------

:Authors: - Alexei Starovoitov <ast@kernel.org>
          - Joe Stringer <joe@wand.net.nz>
          - Michael Kerrisk <mtk.manpages@gmail.com>

The primary info for the bpf syscall is available in the `man-pages`_
for `bpf(2)`_.

bpf() subcommand reference
~~~~~~~~~~~~~~~~~~~~~~~~~~

.. kernel-doc:: include/uapi/linux/bpf.h
   :doc: eBPF Syscall Preamble

.. kernel-doc:: include/uapi/linux/bpf.h
   :doc: eBPF Syscall Commands

.. Links:
.. _man-pages: https://www.kernel.org/doc/man-pages/
.. _bpf(2): https://man7.org/linux/man-pages/man2/bpf.2.html


code:
.. SPDX-License-Identifier: GPL-2.0

======
futex2
======

:Author: André Almeida <andrealmeid@collabora.com>

futex, or fast user mutex, is a set of syscalls to allow userspace to create
performant synchronization mechanisms, such as mutexes, semaphores and
conditional variables in userspace. C standard libraries, like glibc, uses it
as a means to implement more high level interfaces like pthreads.

futex2 is a followup version of the initial futex syscall, designed to overcome
limitations of the original interface.

User API
========

``futex_waitv()``
-----------------

Wait on an array of futexes, wake on any::

  futex_waitv(struct futex_waitv *waiters, unsigned int nr_futexes,
              unsigned int flags, struct timespec *timeout, clockid_t clockid)

  struct futex_waitv {
        __u64 val;
        __u64 uaddr;
        __u32 flags;
        __u32 __reserved;
  };

Userspace sets an array of struct futex_waitv (up to a max of 128 entries),
using ``uaddr`` for the address to wait for, ``val`` for the expected value
and ``flags`` to specify the type (e.g. private) and size of futex.
``__reserved`` needs to be 0, but it can be used for future extension. The
pointer for the first item of the array is passed as ``waiters``. An invalid
address for ``waiters`` or for any ``uaddr`` returns ``-EFAULT``.

If userspace has 32-bit pointers, it should do a explicit cast to make sure
the upper bits are zeroed. ``uintptr_t`` does the tricky and it works for
both 32/64-bit pointers.

``nr_futexes`` specifies the size of the array. Numbers out of [1, 128]
interval will make the syscall return ``-EINVAL``.

The ``flags`` argument of the syscall needs to be 0, but it can be used for
future extension.

For each entry in ``waiters`` array, the current value at ``uaddr`` is compared
to ``val``. If it's different, the syscall undo all the work done so far and
return ``-EAGAIN``. If all tests and verifications succeeds, syscall waits until
one of the following happens:

- The timeout expires, returning ``-ETIMEOUT``.
- A signal was sent to the sleeping task, returning ``-ERESTARTSYS``.
- Some futex at the list was woken, returning the index of some waked futex.

An example of how to use the interface can be found at ``tools/testing/selftests/futex/functional/futex_waitv.c``.

Timeout
-------

``struct timespec *timeout`` argument is an optional argument that points to an
absolute timeout. You need to specify the type of clock being used at
``clockid`` argument. ``CLOCK_MONOTONIC`` and ``CLOCK_REALTIME`` are supported.
This syscall accepts only 64bit timespec structs.

Types of futex
--------------

A futex can be either private or shared. Private is used for processes that
shares the same memory space and the virtual address of the futex will be the
same for all processes. This allows for optimizations in the kernel. To use
private futexes, it's necessary to specify ``FUTEX_PRIVATE_FLAG`` in the futex
flag. For processes that doesn't share the same memory space and therefore can
have different virtual addresses for the same futex (using, for instance, a
file-backed shared memory) requires different internal mechanisms to be get
properly enqueued. This is the default behavior, and it works with both private
and shared futexes.

Futexes can be of different sizes: 8, 16, 32 or 64 bits. Currently, the only
supported one is 32 bit sized futex, and it need to be specified using
``FUTEX_32`` flag.


code:
=====================================
The Linux kernel user-space API guide
=====================================

.. _man-pages: https://www.kernel.org/doc/man-pages/

While much of the kernel's user-space API is documented elsewhere
(particularly in the man-pages_ project), some user-space information can
also be found in the kernel tree itself.  This manual is intended to be the
place where this information is gathered.

.. class:: toc-title

	   Table of contents

.. toctree::
   :maxdepth: 2

   no_new_privs
   seccomp_filter
   landlock
   unshare
   spec_ctrl
   accelerators/ocxl
   ebpf/index
   ioctl/index
   iommu
   iommufd
   media/index
   netlink/index
   sysfs-platform_profile
   vduse
   futex2

.. only::  subproject and html

   Indices
   =======

   * :ref:`genindex`