USB Gadget API for Linux

所需积分/C币:10 2016-10-20 14:08:16 5.33MB PDF
收藏 收藏

USB Gadget API for Linux
speed controller, the SA-11x0 or PXA-25x UDC (found within many PDAs), and a variety of other proaucts Gadget Driver The lower boundary of this driver implements hardware-neutral UsB functions, using calls to the controller driver. Because such hardware varies widely in capabilities and restrictions, and is used in embedded environments where space is at a premium, the gadget driver is often configured at compile time to work with endpoints supported by one particular controller. Gadget drivers may be portable to several different controllers, using conditional compilation.(Recent kernels substantially simplify the work involved in supporting new hardware, by autoconfiguring endpoints automatically for many bulk-oriented drivers) Gadget driver responsibilities include: handling setup requests (epo protocol responses) possibly including class-specific functionality returning configuration and string descriptors (re) setting configurations and interface altsettings, including enabling and configuring endpoints handling life cycle events, such as managing bindings to hardware, USB suspend/ resume remote wakeup, and di sconnection from the USB host managing In and out transfers on all currently enabled endpoints Such drivers may be modules of proprietary code, al though that approach is discouraged in the Linux community. Upper Level Most gadget drivers have an upper boundary that connects to some Linux driver or framework in Linux. Through that boundary flows the data which the gadget driver produces and/or consumes through protocol transfers over USB. Examples include user mode code, using generic (gadgetfs) or application specific files in/dev networking subsystem (for network gadgets, like the CDC Ethernet Model gadget driver) data capture drivers, perhaps video4linux or a scanner driver: or test and measurement hardware input subsystem (for HID gadgets sound subsystem (for audio gadgets) file system (for PTP gadgets) block i/o subsystem (for usb-storage gadgets 3/25 and more Additional Layers Other layers may exist. These could include kernel layers, such as network protocol stacks, as well as user mode applications building on standard posiX system call APIs such as open(, close, read O and write O. On newer systems, POSIX Async 1/0 calls may be an option. Such user mode code will not necessarily be subject to the GNU General Public License (GPL) OTG-capable systems will also need to include a standard Linux-USB host side stack, with usbcore, one or more Host Controller Drivers(HCDs), USB Device Drivers to support the OtG Targeted Peripheral List, and so forth. There will also be an OTG Controller Driver, which is visible to gadget and device driver developers only indirectly. That helps the host and device side USB controllers implement the two new OTG protocols(HNP and SRP). Roles switch (host to peripheral, or vice versa) using hnP during USB suspend processing, and SrP can be viewed as a more battery-friendly kind of device wakeup protocol. Over time, reusable utilities are evolving to help make some gadget driver tasks simpler. For example, building configuration descriptors from vectors of descriptors for the configurations interfaces and endpoints is now automated, and many drivers now use autoconfiguration to choose hardware endpoints and initialize their descriptors. A potential example of particular interest is code implementing standard USB-IF protocols for HID, networking, storage, or audio classes. Some developers are interested in KDB or KGDB hooks, to let target hardware be remotely debugged. Most such USB protocol code doesnt need to be hardware-specific, any more than network protocols like Xll, Http or NFS are. Such gadget-side interface drivers should eventually be combined, to implement composite devices Chapter 3. Kernel Mode Gadget API Table of Contents Driver Life Cycle USB 2.0 Chapter 9 Types and Constants Core Ob jects and Methods Optional Utilities Gadget drivers declare themselves through a struct usb gadget driver, which is responsible for most parts of enumeration for a struct usb gadget. The response to a set configuration usually involves enabling one or more of the struct usb ep objects exposed by the gadget, and submitting one or more struct usb request buffers to transfer data. Understand those four data types, and their operations, and you will understand how this api works Incomplete Data Type descriptions This documentation was prepared using the standard Linux kernel docproc tool, which 4/25 turns text and in-code comments into sgml Docbook and then into usable formats such as HTML or PDF. Other than the Chapter 9 data types, most of the significant data types and functions are described he However, docproc does not unders tand all the c constructs that are used, so some relevant information is likely omitted from what you are reading. One example of such information is endpoint autoconfiguration, You ll have to read the header file, and use example source code (such as that for Gadget Zero), to fully understand the API The part of the api implementing some basic driver capabilities is specific to the version of the linux kernel that' s in use. The 2.6 kernel inc ludes a driver mode l framework that has no analogue on earlier kernels; so those parts of the gadget API are not fully portable. (They are implemented on 2. 4 kernels, but in a different way.)The driver model state is another part of this api that is ignored by the kerneldoc tools The core API does not expose every possible hardware feature, only the most widely available ones. There are significant hardware features, such as device-to-device dma (without temporary storage in a memory buffer) that would be added using hardware specific APIs This api allows drivers to use conditional compilation to handle endpoint capabilities of different hardware, but doesn t require that. Hardware tends to have arbitrary restrictions, relating to transfer types, addressing, packet sizes, buffering, and availability. As a rule, such differences only matter for"endpoint zero logic that handles device configuration and management. The API supports limited run-time detection of capabilities, through naming conventions for endpoints. Many drivers will be able to at least partially autoconfigure themselves. In particular, driver init sections will often have endpoint autoconfiguration logic that scans the hardware s list of endpoints to find ones matching the driver requirements (relying on those conventions), to eliminate some of the most common reasons for conditional compilation Like the Linux-USB host side aPl, this API exposes the chunky nature of USB messages 1/0 requests are in terms of one or more packets a and packet boundaries are visible to drivers. Compared to Rs-232 serial protocols, USB resembles synchronous protocols like hdlc n bytes per frame, multipoint addressing, host as the primary station and devices as secondary stations)more than asynchronous ones (tty style: 8 data bits per frame, no parity, one stop bit). So for example the controller drivers won't buffer two single byte writes into a single two-byte USB in packet, although gadget drivers may do so when they implement protocols where packet boundaries (and short packets" )are not significant Driver Life Cycle Gadget drivers make endpoint 1/0 requests to hardware without needing to know many details of the hardware, but driver setup/configuration code needs to handle some differences. Use the api like this Register a driver for the particular device side usb controller hardware, such as the net2280 on PCI (USB 2.0), sallx0 or pxa25x as found in Linux PDAs, and so on. At this point the device is logically in the USB ch9 initial state ( "attached"), drawing no 5/25 power and not usable (since it does not yet support enumeration). Any host should see the device, since it' s not activated the data line pullup used by the host to hot detect a device, even if vBUS power is available. Register a gadget driver that implements some higher level device function. That will then bindo to a usb gadget, which activates the data line pul lup sometime after detecting VBUS The hardware driver can now start enumerating. The steps it handles are to accept USB power and set address requests. Other steps are handled by the gadget driver. If the gadget driver module is unloaded before the host starts to enumerate, steps before step 7 are skipped The gadget driver's setup call returns usb descriptors, based both on what the bus interface hardware provides and on the functionality being implemented. That can involve alternate settings or configurations, unless the hardware prevents such operation. For otG devices, each configuration descriptor includes an OTG descriptor. The gadget driver handles the last step of enumeration, when the USB host issues a set configuration call. It enables all endpoints used in that configuration, with all interfaces in their default settings. That involves using a list of the hardware s endpoints, enabling each endpoint according to its descriptor. It may also involve using usb gadget vbus draw to let more power be drawn from VBUS, as allowed by that configuration. For OtG devices, setting a configuration may also involve reporting HNP capabilities through a user interface Do real work and perform data transfers, possibly involving changes to interface settings or switching to new configurations, until the device is disconnect Oed from the host. Queue any number of transfer requests to each endpoint. It may be suspended and resumed several times before being disconnected. On disconnect, the drivers go back to step 3(above) When the gadget driver module is being unloaded, the driver unbind( callback is issued That lets the controller driver be unloaded Drivers will normally be arranged so that just loading the gadget driver module (or statically linking it into a Linux kernel) allows the peripheral device to be enumerated, but some drivers will defer enumeration until some higher level component (like a user mode daemon) enables it. Note that at this lowest level there are no policies about how epo configuration logic is implemented, except that it should obey USB specifications. Such issues are in the domain of gadget drivers, inc luding knowing about implementation constraints imposed by some USB controllers or unders tanding that composite devices might happen to be built by integrating reusable components. Note that the lifecycle above can be slightly different for OTG devices. Other than providing an additional OtG descriptor in each configuration, only the HNP-related differences are particularly visible to driver code. They involve reporting requirements during the SET CONF IGURATION request, and the option to invoke HNP during some suspend callbacks. Also, SrP changes the semantics of usb gadget wakeup slightly 6/25 USB 2.0 Chapter 9 Types and Constants Gadget drivers rely on common USB structures and cons tants defined in the Linux/usb ch9. h> header file, which is standard in Linux 2. 6 kernels. These are the same types and constants used by host side drivers (and usbcore) struct usb ctrlrequest ame struct usb ctrlrequest- setUP data for a UsB device control request Synopsis struct usb ctrlrequest u8 bRequestType u8 bRequest le16 wValue: le16 wIndex le16 lEngth Me mbers bRequestType--matches the USB bmRequestType field bRequest--matches the USB bRequest field wValue--matches the USB wValue field (le16 byte order wIndex--matches the USB wIndex field (lel6 byte order wLength--matches the USB wLength field(le16 byte order) Description This structure is used to send control requests to a uSb device. It matches the different fields of the USB 2.0 Spec section 9.3, table 9-2. See the USB spec for a fuller description of the different fields, and what they are used for Note that the driver for any interface can issue control requests. For most devices, interfaces don t coordinate with each other, so such requests may be made at any time. Core Objects and Methods These are declared in <linux/usb gadget. h>, and are used by gadget drivers to interact with USB peripheral controller drivers struct usb request Name struct usb request- describes one i/o request nopsI s struct usb request I void s buf. unsigned length dma addr t dma unsigned no interrupt: 1 unsigned zero: 1 unsigned short not ok: 1 7/25 void(* complete)(struct usb ep ep struct usb request *reg) void = context struct list head list: Int status unsigned actual Members buf--Buffer used for data. Always provide this: some controllers only use PIO, or dont use DMa for some endpoints. length--Length of that data dma--DMA address corresponding to buf. If you don t set this field, and the usb controller needs one, it is responsible for mapping and unmapping the buffer. no interrupt--If true, hints that no completion irg is needed. Helpful sometimes with deep request queues that are handled directly by dMa controllers. zero--If true, when writing data, makes the last packet be "short" by adding a zero length packet as needed short not ok--When reading data, makes short packets be treated as errors (queue stops advancing till cleanup) complete--Function called when request completes, so this request and its buffer may be re-used. Reads terminate with a short packet, or when the buffer fills, whichever comes first. When writes terminate, some data bytes will usually still be in flight (often in a hardware fifo). Errors (for reads or writes) stop the queue from advancing until the completion function returns, so that any transfers invalidated by the error may first be dequeued context--For use by the completion callback ist--For use by the gadget driver. status--Reports completion code, zero or a negative errno. Normally, faults bl transfer queue from advancing until the completion callback returns. Code <ock the ESHUTDOWN" indicates completion caused by device disconnect, or when the driver disabled the endpoint actual--Reports bytes transferred to/ from the buffer. For reads (OUT transfers)this may be less than the requested length. If the short not ok flag is set, short reads are treated as errors even when status otherwise indicates successful completion. Note that for writes (IN transfers) some data bytes may still reside in a device-side Fifo when the request is reported as complete Description These are allocated/freed through the endpoint theyre used with. The hardware's driver can add extra per-request data to the memory it returns, which often avoids separate memory allocations (potential failures), later when the request is queued Request flags affect request handling, such as whether a zero length packet is written (the "zero" flag), whether a short read should be treated as an error (blocking request queue advance, the "short not ok" flag), or hinting that an interrupt is not required (the "no interrupt" flag, for use with deep request queues Bulk endpoints can use any size buffers, and can also be used for interrupt transfers. interrupt-only endpoints can be much less functional struct usb ep Name 8/25 struct usb ep- device side representation of USB endpoint gnosis struct usb ep void *k driver data const char name const struct usb ep ops * k ops: struct list head ep list unsigned maxpacket: 16 Members driver data--for use by the gadget driver. all other fields are read-only to gadget drivers name-- identifier for the endpoint, such as“ep-a”or“ep9in-bulk ops--Function pointers used to access hardware-specific operations. ep list--the gadgets ep list holds all of its endpoints axpacket--The maximum packet size used on this endpoint. The initial value can some times be reduced (hardware allowing), according to the endpoint descriptor used to configure the endpoint Description the bus controller driver lists all the general purpose endpoints in gadget>ep list the control endpoint (gadget->epo) is not in that list, and is accessed only in response to a driver setup callback. usb ep enable ame usb ep enable- configure endpoint, making it usable S gnosiS int usb ep enable( struct usb ep ep const struct usb endpoint descriptor desc) Arguments ep--the endpoint being configured. may not be the endpoint named " ep0". drivers discover endpoints through the ep list of a usb gadget. desc--descriptor for desired behavior. caller guarantees this pointer remains valid until the endpoint is disabled; the data byte order is little-endian (usb-standard Description when configurations are set, or when interface settings change, the driver will enable or disable the relevant endpoints. while it is enabled, an endpoint may be used for i/o until the driver receives a disconnect from the host or until the endpoint i disabled the epo implementation (which calls this routine)must ensure that the hardware capabilities of each endpoint match the descriptor provided for it. for example, an endpoint named "ep2in-bulk would be usable for interrupt transfers as well as bulk but it likely couldnt be used for iso transfers or for endpoint 14. some endpoints are fully configurable, with more generic names like "ep-a".(remember that for USB “in” means“ towards the usb master”.) returns zero, or a negative error code usb ep disable 9/25 Name usb ep disable- endpoint is no longer usable Synopsis int usb ep disable( struct usb ep *k ep) rguments epthe endpoint being unconfigured. may not be the endpoint named "ep0 scription no other task may be using this endpoint when this is called. any pending and uncompleted requests will complete with status indicating disconnect (-ESHUTDOWN before this call returns. gadget drivers must call usb ep enable again before queueing requests to the endpoint returns zero, or a negative error code usb ep alloc request Name usb ep alloc request- allocate a request object to use with this endpoint nosiS struct usb request usb ep alloc request struct usb ep ep, gfp t gfp flags) Arguments ep--the endpoint to be used with with the request gfp flags--GFP flags to use Description Request objects must be allocated with this call, since they normally need controller-specific setup and may even need endpoint-specific resources such as allocation of DMA descriptors. Requests may be submitted with usb ep queue, and receive a single completion callback. Free requests with usb ep free request, when they are no longer needed Returns the request, or null if one could not be allocated usb ep free request ame sb ep free request frees a request object Synopsis void usb ep free request struct usb ep ep struct usb request req Arguments ep--the endpoint associated with the request reg--the request being freed Description Reverses the effect of usb ep alloc request. Caller guarantees the request is not queued, and that it will no longer be requeued (or otherwise used) usb ep alloc buffer Name 10/25

试读 25P USB Gadget API for Linux
立即下载 低至0.43元/次 身份认证VIP会员低至7折
  • 分享达人

关注 私信
USB Gadget API for Linux 10积分/C币 立即下载
USB Gadget API for Linux第1页
USB Gadget API for Linux第2页
USB Gadget API for Linux第3页
USB Gadget API for Linux第4页
USB Gadget API for Linux第5页

试读结束, 可继续读3页

10积分/C币 立即下载 >