[cdi-devel] [PATCH v3 1/5] CDI.usb, CDI.usb-hcd
Kevin Wolf ·
From: Max Reitz <max at tyndur.org> + Added CDI.usb header + Added CDI.usb-hcd header Signed-off-by: Max Reitz <max at tyndur.org> Signed-off-by: Kevin Wolf <kevin at tyndur.org> --- include/cdi/usb-hcd.h | 178 ++++++++++ include/cdi/usb.h | 868 +++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 1046 insertions(+), 0 deletions(-) create mode 100644 include/cdi/usb-hcd.h create mode 100644 include/cdi/usb.h diff --git a/include/cdi/usb-hcd.h b/include/cdi/usb-hcd.h new file mode 100644 index 0000000..60b0a01 --- /dev/null +++ b/include/cdi/usb-hcd.h @@ -0,0 +1,178 @@ +/* + * Copyright (c) 2009 Max Reitz + * + * This program is free software. It comes without any warranty, to + * the extent permitted by applicable law. You can redistribute it + * and/or modify it under the terms of the Do What The Fuck You Want + * To Public License, Version 2, as published by Sam Hocevar. See + * http://sam.zoy.org/projects/COPYING.WTFPL for more details. + */ + +/** + * \if german + * USB-Hostcontrollertreiber + * \elseif english + * USB host controller drivers + * \endif + * \defgroup USBHCD + */ +/*\@{*/ + +#ifndef _CDI_USB_HCD_H_ +#define _CDI_USB_HCD_H_ + +#include "cdi/misc.h" +#include "cdi/usb.h" + +struct cdi_usb_hc { + struct cdi_device dev; + + /** + * \if german + * USB-Geschwindigkeit + * \elseif english + * USB speed + * \endif + */ + cdi_usb_speed_t speed; +}; + +struct cdi_usb_hcd { + struct cdi_driver drv; + + /** + * \if german + * + * Listet alle Geraete auf, die an den Rootports haengen und ruft ggf. + * cdi_usb_device_init auf + * + * @param device Der Hostcontroller + * + * \elseif english + * + * Lists all devices hanging at the root ports and calls (if necessary) + * cdi_usb_device_init + * + * @param device The host controller + * + * \endif + */ + void (*find_devices)(struct cdi_usb_hc* device); + + /** + * \if german + * + * Aktiviert den zum angegebenen Geraet gehoerigen Rootport + * + * @param usb_device Das USB-Geraet (muss an einem Rootport haengen) + * + * \elseif english + * + * Activates the root port corresponding to the device + * + * @param usb_device The USB device (must be located at a root port) + * + * \endif + */ + void (*activate_device)(struct cdi_usb_device* usb_device); + + /** + * \if german + * + * Verarbeitet USB-Pakete + * + * @param packets Array zu sendender Pakete + * @param num_packets Anzahl der Pakete + * + * @return Gibt den Status an (z. B. USB_NO_ERROR fuer keinen Fehler) + * + * \elseif english + * + * Sends USB packets + * + * @param packets Array of packages to be sent + * @param num_packages Number of packages + * + * \endif + */ + cdi_usb_status_t (*send_packets)(struct cdi_usb_packet* packets, + size_t num_packets); + + /** + * \if german + * + * Erstellt eine neue Pipe + * + * @param pipe Die Pipe + * + * \elseif english + * + * Creates a new pipe + * + * @param pipe The pipe + * + * \endif + */ + void (*add_pipe)(struct cdi_usb_pipe* pipe); +}; + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * \if german + * + * Initialisiert einen HCD + * + * @param driver Der HCD + * + * \elseif english + * + * Initializes an HCD + * + * @param driver The HCD + * + * \endif + */ +void cdi_usb_hcd_init(struct cdi_usb_hcd* driver); + +/** + * \if german + * + * Gibt einen HCD frei + * + * @param driver Freizugebender HCD + * + * \elseif english + * + * Removes an HCD + * + * @param driver HCD to be removed + * + * \endif + */ +void cdi_usb_hcd_destroy(struct cdi_usb_hcd* driver); + +/** + * \if german + * + * Registriert einen HCD + * + * @param driver Zu registrierender HCD + * + * \elseif english + * + * Registers an HCD + * + * @param driver HCD to be registered + * + * \endif + */ +void cdi_usb_hcd_register(struct cdi_usb_hcd* driver); + +#ifdef __cplusplus +} //extern "C" +#endif + +#endif diff --git a/include/cdi/usb.h b/include/cdi/usb.h new file mode 100644 index 0000000..54ce1a0 --- /dev/null +++ b/include/cdi/usb.h @@ -0,0 +1,868 @@ +/* + * Copyright (c) 2009 Max Reitz + * + * This program is free software. It comes without any warranty, to + * the extent permitted by applicable law. You can redistribute it + * and/or modify it under the terms of the Do What The Fuck You Want + * To Public License, Version 2, as published by Sam Hocevar. See + * http://sam.zoy.org/projects/COPYING.WTFPL for more details. + */ + +/** + * \if german + * USB-Bustreiber + * \elseif english + * USB bus drivers + * \endif + * \defgroup USB + */ +/*\@{*/ + +#ifndef _CDI_USB_H_ +#define _CDI_USB_H_ + +#include "stddef.h" +#include "stdint.h" + +typedef enum { + /// Low-Speed (1,5 Mbit/s) + CDI_USB_LOW_SPEED = 0x01, + /// Full-Speed (12 Mbit/s) + CDI_USB_FULL_SPEED = 0x02, + /// High-Speed (480 Mbit/s) + CDI_USB_HIGH_SPEED = 0x04, + /// SuperSpeed (5 Gbit/s) + CDI_USB_SUPER_SPEED = 0x08, +} cdi_usb_speed_t; + +typedef enum { + /** + * \if german + * SETUP-Paket + * \elseif english + * SETUP packet + * \endif + */ + CDI_USB_PACKET_SETUP = 0x2D, + + /** + * \if german + * Daten vom Geraet zum Host + * \elseif english + * Data from the device to the host + * \endif + */ + CDI_USB_PACKET_IN = 0x69, + + /** + * \if german + * Daten vom Host zum Geraet + * \elseif english + * Data from the host to the device + * \endif + */ + CDI_USB_PACKET_OUT = 0xE1, +} cdi_usb_packet_type_t; + +typedef enum { + /** + * \if german + * Kein Fehler + * \elseif english + * No error + * \endif + */ + CDI_USB_NO_ERROR = 0x0000, + + /// Stalled + CDI_USB_STALLED = 0x0001, + + /** + * \if german + * Bufferfehler (Overflow, underrun, ...) + * \elseif english + * Buffer error (overflow, underrun, ...) + * \endif + */ + CDI_USB_BUFFER_ERROR = 0x0002, + + /** + * \if german + * Babble (Geraet hat zu viele Daten gesendet) + * \elseif english + * Babble (device has sent more data than expected) + * \endif + */ + CDI_USB_BABBLE = 0x0004, + + /** + * \if german + * NAK (Daten sind erneut zu senden) + * \elseif english + * NAK (data has to be sent again) + * \endif + */ + CDI_USB_NAK = 0x0008, + + /** + * \if german + * CRC-Fehler + * \elseif english + * CRC error + * \endif + */ + CDI_USB_CRC = 0x0010, + + /// Timeout + CDI_USB_TIMEOUT = 0x0020, + + /** + * \if german + * Bitstuff/-destuff-Fehler + * \elseif english + * bitstuff/-destuff error + * \endif + */ + CDI_USB_BITSTUFF = 0x0040, + + /** + * \if german + * Reservieren von Speicher fehlgeschlagen, ... + * \elseif english + * Allocating of memory failed, ... + * \endif + */ + CDI_USB_TRIVIAL_ERROR = 0x0080, +} cdi_usb_status_t; + +struct cdi_usb_hc; +struct cdi_usb_pipe; +struct cdi_usb_interface; +struct cdi_usb_driver; + +struct cdi_usb_device { + /** + * \if german + * Der USB-Bustreiber + * \elseif english + * The USB bus driver + * \endif + */ + struct cdi_usb_driver* drv; + + /** + * \if german + * Der Hostcontroller, an dem das Geraet im Endeffekt haengt + * \elseif english + * The host controller where the device is eventually located + * \endif + */ + struct cdi_usb_hc* hc; + + /** + * \if german + * Haengt das Geraet an einem Hub, dann ist dieses Feld ein Pointer auf + * das entsprechende USB-Geraet, haengt es an einem Rootport, dann ist + * dieses Feld NULL. + * \elseif english + * If the device is located at a hub, then this field contains a pointer to + * the corresponding USB device, if it's located at a root port, then this + * field is set to NULL. + * \endif + */ + struct cdi_usb_device* hub; + + /** + * \if german + * Geschwindigkeit(-en) dieses Geraets + * \elseif english + * Speed(-s) supported by this device + * \endif + */ + cdi_usb_speed_t speed; + + /// ID + int id; + + /** + * \if german + * Entweder der Rootport oder der Port des Hubs, an dem das Geraet haengt + * \elseif english + * Either the root port or the port hub's port where the device is located + * \endif + */ + int port; + + /** + * \if german + * Hier darf der Geraetetreiber seine Daten unterbringen + * \elseif english + * The device driver may store its data here + * \endif + */ + void* driver_data; + + /** + * \if german + * Felder, die so auch bei PCI existieren: Vendor-, Device-, Class-, + * Subclass- und Protocol-ID + * \elseif english + * Fields existing at PCI, too: vendor, device, class, subclass and + * protocol ID. + * \endif + */ + int vendor_id; + int device_id; + int class_id; + int subclass_id; + int protocol_id; + + /** + * \if german + * + * Setzt das USB-Geraet zurueck (kann sowohl vom HCD als auch vom Hub + * driver ausgefuehrt werden) + * + * @param usb_device Das Geraet + * + * \elseif english + * + * Resets the USB device (may be executed either by the HCD or the hub + * driver) + * + * @param usb_device The device + * + * \endif + */ + void (*reset)(struct cdi_usb_device* usb_device); + + /** + * \if german + * Ziemlich lowlevelig. Gehoert das hier wirklich rein? + * \elseif english + * Very low level. Does it really fit in here? + * \endif + */ + + /** + * \if german + * Im einzelnen sind das: Pipe fuer Endpoint 0 + * \elseif english + * In particular these things are: Pipe for endpoint 0 + * \endif + */ + struct cdi_usb_pipe* ep0; + + /// Device descriptor + void* device_desc; + + /// Configuration descriptor + void* config_desc; + + /// Interface descriptor + struct cdi_usb_interface* interface_desc; + + /// Class descriptor + void* class_desc; +}; + +enum cdi_usb_toggle { + /** + * \if german + * Das Toggle nehmen, das jetzt dran ist + * \elseif english + * Use the toggle to be used right now + * \endif + */ + TOGGLE_UNSPECIFIC = 0, + + /** + * \if german + * Geloeschtes Togglebit erzwingen + * \elseif english + * Force unset toggle bit + * \endif + */ + TOGGLE_0 = 1, + + /** + * \if german + * Gesetztes Togglebit erzwingen + * \elseif english + * Force set toggle bit + * \endif + */ + TOGGLE_1 = 2 +}; + +struct cdi_usb_endpoint { + /// sizeof(struct cdi_usb_endpoint) + uint8_t length; + + /// 5 + uint8_t descriptor_type; + + /** + * \if german + * Nummer des Endpoints + * \elseif english + * Endpoint's number + * \endif + */ + uint8_t endpoint_address; + + /** + * \if german + * Eigenschaften (IN/OUT, Bulk/Interrupt/..., ...) + * \elseif english + * Attributes (IN/OUT, bulk/interrupt/..., ...) + * \endif + */ + uint8_t attributes; + + /** + * \if german + * Maximale Paketgroesse in Bytes + * \elseif english + * Maximum packet size in bytes + * \endif + */ + uint16_t max_packet_size; + + /// ??? + uint8_t interval; +} __attribute__((packed)); + +struct cdi_usb_interface { + /// sizeof(struct cdi_usb_interface) + uint8_t length; + + /// 4 + uint8_t descriptor_type; + + /** + * \if german + * Nummer des Interface + * \elseif english + * Interface's number + * \endif + */ + uint8_t interface_number; + + /// ??? + uint8_t alternate_setting; + + /** + * \if german + * Anzahl der Endpoints fuer dieses Interface + * \elseif english + * Number of endpoints for this interface + * \endif + */ + uint8_t num_endpoints; + + /** + * \if german + * Class-ID (bei Composite Devices) + * \elseif english + * Class ID (used with composite devices) + * \endif + */ + uint8_t interface_class; + + /// Subclass-ID + uint8_t interface_subclass; + + /// Protocol-ID + uint8_t interface_protocol; + + /** + * \if german + * String-Index, der das Interface beschreibt + * \elseif english + * String index describing the interface + * \endif + */ + uint8_t iInterface; +} __attribute__((packed)); + +/** + * \if german + * Beschreibt eine Pipe + * \elseif english + * Describes a pipe + * \endif + */ +struct cdi_usb_pipe { + /** + * \if german + * Ziel + * \elseif english + * Destination + * \endif + */ + struct cdi_usb_device* device; + + /** + * \if german + * Ein Pointer auf eine den Endpoint beschreibende Struktur + * TODO Das ist eigentlich auch sehr lowlevelig. + * \elseif english + * A pointer to a structure describing the endpoint + * TODO This is on a very low level, too. + */ + struct cdi_usb_endpoint* endpoint; + + /// Data-Toggle + int data_toggle; +}; + +/** + * \if german + * Beschreibt ein USB-Paket + * \elseif english + * Describes a USB packet + * \endif + */ +struct cdi_usb_packet { + /** + * \if german + * Die gewuenschte Pipe + * \elseif english + * The desired pipe + * \endif + */ + struct cdi_usb_pipe* pipe; + + /** + * \if german + * Der Typ des Pakets (PACKET_IN, PACKET_OUT, PACKET_SETUP) + * \elseif english + * Type of packet (PACKET_IN, PACKET_OUT, PACKET_SETUP) + * \endif + */ + cdi_usb_packet_type_t type; + + /** + * \if german + * Zeiger auf den Datenpuffer + * \elseif english + * Pointer to the data buffer + * \endif + */ + void* data; + + /** + * \if german + * Die Laenge des Puffers + * \elseif english + * The buffer's length + * \endif + */ + size_t length; + + /** + * \if german + * Fehlertyp (oder USB_NO_ERROR) + * \elseif english + * Error type (or USB_NO_ERROR) + * \endif + */ + cdi_usb_status_t condition; + + /** + * \if german + * Bestimmtes Data-Toggle benuten + * \elseif english + * Use specific data toggle + * \endif + */ + enum cdi_usb_toggle use_toggle; +}; + +typedef enum { + /** + * \if german + * Host -> Geraet + * \elseif english + * Host -> device + * \endif + */ + CDI_USB_CONTROL_OUT = 0x00, + + /** + * \if german + * Geraet -> Host + * \elseif english + * Device -> host + * \endif + */ + CDI_USB_CONTROL_IN = 0x80 +} cdi_usb_control_direction_t; + +typedef enum { + /** + * \if german + * Standard-Request + * \elseif english + * Standard request + * \endif + */ + CDI_USB_CONTROL_RQ_STANDARD = 0x00, + + /** + * \if german + * Klassenspezifischer Request + * \elseif english + * Class specific request + * \endif + */ + CDI_USB_CONTROL_RQ_CLASS = 0x20, + + /** + * \if german + * Herstellerspezifischer Request + * \elseif english + * Vendor specific request + * \endif + */ + CDI_USB_CONTROL_RQ_VENDOR = 0x40 +} cdi_usb_control_request_type_t; + +typedef enum { + /** + * \if german + * Empfaenger: Geraet + * \elseif english + * Recipient: device + * \endif + */ + CDI_USB_CONTROL_REC_DEVICE = 0x00, + + /** + * \if german + * Empfaenger: Interface + * \elseif english + * Recipient: interface + * \endif + */ + CDI_USB_CONTROL_REC_INTERFACE = 0x01, + + /** + * \if german + * Empfaenger: Endpoint + * \elseif english + * Recipient: endpoint + * \endif + */ + CDI_USB_CONTROL_REC_ENDPOINT = 0x02, + + /** + * \if german + * Empfaenger ist jemand anderes + * \elseif english + * Recipient is another one + * \endif + */ + CDI_USB_CONTROL_REC_OTHER = 0x03 +} cdi_usb_control_recipient_t; + +struct cdi_usb_control_transfer { + /** + * \if german + * Wenn Daten zum Geraet gesendet werden sollen, dann ist hier der + * Speicherbereich anzugeben + * \elseif english + * If data has to be sent to the device, then the memory buffer has to be + * given here + * \endif + */ + void* buffer; + + /** + * \if german + * Laenge der erwarteten bzw. zu sendenden Daten + * \elseif english + * Length of the expected data respectively the data to be sent + * \endif + */ + size_t length; + + /** + * \if german + * Richtung + * \elseif english + * Direction + * \endif + */ + cdi_usb_control_direction_t direction; + + /** + * \if german + * Art des Requests (Standardrequest, klassenspezifisch, + * herstellerspezifisch) + * \elseif english + * Request type (standard request, class specific, vendor specific) + * \endif + */ + cdi_usb_control_request_type_t rtype; + + /** + * \if german + * Ziel (Device, Interface, Endpoint, anderes) + * \elseif english + * Recipient (device, interface, endpoint, other) + * \endif + */ + cdi_usb_control_recipient_t recipient; + + /** + * \if german + * Requestcode (Je nach rtype und recipient) + * \elseif english + * Request code (specific to rtype and recipient) + * \endif + */ + int request; + + /** + * \if german + * Ein zu sendender Wert + * \elseif english + * A value to be sent + * \endif + */ + int value; + + /** + * \if german + * Ein zu sendender Index + * \elseif english + * An index to be sent + * \endif + */ + int index; +}; + +#include "cdi/usb-hcd.h" + +struct cdi_usb_driver { + struct cdi_driver drv; + + /** + * \if german + * Unterstuetzte Geschwindigkeiten + * \elseif english + * Supported speeds + * \endif + */ + cdi_usb_speed_t speeds; + + /** + * \if german + * + * Enumeriert ein USB-Geraet + * + * @param device Das zu enumerierende Geraet + * + * \elseif english + * + * Enumerates a USB device + * + * @param device The device to be enumerated + * + * \endif + */ + void (*enumerate_device)(struct cdi_usb_device* device); + + /** + * \if german + * + * Sendet USB-Pakete + * + * @param packets Array zu sendender Pakete + * @param num_packets Anzahl der Pakete + * + * @return Gibt den Status an (z. B. USB_NO_ERROR fuer keinen Fehler) + * + * \elseif english + * + * Sends USB packets + * + * @param packets Array of packets to be sent + * @param num_packets Number of packets + * + * @return Returns the status (i. e. USB_NO_ERROR to indicate no error) + * + * \endif + */ + cdi_usb_status_t (*send_packets)(struct cdi_usb_packet* packets, + size_t num_packets); + + /** + * \if german + * + * Fuehrt einen Control-Transfer durch + * + * @param device Das Zielgeraet + * @param transfer Eine den Transfer beschreibende Struktur + * + * @return Gibt einen Puffer zurueck, der die ausgetauschen Daten enthaelt, + * im Fehlerfall hingegen NULL, gab es keine Daten, dann + * (void *)0xFFFFFFFF. + * + * \elseif english + * + * Performs a control transfer + * + * @param device The destination device + * @param transfer A structure describing this transfer + * + * @return Returns a buffer containing the transferred data, in case of an + * error the value is NULL and if there was no data, it returns + * (void *)0xFFFFFFFF. + * + * \endif + */ + void* (*do_control)(struct cdi_usb_device* device, + struct cdi_usb_control_transfer* transfer); +}; + +/** + * \if german + * Ein USB-Geraetetreiber uebergibt dem Betriebssystem eine solche Struktur, + * damit ein bestimmter Handler beim Auffinden solcher Geraete aufgerufen wird. + * Jedes Feld enthaelt entweder eine Zahl, die mit der des Geraetes + * uebereinstimmen muss oder -1, dann wird dieses Feld ignoriert. + * \elseif english + * A USB device driver passes this structure to the OS so that a specific + * handler is called upon the detection of such a device. Each field either + * contains a number that has to be equal to that of the driver or -1, so that + * the field will be ignored. + * \endif + */ +struct cdi_usb_device_pattern { + int vendor_id; + int device_id; + int class_id; + int subclass_id; + int protocol_id; + + /** + * \if german + * + * Ueberprueft das angegebene USB-Geraet + * + * @param device Das Geraet + * + * @return 0, wenn dieses Geraet nicht vom Treiber verarbeitet werden kann, + * sonst 1 + * + * \elseif english + * + * Checks the given USB device + * + * @param device The device + * + * @return 0 if the driver is unable to handle this device, else 1 + * + * \endif + */ + int (*take_usb_device)(struct cdi_usb_device* device); +}; + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * \if german + * + * Entfernt einen USB-Bustreiber + * + * @param driver Der Treiber + * + * \elseif english + * + * Removes a USB bus driver + * + * @param driver The driver + * + * \endif + */ +void cdi_usb_driver_destroy(struct cdi_usb_driver* driver); + +/** + * \if german + * + * Initialisiert einen USB-Bustreiber + * + * @param driver Der Treiber + * + * \elseif english + * + * Initializes a USB bus driver + * + * @param driver The driver + * + * \endif + */ +void cdi_usb_driver_init(struct cdi_usb_driver* driver); + +/** + * \if german + * + * Registriert einen USB-Bustreiber beim System + * + * @param driver Der Treiber + * + * \elseif english + * + * Registers a USB bus driver at the OS + * + * @param driver The driver + * + * \endif + */ +void cdi_usb_driver_register(struct cdi_usb_driver* driver); + +/** + * \if german + * + * Registriert ein gefundenes USB-Geraet beim Betriebssystem - diese Funktion + * wird z. B. vom Host-Controller-Treiber nach einem Aufruf von find_devices + * fuer jedes gefundene Geraet aufgerufen + * + * @param device Das zu registrierende Geraet + * + * \elseif english + * + * Registers a detected USB device at the OS - this function is called i. e. by + * the host controller driver after a find_devices call for every device found + * + * @param device The device to be registered + */ +void cdi_usb_device_init(struct cdi_usb_device* device); + +/** + * \if german + * + * Registriert ein Geraetemuster + * + * @param pattern Das Muster + * + * \elseif english + * + * Registers a device pattern + * + * @param pattern The pattern + * + * \endif + */ +void cdi_usb_register_device_pattern(struct cdi_usb_device_pattern* pattern); + +#ifdef __cplusplus +} //extern "C" +#endif + +#endif -- 1.6.0.2
Antworten
- [cdi-devel] [PATCH v3 1/5] CDI.usb, CDI.usb-hcd · Kevin Wolf