ChangeSet 1.1303.2.2, 2003/06/05 01:27:20-07:00, david-b@pacbell.net [PATCH] USB: kerneldoc for gadget API Here's the non-inlined doc for the gadget API. Documentation/DocBook/Makefile | 3 Documentation/DocBook/gadget.tmpl | 966 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 968 insertions(+), 1 deletion(-) diff -Nru a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile --- a/Documentation/DocBook/Makefile Thu Jun 5 13:45:07 2003 +++ b/Documentation/DocBook/Makefile Thu Jun 5 13:45:07 2003 @@ -11,7 +11,8 @@ kernel-locking.sgml via-audio.sgml mousedrivers.sgml \ deviceiobook.sgml procfs-guide.sgml tulip-user.sgml \ writing_usb_driver.sgml scsidrivers.sgml sis900.sgml \ - kernel-api.sgml journal-api.sgml lsm.sgml usb.sgml + kernel-api.sgml journal-api.sgml lsm.sgml usb.sgml \ + gadget.sgml ### # The build process is as follows (targets): diff -Nru a/Documentation/DocBook/gadget.tmpl b/Documentation/DocBook/gadget.tmpl --- /dev/null Wed Dec 31 16:00:00 1969 +++ b/Documentation/DocBook/gadget.tmpl Thu Jun 5 13:45:07 2003 @@ -0,0 +1,966 @@ + + + + USB Gadget API for Linux + 02 June 2003 + 02 June 2003 + + + Permission is granted to copy, distribute, and/or modify + this document under the terms of the GNU Free Documentation + License, version 1.2, or any later version published by the + Free Software Foundation; with the Invariant Sections being + the "GNU Free Documentation License", + no Front-Cover Texts, + and + no Back-Cover Texts. + + + This documentation is distributed in the hope that it will be + useful, but WITHOUT ANY WARRANTY; without even the implied + warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + See the GNU Free Documentation License for more details. + + + Note that certain sections of this document are merged + into Linux kernel source code. + That content is the bulk of + and + , + where the "GNU Free Documentation License" is identified + as an alternate licence for its documentation. + + + + + 2003 + David Brownell + + + + David + Brownell + +
dbrownell@users.sourceforge.net
+ + + + + + +Introduction + +This document presents a Linux-USB "Gadget" +kernel mode +API, for use within peripherals and other USB devices +that embed Linux. +It provides an overview of the API structure, +and shows how that fits into a system development project. +This is the first such API released on Linux to address +a number of important problems, including: + + + Supports USB 2.0, for high speed devices which + can stream data at several dozen megabytes per second. + + Handles devices with dozens of endpoints just as + well as ones with just two fixed-function ones. Gadget drivers + can be written so they're easy to port to new hardware. + + Flexible enough to expose more complex USB device + capabilities such as multiple configurations, multiple interfaces, + composite devices, + and alternate interface settings. + + Sharing data structures and API models with the + Linux-USB host side API. This looks forward to USB "On-The-Go" + (OTG) and similar more-symmetric frameworks. + + Minimalist, so it's easier to support new device + controller hardware. I/O processing doesn't imply large + demands for memory or CPU resources. + + + + +Most Linux developers will not be able to use this API, since they +have USB "host" hardware in a PC, workstation, or server. +Linux users with embedded systems are more likely to +have USB peripheral hardware. +To distinguish drivers running inside such hardware from the +more familiar Linux "USB device drivers", +which are host side proxies for the real USB devices, +a different term is used: +the drivers inside the peripherals are "USB gadget drivers". +In USB protocol interactions, the device driver is the master +(or "client driver") +and the gadget driver is the slave (or "function driver"). + + +The gadget API resembles the host side Linux-USB API in that both +use queues of request objects to package I/O buffers, and those requests +may be submitted or canceled. +They share common definitions for the standard USB +Chapter 9 messages, structures, and constants. +Also, both APIs bind and unbind drivers to devices. +The APIs differ in detail, since the host side's current +URB framework exposes a number of implementation details +and assumptions that are inappropriate for a gadget API. +While the model for control transfers and configuration +management is necessarily different (one side is a hardware-neutral master, +the other is a hardware-aware slave), the endpoint I/0 API used here +should also be usable for an overhead-reduced host side API. + + + + +Structure of Gadget Drivers + +A system running inside a USB peripheral +normally has at least three layers inside the kernel to handle +USB protocol processing, and may have additional layers in +user space code. +The "gadget" API is used by the middle layer to interact +with the lowest level (which directly handles hardware). + + +In Linux, from the bottom up, these layers are: + + + + + + USB Controller Driver + + + This is the lowest software level. + It is the only layer that talks to hardware, + through registers, fifos, dma, irqs, and the like. + The <linux/usb_gadget.h> API abstracts + the peripheral controller endpoint hardware. + That hardware is exposed through endpoint objects, which accept + streams of IN/OUT buffers, and through callbacks that interact + with gadget drivers. + Since normal USB devices only have one upstream + port, they only have one of these drivers. + The controller driver can support any number of different + gadget drivers, but only one of them can be used at a time. + + + Examples of such controller hardware include + the PCI-based NetChip 2280 USB 2.0 high speed controller, + the SA-11x0 or PXA-25x UDC (found within many PDAs), + and a variety of other products. + + + + + 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, + the gadget driver is normally 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. + Gadget driver responsibilities include: + + + handling setup requests (ep0 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, and disconnection from the USB host. + + managing IN and OUT transfers on all currently + enabled endpoints + + + + + Such drivers may be modules of proprietary code, although + 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) + + ... 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() and write(). + On newer systems, POSIX Async I/O calls may be an option. + Such user mode code will not necessarily be subject to + the GNU General Public License (GPL). + + + + + + +Over time, reusable utilities should evolve to help make some +gadget driver tasks simpler. An 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 doesn't need to be hardware-specific, +any more than network protocols like X11, HTTP, or NFS are. +Such interface drivers might be combined, to support composite devices. + + + + + +Kernel Mode Gadget API + +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 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 here. + + +However, docproc does not understand 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 several per-request flags. +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.5 kernel includes a driver model +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 expects drivers to use conditional compilation to handle +endpoint capabilities of different hardware. +Those tend 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 only supports limited run-time +detection of capabilities, through naming conventions for endpoints. +Although a gadget driver could scan the endpoints available to it and +choose to map those capabilities onto driver functionality in some way, +few drivers will want to reconfigure themselves at run-time. + + +Like the Linux-USB host side API, this API exposes +the "chunky" nature of USB messages: I/O requests are in terms +of one or more "packets", 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 from the host) +more than asynchronous ones +(tty style, like 8 bytes, 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 I/O 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), +sa11x0 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 power and not usable +(since it does not yet support enumeration). + + +Register a gadget driver that implements some higher level +device function. That will then bind() to a usb_gadget. + + +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. + + +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. + + +Do real work and perform data transfers, possibly involving +changes to interface settings or switching to new configurations, until the +device is disconnect()ed from the host. +Queue any number of transfer requests to each endpoint. +The drivers then 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. +Note that at this lowest level there are no policies about how +ep0 configuration logic is implemented, +except that it should obey USB specifications. +Such issues are in the domain of gadget drivers, +including knowing about implementation constraints +imposed by some USB controllers +or understanding that composite devices might happen to +be built by integrating reusable components. + + + + +USB 2.0 Chapter 9 Types and Constants + +Gadget drivers +rely on common USB structures and constants +defined in the +<linux/usb_ch9.h> +header file, which is standard in Linux 2.5 kernels. +These are the same types and constants used by host +side drivers. + + +!Iinclude/linux/usb_ch9.h + + +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. + + + + +!Iinclude/linux/usb_gadget.h + + +Optional Utilities + +The core API is sufficient for writing a USB Gadget Driver, +but some optional utilities are provided to simplify common tasks. + + +!Edrivers/usb/gadget/usbstring.c + + + + +Peripheral Controller Drivers + +The first hardware supporting this API is the NetChip 2280 +controller, which supports USB 2.0 high speed and is based on PCI. +This is the net2280 driver module. +The driver supports Linux kernel versions 2.4 and 2.5; +contact NetChip Technologies for development boards and product +information. + + + + +A partial USB simulator, +the dummy_hcd driver, is available. +It can act like a net2280, a pxa25x, or an sa11x0 in terms +of available endpoints and device speeds; and it simulates +control, bulk, and to some extent interrupt transfers. +That lets you develop some parts of a gadget driver on a normal PC, +without any special hardware, and perhaps with the assistance +of tools such as GDB running with User Mode Linux. +At least one person has expressed interest in adapting that +approach, hooking it up to a simulator for a microcontroller. +Such simulators can help debug subsystems where the runtime hardware +is unfriendly to software development, or is not yet available. + + +Support for other controllers is expected to be developed +and contributed +over time, as this driver framework evolves. + + + + +Gadget Drivers + +In addition to Gadget Zero +(used primarily for testing and development with drivers +for usb controller hardware), other gadget drivers exist. + + +There's an ethernet gadget +driver, which implements one of the most useful +Communications Device Class models. +One of the standards for cable modem interoperability even +specifies the use of this ethernet model as one of two +mandatory options. +Gadgets using this code look to a USB host as if they're +an Ethernet adapter. +It provides access to a network where the gadget's CPU is one host, +which could easily be bridging, routing, or firewalling +access to other networks. + + +There is also support for user mode gadget drivers, +using gadgetfs. +This provides a User Mode API that presents +each endpoint as a single file descriptor. I/O is done using +normal read() and read() calls. +Familiar tools like GDB and pthreads can be used to +develop and debug user mode drivers, so that once a robust +controller driver is available many applications for it +won't require new kernel mode software. + + +Support for other kinds of gadget is expected to +be developed and contributed +over time, as this driver framework evolves. + + + + + + +GNU Free Documentation License +Version 1.2, November 2002 + + + +PREAMBLE + +The purpose of this License is to make a manual, textbook, or +other functional and useful document "free" in the sense of freedom: to +assure everyone the effective freedom to copy and redistribute it, with +or without modifying it, either commercially or noncommercially. +Secondarily, this License preserves for the author and publisher a way +to get credit for their work, while not being considered responsible for +modifications made by others. + +This License is a kind of "copyleft", which means that derivative +works of the document must themselves be free in the same sense. It +complements the GNU General Public License, which is a copyleft license +designed for free software. + +We have designed this License in order to use it for manuals for +free software, because free software needs free documentation: a free +program should come with manuals providing the same freedoms that the +software does. But this License is not limited to software manuals; it +can be used for any textual work, regardless of subject matter or +whether it is published as a printed book. We recommend this License +principally for works whose purpose is instruction or reference. + + +APPLICABILITY AND DEFINITIONS + +This License applies to any manual or other work, in +any medium, that contains a notice placed by the copyright holder saying +it can be distributed under the terms of this License. Such a notice +grants a world-wide, royalty-free license, unlimited in duration, to use +that work under the conditions stated herein. The "Document", below, +refers to any such manual or work. Any member of the public is a +licensee, and is addressed as "you". You accept the license if you +copy, modify or distribute the work in a way requiring permission under +copyright law. + +A "Modified Version" of the Document means any +work containing the Document or a portion of it, either copied verbatim, +or with modifications and/or translated into another language. + +A "Secondary Section" is a named appendix or +a front-matter section of the Document that deals exclusively with the +relationship of the publishers or authors of the Document to the +Document's overall subject (or to related matters) and contains nothing +that could fall directly within that overall subject. (Thus, if the +Document is in part a textbook of mathematics, a Secondary Section may +not explain any mathematics.) The relationship could be a matter of +historical connection with the subject or with related matters, or of +legal, commercial, philosophical, ethical or political position +regarding them. + +The "Invariant Sections" are certain Secondary +Sections whose titles are designated, as being those of Invariant +Sections, in the notice that says that the Document is released under +this License. If a section does not fit the above definition of +Secondary then it is not allowed to be designated as Invariant. The +Document may contain zero Invariant Sections. If the Document does not +identify any Invariant Sections then there are none. + +The "Cover Texts" are certain short passages of +text that are listed, as Front-Cover Texts or Back-Cover Texts, in the +notice that says that the Document is released under this License. A +Front-Cover Text may be at most 5 words, and a Back-Cover Text may be at +most 25 words. + +A "Transparent" copy of the Document means a +machine-readable copy, represented in a format whose specification is +available to the general public, that is suitable for revising the +document straightforwardly with generic text editors or (for images +composed of pixels) generic paint programs or (for drawings) some widely +available drawing editor, and that is suitable for input to text +formatters or for automatic translation to a variety of formats suitable +for input to text formatters. A copy made in an otherwise Transparent +file format whose markup, or absence of markup, has been arranged to +thwart or discourage subsequent modification by readers is not +Transparent. An image format is not Transparent if used for any +substantial amount of text. A copy that is not "Transparent" is called +"Opaque". + +Examples of suitable formats for Transparent copies include plain +ASCII without markup, Texinfo input format, LaTeX input format, SGML or +XML using a publicly available DTD, and standard-conforming simple HTML, +PostScript or PDF designed for human modification. Examples of +transparent image formats include PNG, XCF and JPG. Opaque formats +include proprietary formats that can be read and edited only by +proprietary word processors, SGML or XML for which the DTD and/or +processing tools are not generally available, and the machine-generated +HTML, PostScript or PDF produced by some word processors for output +purposes only. + +The "Title Page" means, for a printed book, +the title page itself, plus such following pages as are needed to hold, +legibly, the material this License requires to appear in the title page. +For works in formats which do not have any title page as such, "Title +Page" means the text near the most prominent appearance of the work's +title, preceding the beginning of the body of the text. + +A section "Entitled XYZ" means a named subunit +of the Document whose title either is precisely XYZ or contains XYZ in +parentheses following text that translates XYZ in another language. +(Here XYZ stands for a specific section name mentioned below, such as +"Acknowledgements", "Dedications", "Endorsements", or "History".) To +"Preserve the Title" of such a section when you modify the Document +means that it remains a section "Entitled XYZ" according to this +definition. + +The Document may include Warranty Disclaimers next to the notice +which states that this License applies to the Document. These Warranty +Disclaimers are considered to be included by reference in this License, +but only as regards disclaiming warranties: any other implication that +these Warranty Disclaimers may have is void and has no effect on the +meaning of this License. + + +VERBATIM COPYING + +You may copy and distribute the Document in any medium, either +commercially or noncommercially, provided that this License, the +copyright notices, and the license notice saying this License applies to +the Document are reproduced in all copies, and that you add no other +conditions whatsoever to those of this License. You may not use +technical measures to obstruct or control the reading or further copying +of the copies you make or distribute. However, you may accept +compensation in exchange for copies. If you distribute a large enough +number of copies you must also follow the conditions in section 3. + + +You may also lend copies, under the same conditions stated above, +and you may publicly display copies. + + +COPYING IN QUANTITY + +If you publish printed copies (or copies in media that commonly +have printed covers) of the Document, numbering more than 100, and the +Document's license notice requires Cover Texts, you must enclose the +copies in covers that carry, clearly and legibly, all these Cover Texts: +Front-Cover Texts on the front cover, and Back-Cover Texts on the back +cover. Both covers must also clearly and legibly identify you as the +publisher of these copies. The front cover must present the full title +with all words of the title equally prominent and visible. You may add +other material on the covers in addition. Copying with changes limited +to the covers, as long as they preserve the title of the Document and +satisfy these conditions, can be treated as verbatim copying in other +respects. + +If the required texts for either cover are too voluminous to fit +legibly, you should put the first ones listed (as many as fit +reasonably) on the actual cover, and continue the rest onto adjacent +pages. + +If you publish or distribute Opaque copies of the Document +numbering more than 100, you must either include a machine-readable +Transparent copy along with each Opaque copy, or state in or with each +Opaque copy a computer-network location from which the general +network-using public has access to download using public-standard +network protocols a complete Transparent copy of the Document, free of +added material. If you use the latter option, you must take reasonably +prudent steps, when you begin distribution of Opaque copies in quantity, +to ensure that this Transparent copy will remain thus accessible at the +stated location until at least one year after the last time you +distribute an Opaque copy (directly or through your agents or retailers) +of that edition to the public. + +It is requested, but not required, that you contact the authors of +the Document well before redistributing any large number of copies, to +give them a chance to provide you with an updated version of the +Document. + + +MODIFICATIONS + +You may copy and distribute a Modified Version of the Document +under the conditions of sections 2 and 3 above, provided that you +release the Modified Version under precisely this License, with the +Modified Version filling the role of the Document, thus licensing +distribution and modification of the Modified Version to whoever +possesses a copy of it. In addition, you must do these things in the +Modified Version: + + +Use in the Title Page (and on the covers, if any) a + title distinct from that of the Document, and from those of previous + versions (which should, if there were any, be listed in the History + section of the Document). You may use the same title as a previous + version if the original publisher of that version gives permission. + +List on the Title Page, as authors, one or more + persons or entities responsible for authorship of the modifications in + the Modified Version, together with at least five of the principal + authors of the Document (all of its principal authors, if it has fewer + than five), unless they release you from this requirement. + +State on the Title page the name of the publisher of + the Modified Version, as the publisher. +Preserve all the copyright notices of the Document. + +Add an appropriate copyright notice for your + modifications adjacent to the other copyright notices. + +Include, immediately after the copyright notices, a + license notice giving the public permission to use the Modified + Version under the terms of this License, in the form shown in the + Addendum below. + +Preserve in that license notice the full lists of + Invariant Sections and required Cover Texts given in the Document's + license notice. +Include an unaltered copy of this License. + +Preserve the section Entitled "History", Preserve its + Title, and add to it an item stating at least the title, year, new + authors, and publisher of the Modified Version as given on the Title + Page. If there is no section Entitled "History" in the Document, + create one stating the title, year, authors, and publisher of the + Document as given on its Title Page, then add an item describing the + Modified Version as stated in the previous sentence. + +Preserve the network location, if any, given in the + Document for public access to a Transparent copy of the Document, and + likewise the network locations given in the Document for previous + versions it was based on. These may be placed in the "History" + section. You may omit a network location for a work that was + published at least four years before the Document itself, or if the + original publisher of the version it refers to gives permission. + +For any section Entitled "Acknowledgements" or + "Dedications", Preserve the Title of the section, and preserve in the + section all the substance and tone of each of the contributor + acknowledgements and/or dedications given therein. + +Preserve all the Invariant Sections of the Document, + unaltered in their text and in their titles. Section numbers or the + equivalent are not considered part of the section titles. + +Delete any section Entitled "Endorsements". + Such a section may not be included in the Modified Version. + +Do not retitle any existing section to be Entitled + "Endorsements" or to conflict in title with any Invariant Section. + +Preserve any Warranty Disclaimers. + + + +If the Modified Version includes new front-matter sections or +appendices that qualify as Secondary Sections and contain no material +copied from the Document, you may at your option designate some or all +of these sections as invariant. To do this, add their titles to the +list of Invariant Sections in the Modified Version's license notice. +These titles must be distinct from any other section titles. + +You may add a section Entitled "Endorsements", provided it +contains nothing but endorsements of your Modified Version by various +parties--for example, statements of peer review or that the text has +been approved by an organization as the authoritative definition of a +standard. + +You may add a passage of up to five words as a Front-Cover Text, +and a passage of up to 25 words as a Back-Cover Text, to the end of the +list of Cover Texts in the Modified Version. Only one passage of +Front-Cover Text and one of Back-Cover Text may be added by (or through +arrangements made by) any one entity. If the Document already includes +a cover text for the same cover, previously added by you or by +arrangement made by the same entity you are acting on behalf of, you may +not add another; but you may replace the old one, on explicit permission +from the previous publisher that added the old one. + +The author(s) and publisher(s) of the Document do not by this +License give permission to use their names for publicity for or to +assert or imply endorsement of any Modified Version. + + +COMBINING DOCUMENTS + +You may combine the Document with other documents released under +this License, under the terms defined in section +4 above for modified versions, provided that you include in the +combination all of the Invariant Sections of all of the original +documents, unmodified, and list them all as Invariant Sections of your +combined work in its license notice, and that you preserve all their +Warranty Disclaimers. + +The combined work need only contain one copy of this License, and +multiple identical Invariant Sections may be replaced with a single +copy. If there are multiple Invariant Sections with the same name but +different contents, make the title of each such section unique by adding +at the end of it, in parentheses, the name of the original author or +publisher of that section if known, or else a unique number. Make the +same adjustment to the section titles in the list of Invariant Sections +in the license notice of the combined work. + +In the combination, you must combine any sections Entitled +"History" in the various original documents, forming one section +Entitled "History"; likewise combine any sections Entitled +"Acknowledgements", and any sections Entitled "Dedications". You must +delete all sections Entitled "Endorsements". + + +COLLECTIONS OF DOCUMENTS + +You may make a collection consisting of the Document and other +documents released under this License, and replace the individual copies +of this License in the various documents with a single copy that is +included in the collection, provided that you follow the rules of this +License for verbatim copying of each of the documents in all other +respects. + +You may extract a single document from such a collection, and +distribute it individually under this License, provided you insert a +copy of this License into the extracted document, and follow this +License in all other respects regarding verbatim copying of that +document. + + +AGGREGATION WITH INDEPENDENT WORKS + +A compilation of the Document or its derivatives with other +separate and independent documents or works, in or on a volume of a +storage or distribution medium, is called an "aggregate" if the +copyright resulting from the compilation is not used to limit the legal +rights of the compilation's users beyond what the individual works +permit. When the Document is included an aggregate, this License does +not apply to the other works in the aggregate which are not themselves +derivative works of the Document. + +If the Cover Text requirement of section 3 is applicable to these +copies of the Document, then if the Document is less than one half of +the entire aggregate, the Document's Cover Texts may be placed on covers +that bracket the Document within the aggregate, or the electronic +equivalent of covers if the Document is in electronic form. Otherwise +they must appear on printed covers that bracket the whole +aggregate. + + +TRANSLATION + +Translation is considered a kind of modification, so you may +distribute translations of the Document under the terms of section 4. +Replacing Invariant Sections with translations requires special +permission from their copyright holders, but you may include +translations of some or all Invariant Sections in addition to the +original versions of these Invariant Sections. You may include a +translation of this License, and all the license notices in the +Document, and any Warranty Disclaimers, provided that you also include +the original English version of this License and the original versions +of those notices and disclaimers. In case of a disagreement between the +translation and the original version of this License or a notice or +disclaimer, the original version will prevail. + +If a section in the Document is Entitled "Acknowledgements", +"Dedications", or "History", the requirement (section 4) to Preserve its +Title (section 1) will typically require changing the actual +title. + + +TERMINATION + +You may not copy, modify, sublicense, or distribute the Document +except as expressly provided for under this License. Any other attempt +to copy, modify, sublicense or distribute the Document is void, and will +automatically terminate your rights under this License. However, +parties who have received copies, or rights, from you under this License +will not have their licenses terminated so long as such parties remain +in full compliance. + + +FUTURE REVISIONS OF THIS LICENSE + +The Free Software Foundation may publish new, revised versions of +the GNU Free Documentation License from time to time. Such new versions +will be similar in spirit to the present version, but may differ in +detail to address new problems or concerns. See +http://www.gnu.org/copyleft/. + +Each version of the License is given a distinguishing version +number. If the Document specifies that a particular numbered version of +this License "or any later version" applies to it, you have the option +of following the terms and conditions either of that specified version +or of any later version that has been published (not as a draft) by the +Free Software Foundation. If the Document does not specify a version +number of this License, you may choose any version ever published (not +as a draft) by the Free Software Foundation. + + +ADDENDUM: How to use this License for + your documents + +To use this License in a document you have written, include a copy +of the License in the document and put the following copyright and +license notices just after the title page: + + + +If you have Invariant Sections, Front-Cover Texts and Back-Cover +Texts, replace the "with...Texts." line with this: + +
+ with the Invariant Sections being LIST THEIR TITLES, with the + Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. +
+ +If you have Invariant Sections without Cover Texts, or some other +combination of the three, merge those two alternatives to suit the +situation. + +If your document contains nontrivial examples of program code, we +recommend releasing these examples in parallel under your choice of free +software license, such as the GNU General Public License, to permit +their use in free software. + + + + +