SAMV71 Xplained Ultra Software Package 1.4

cdc-serial.dir

00001 /* ----------------------------------------------------------------------------
00002  *         ATMEL Microcontroller Software Support 
00003  * ----------------------------------------------------------------------------
00004  * Copyright (c) 2008, Atmel Corporation
00005  *
00006  * All rights reserved.
00007  *
00008  * Redistribution and use in source and binary forms, with or without
00009  * modification, are permitted provided that the following conditions are met:
00010  *
00011  * - Redistributions of source code must retain the above copyright notice,
00012  * this list of conditions and the disclaimer below.
00013  *
00014  * Atmel's name may not be used to endorse or promote products derived from
00015  * this software without specific prior written permission.
00016  *
00017  * DISCLAIMER: THIS SOFTWARE IS PROVIDED BY ATMEL "AS IS" AND ANY EXPRESS OR
00018  * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
00019  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT ARE
00020  * DISCLAIMED. IN NO EVENT SHALL ATMEL BE LIABLE FOR ANY DIRECT, INDIRECT,
00021  * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
00022  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA,
00023  * OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
00024  * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
00025  * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
00026  * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
00027  * ----------------------------------------------------------------------------
00028  */
00029 
00030 /** \dir usb/device/cdc-serial
00031  *
00032  *  \section Purpose
00033  * 
00034  *  This directory provides definitions, structs and functions for a USB CDC
00035  *  device - USB CDC Serial Converter demo, to implement an USB Serial COM port
00036  *  driver.
00037  * 
00038  *  \section Contents
00039  * 
00040  *  There are two things for the implement of the USB CDC Serial device driver:
00041  *  - Implement the CDC Serial driver structs and functions for the device,
00042  *    to initialize, to handle CDC-specific requests and dispach
00043  *    standard requests in USBD callbacks, to read/write through assigned USB
00044  *    endpoints,
00045  *  - Create the CDC Serial device's descriptors that should be passed to
00046  *    the USBDDriver instance on initialization, so that the host can 
00047  *    recognize the device as a USB CDC Serial COM port device.
00048  * 
00049  *  For more information about what a particular group contains, please refer to
00050  *  \ref usbd_cdc "USB CDC Library" and
00051  *  \ref usbd_cdc_serial_drv "USB CDC Driver Doc".
00052  */
00053 
00054 /**
00055  \page usbd_cdc_serial_drv USB Device CDC Serial Driver
00056 
00057  \section Purpose
00058  This page describes how to use the USB framework to produce a USB CDC Serial
00059  Device driver, which appears as a virtual COM port on host.
00060 
00061  \section References
00062  - \ref usbd_framework "AT91 USB device framework"
00063  - \ref usbd_enum "USB Device Enumeration"
00064  - <a href="http://www.usb.org/developers/docs/usb_20_040908.zip">
00065    Universal Serial Bus Revision 2.0 specification
00066    </a> (.zip file format, size 9.80 MB)
00067  - <a href="http://www.usb.org/developers/devclass_docs/CDC1.2_WMC1.1.zip">
00068    Communication Device Class Documents</a> (.zip file format)
00069  - Abstract Control Model Serial Emulation (USB Class Definitions for
00070    Communication Devices, section 3.6.2.1).
00071 
00072  \section cdc Communication Device Class
00073 
00074  \subsection Purpose
00075 
00076  CDC is used to connect communication devices, such as modems (digital or
00077  analog), telephones or networking devices. Its generic framework supports a
00078  wide variety of physical layers (xDSL, ATM, etc.) and protocols.
00079 
00080  In this document, CDC is used to implement a USB to a serial data converter.
00081  A USB to serial converter can be used in this case to bridge a legacy RS-232
00082  interface with a USB port.
00083 
00084  \subsection Architecture
00085  
00086  \subsubsection cdc_if Communication Class Interface
00087  The <b>Communication Class Interface</b> is used for device management. It
00088  includes requests to manage the device state, its responses, as well as
00089  event notifications. This interface can also be optionally used for call
00090  management, i.e., setting up and terminating calls as well as managing
00091  their parameters.
00092 
00093  The interface requires at least one endpoint (<b>Default EP0</b>) to used for
00094  device management. Optionally, another endpoint can be dedicated to
00095  event notification. This will usually be an <b>Interrupt IN</b> endpoint.
00096 
00097  \subsubsection data_class_if Data Class Interface
00098  The <b>Data Class Interface</b> is used for generic data transmissions. It provides
00099  a means for a communication device to actually transfer data to and from the
00100  host. In addition, it also enables the multiplexing of data and commands on
00101  the same interface, through the use of wrappers.
00102 
00103  endpoints for this interface must exist in pairs of the same type. This is
00104  necessary to allow both IN and OUT communication. Only the <b>Bulk</b> and
00105  <b>Isochronous</b> types can be used for these endpoints.
00106 
00107  \image html CDCArchitecture.png "CDC Class Driver Architecture"
00108 
00109  \subsubsection Models
00110  To account for the wide variety of existing communication devices, several
00111  <b>models</b> have been defined, for more details you can refer to CDC spec. 1.1.
00112  - POTS (Plain Old Telephone Service)
00113     - Direct Line Control Model
00114     - Datapump Model
00115     - Abstract Control Model (ACM)
00116  - Telephone
00117     - Telephone Control Model
00118  - ISDN
00119     - Multi-Channel Model
00120     - USB CAPI Model
00121  - Networking
00122     - Ethernet Networking Model
00123     - ATM Networking Control Model
00124 
00125  \subsubsection class_spec_desc Class-specific Descriptors
00126  CDC-specific information is described using Functional Descriptors. They
00127  define various parameters of an interface, such as how the device handles
00128  call management, or model-specific attributes.
00129 
00130  Since the CDC specification defines quite a number of functional descriptors,
00131  they are not detailed here. Instead, they are presented in the various case
00132  studies of this document in which they are used.
00133 
00134  \subsection host_drv Host Drivers
00135  Most Operating Systems (OS) now include generic drivers for a wide variety of
00136  USB classes. This makes developing a device simpler, since the host complexity
00137  is now handled by the OS. Manufacturers can thus concentrate on the device
00138  itself, not on developing specific host drivers.
00139 
00140  Here is a brief list of the various CDC implementations supported by several
00141  OS:
00142  - Windows
00143      - Abstract Control Model
00144      - Remote NDIS
00145  - Linux
00146      - Abstract Control Model
00147      - Ethernet Model
00148 
00149  \section usb_serial_conv USB to Serial Converter
00150  This section describes the implementation of the USB to serial converter using
00151  the CDC class and the AT91 USB Device Framework.
00152 
00153  \subsection brige Bridging a Legacy Device and a Host with USB-Serial Converter
00154  \image html USB-SerialConverter.png
00155 
00156  \subsection Model
00157  The CDC specification defines a model which suits this application perfectly:
00158  the <b>Abstract Control Model (ACM)</b>. It implements the requests and
00159  notifications necessary to communicate with an RS-232 interface.
00160 
00161  The Abstract Control Model requires two interfaces, one <b>Communication Class
00162  Interface</b> and one <b>Data Class Interface</b>. Each of them must have two
00163  associated endpoints. The former shall have one endpoint dedicated to device
00164  management (default Control endpoint 0) and one for events notification
00165  (additional Interrupt IN endpoint).
00166 
00167  The Data Class Interface needs two endpoints through which to carry data to
00168  and from the host. Depending on the application, these endpoints can either
00169  be Bulk or Isochronous. In the case of a USB to serial converter, using Bulk
00170  endpoints is probably more appropriate, since the reliability of the
00171  transmission is important and the data transfers are not time-critical.
00172 
00173  \subsection Descriptors
00174  The descriptors are modtly standard ones. The following code examples thus
00175  use the structures described in the \ref usbd_framework "AT91 USB device framework".
00176 
00177  For CDC-specific descriptors, some new types are defined:
00178  - \ref CDCHeaderDescriptor
00179  - \ref CDCCallManagementDescriptor
00180  - \ref CDCAbstractControlManagementDescriptor
00181  - \ref CDCUnionDescriptor
00182 
00183  All the descriptors can be found in CDCDSerialDriverDescriptors.c.
00184 
00185  \subsubsection dev_desc Device Descriptor
00186  \code
00187 const USBDeviceDescriptor deviceDescriptor = {
00188     sizeof(USBDeviceDescriptor),
00189     USBGenericDescriptor_DEVICE,
00190     USBDeviceDescriptor_USB2_00,
00191     CDCDeviceDescriptor_CLASS,
00192     CDCDeviceDescriptor_SUBCLASS,
00193     CDCDeviceDescriptor_PROTOCOL,
00194     BOARD_USB_ENDPOINTS_MAXPACKETSIZE(0),
00195     CDCDSerialDriverDescriptors_VENDORID,
00196     CDCDSerialDriverDescriptors_PRODUCTID,
00197     CDCDSerialDriverDescriptors_RELEASE,
00198     0, // No string descriptor for manufacturer
00199     1, // Index of product string descriptor is #1
00200     0, // No string descriptor for serial number
00201     1 // Device has 1 possible configuration
00202 };
00203  \endcode
00204  The Vendor ID and Product ID fields are used to determine which driver to use
00205  when the device is enumerated. The Vendor ID is provided by the USB-IF
00206  organization after registration; the product ID is completely vendor-specific.
00207  In the example implementation provided with this document, the Atmel vendor ID
00208  (03EBh) is used along with a custom product ID (6119h).
00209 
00210  The configuration descriptor is followed by interface, endpoint and class-
00211  specific descriptors.
00212 \code
00213 const CDCDSerialDriverConfigurationDescriptors configurationDescriptors[];
00214 \endcode
00215 
00216  \subsubsection cfg_desc Configuration Descriptor
00217 \code
00218     {
00219         sizeof(USBConfigurationDescriptor),
00220         USBGenericDescriptor_CONFIGURATION,
00221         sizeof(CDCDSerialDriverConfigurationDescriptors),
00222         2, // There are two interfaces in this configuration
00223         1, // This is configuration #1
00224         0, // No string descriptor for this configuration
00225         BOARD_USB_BMATTRIBUTES,
00226         USBConfigurationDescriptor_POWER(100)
00227     },
00228 \endcode
00229 
00230  \subsubsection ccif_desc Communication Class Interface Descriptor
00231  The bInterfaceClass should be set to 0x02 and bInterfaceSubClass should be set
00232  to 0x02.
00233 \code
00234     {
00235         sizeof(USBInterfaceDescriptor),
00236         USBGenericDescriptor_INTERFACE,
00237         0, // This is interface #0
00238         0, // This is alternate setting #0 for this interface
00239         1, // This interface uses 1 endpoint
00240         CDCCommunicationInterfaceDescriptor_CLASS,
00241         CDCCommunicationInterfaceDescriptor_ABSTRACTCONTROLMODEL,
00242         CDCCommunicationInterfaceDescriptor_NOPROTOCOL,
00243         0  // No string descriptor for this interface
00244     },
00245 \endcode
00246 
00247  \subsubsection fun_hdr_desc Functional - Header Descriptor
00248 \code
00249     {
00250         sizeof(CDCHeaderDescriptor),
00251         CDCGenericDescriptor_INTERFACE,
00252         CDCGenericDescriptor_HEADER,
00253         CDCGenericDescriptor_CDC1_10
00254     },
00255 \endcode
00256 
00257  \subsubsection fun_cm_desc Functional - Call Management Descriptor
00258 \code
00259     {
00260         sizeof(CDCCallManagementDescriptor),
00261         CDCGenericDescriptor_INTERFACE,
00262         CDCGenericDescriptor_CALLMANAGEMENT,
00263         CDCCallManagementDescriptor_SELFCALLMANAGEMENT,
00264         0 // No associated data interface
00265     },
00266 \endcode
00267 
00268  \subsubsection fun_acm_desc Functional - Abstract Control Management Descriptor
00269 \code
00270     {
00271         sizeof(CDCAbstractControlManagementDescriptor),
00272         CDCGenericDescriptor_INTERFACE,
00273         CDCGenericDescriptor_ABSTRACTCONTROLMANAGEMENT,
00274         CDCAbstractControlManagementDescriptor_LINE
00275     },
00276 \endcode
00277 
00278  \subsubsection fun_u_desc Functional - Union Descriptor
00279 \code
00280     {
00281         sizeof(CDCUnionDescriptor),
00282         CDCGenericDescriptor_INTERFACE,
00283         CDCGenericDescriptor_UNION,
00284         0, // Number of master interface is #0
00285         1 // First slave interface is #1
00286     },
00287 \endcode
00288 
00289  \subsubsection notification_ep_desc Notification Endpoint Descriptor
00290  The EP is defined as CDCDSerialDriverDescriptors_NOTIFICATION.
00291 \code
00292     {
00293         sizeof(USBEndpointDescriptor), 
00294         USBGenericDescriptor_ENDPOINT,
00295         USBEndpointDescriptor_ADDRESS(USBEndpointDescriptor_IN,
00296                      CDCDSerialDriverDescriptors_NOTIFICATION),
00297         USBEndpointDescriptor_INTERRUPT,
00298         MIN(BOARD_USB_ENDPOINTS_MAXPACKETSIZE(
00299                      CDCDSerialDriverDescriptors_NOTIFICATION),
00300             USBEndpointDescriptor_MAXINTERRUPTSIZE_FS),
00301         10 // Endpoint is polled every 10ms
00302     },
00303 \endcode
00304 
00305  \subsubsection data_if_desc Data Class Interface Descriptor
00306 \code
00307     {
00308         sizeof(USBInterfaceDescriptor),
00309         USBGenericDescriptor_INTERFACE,
00310         1, // This is interface #1
00311         0, // This is alternate setting #0 for this interface
00312         2, // This interface uses 2 endpoints
00313         CDCDataInterfaceDescriptor_CLASS,
00314         CDCDataInterfaceDescriptor_SUBCLASS,
00315         CDCDataInterfaceDescriptor_NOPROTOCOL,
00316         0  // No string descriptor for this interface
00317     },
00318 \endcode
00319 
00320  \subsubsection data_ep_desc Data Endpoint Descriptors
00321  The EPs are defined as CDCDSerialDriverDescriptors_DATAOUT &
00322  CDCDSerialDriverDescriptors_DATAIN.
00323 \code
00324     // Bulk-OUT endpoint standard descriptor
00325     {
00326         sizeof(USBEndpointDescriptor), 
00327         USBGenericDescriptor_ENDPOINT,
00328         USBEndpointDescriptor_ADDRESS(USBEndpointDescriptor_OUT,
00329                            CDCDSerialDriverDescriptors_DATAOUT),
00330         USBEndpointDescriptor_BULK,
00331         MIN(BOARD_USB_ENDPOINTS_MAXPACKETSIZE(
00332             CDCDSerialDriverDescriptors_DATAOUT),
00333             USBEndpointDescriptor_MAXBULKSIZE_FS),
00334         0 // Must be 0 for full-speed bulk endpoints
00335     },
00336     // Bulk-IN endpoint descriptor
00337     {
00338         sizeof(USBEndpointDescriptor),
00339         USBGenericDescriptor_ENDPOINT,
00340         USBEndpointDescriptor_ADDRESS(USBEndpointDescriptor_IN,
00341                            CDCDSerialDriverDescriptors_DATAIN),
00342         USBEndpointDescriptor_BULK,
00343         MIN(BOARD_USB_ENDPOINTS_MAXPACKETSIZE(
00344             CDCDSerialDriverDescriptors_DATAIN),
00345             USBEndpointDescriptor_MAXBULKSIZE_FS),
00346         0 // Must be 0 for full-speed bulk endpoints
00347     },
00348 \endcode
00349 
00350  \subsubsection str_desc String Descriptors
00351  Several descriptors (device, configuration, interface, etc.) can specify the
00352  index of a string descriptor to comment their use.
00353 
00354  The actual string code is defined:
00355  stringDescriptors.
00356 
00357  \subsection class_spec_req Class-specific Requests
00358  The CDC specification defines a set of <b>class-specific requests</b> for devices
00359  implementing the ACM. This section details these requests. Please refer to
00360  section 3.6.2.1 of the CDC spec. 1.1 for more information.
00361 
00362  \subsubsection set_get_linecode SetLineCoding, GetLineCoding
00363  These requests are sent by the host to modify or retrieve the configuration of
00364  the serial line, which includes:
00365  - Baudrate
00366  - Number of stop bits
00367  - Parity check
00368  - Number of data bits
00369 
00370  When the terminal application (such as HyperTerminal) on the host (PC) side
00371  changes the setting of the COM port, a SetLineCoding request is sent with the
00372  new parameters. The host may also retrieve the current setting using
00373  GetLineCoding, not modifying them if they are correct.
00374 
00375  When a SET_LINE_CODING request is received, the device should read the new
00376  parameters. Then program the new parameters in the USART. A callback must be
00377  provided to the USBD_Read function.
00378  See CDCDSerialDriver_SetLineCoding.
00379 
00380  The code handling GET_LINE_CODING shall simply invoke the USBD_Write function
00381  to send the current settings of the USART to the host.
00382  See CDCDSerialDriver_GetLineCoding.
00383 
00384  \subsubsection SetControlLineState
00385  This request is sent by the host to notify the device of two state changes.
00386  The first bit (D0) of the wValue field of the request indicates whether or not
00387  a terminal is connected to the virtual COM port. Bit D1 indicates that the
00388  USART should enable/disable its carrier signal to start/stop receiving and
00389  transmitting data.
00390 
00391  In practice, the USB to serial converter should operate only when those two
00392  bits are set. Otherwise, it should not transmit or receive data.
00393 
00394  Since the SET_CONTROL_LINE_STATE request does not have a data payload, the
00395  device only has to acknowledge the request by sending a ZLP (zero-length
00396  packet), using the USBD_Write method.
00397  See CDCDSerialDriver_SetControlLineState.
00398 
00399  Before that, the wValue field should be parsed to retrieve the new control
00400  line state. A single boolean variable can be used to keep track of the
00401  connection state. If both the D0 and D1 bits are set, then the converter
00402  should operate normally, i.e., forward data between the USART and the USB
00403  host. Otherwise, it should stop its activity.
00404 
00405  \subsection Notifications
00406  Notifications are sent by the device when an event, such as a serial line
00407  state change, has occurred. In this example, they are transmitted through a
00408  dedicated Interrupt IN endpoint. A special header must precede the data
00409  payload of each notification. This header has the same format of a SETUP
00410  request, so the USBGenericRequest structure defined in the
00411  \ref usbd_framework "AT91 USB device framework" can be used.
00412 
00413  Note that the device should only send a notification when there is a state
00414  change, and not continuously. This does not really matter in practice, but
00415  only sending notifications sporadically will reduce the stress on the device.
00416 
00417  When the serial state is changed by CDCDSerialDriver_SetSerialState, the
00418  notification is sent to the host.
00419 
00420  \section cdc_serial_drv_api CDC Serial Driver API
00421  - CDCDSerialDriver_Initialize()
00422  - CDCDSerialDriver_RequestHandler()
00423  - CDCDSerialDriver_Read()
00424  - CDCDSerialDriver_Write()
00425  - CDCDSerialDriver_GetSerialState()
00426  - CDCDSerialDriver_SetSerialState()
00427 
00428  \section main_app Main Application
00429  The job of the main application is to bridge the USART and the USB. This means
00430  that data read from one end must be forwarded to the other end. This section
00431  describes several possibilities to do this.
00432 
00433  \section usb_op USB Operation
00434  Reading data coming from the host is done using the CDCDSerialDriver_Read().
00435  Since this is an asynchronous function, it does not block the execution flow.
00436  This means that other actions (like reading data from the USART) can be
00437  performed while the transfer is going on. Whenever some data is sent by the
00438  host, the transfer terminates and the associated callback function is invoked.
00439  This callback (UsbDataReceived()) can be programmed to forward the received data
00440  through the USART.
00441 
00442  Likewise, the CDCDSerialDriver_Write() function can be called as soon as there
00443  is data to transmit, again without block the program flow. However, there
00444  cannot be two write operations at the same time, so the program must check
00445  whether or not the last transfer is complete. This can be done by checking the
00446  result code of the CDCDSerialDriver_Write() method. If \ref USBD_STATUS_LOCKED is
00447  returned, then there is already another operation in progress. The device
00448  will have to buffer the data retrieved from the USART until the endpoint
00449  becomes free again.
00450 
00451  \subsection usart_op USART Operation
00452  The USART peripheral present on AT91 chips can be used in two different ways.
00453  The classic way is to read and write one byte at a time in the correct
00454  registers to send and receive data.
00455 
00456  A more powerful method is available on AT91SAM chips, by using the embedded
00457  Peripheral DMA Controller (PDC). The PDC can take care of transfers between
00458  the processor, memory and peripherals, thus freeing the processor to perform
00459  other tasks. Since the PDC interrupt happens on the buffer full, Some timer
00460  can be used to check if there is any data frags input from the USART.
00461 
00462  \section use_host_drv Using a Generic Host Driver
00463  See \subpage usbd_cdc_host_drv "USB CDC Serial Host Driver".
00464 
00465  \section dual_cdc_drv Add two or more ports in one USB device
00466  See \subpage usbd_dual_cdc "USB Dual Port CDC Serial Device".
00467 
00468 */
00469 
00470 /**
00471  \page usbd_cdc_host_drv USB CDC Serial Host Driver
00472  Both Microsoft Windows and Linux offer a generic driver for using a USB to
00473  serial converter device. This page details the steps required to make use
00474  of them.
00475 
00476  \section Windows
00477  On Microsoft Windows, the standard USB serial driver is named usbser.sys and
00478  is part of the standard set of drivers. It has been available since Windows
00479  98SE. However, conversely to other generic driver such as the one for Mass
00480  Storage Devices (MSD), usbser.sys is not automatically loaded when a CDC
00481  device is plugged in.
00482 
00483  \subsection write_win_inf Writing a Windows Driver File
00484  For Windows to recognize the device correctly, it is necessary to write a
00485  .inf file. The Windows Driver Development Kit (DDK) contains information on
00486  this topic. A basic driver, named 6119.inf in the example software provided,
00487  will now be described. The driver file is made up of several sections.
00488 
00489  The first section of the .inf file must be the <b>[Version]</b> section. It
00490  contains information about the driver version, provider, release data, and so
00491  on.
00492 \code
00493 [Version]
00494 Signature="$Chicago$"
00495 Class=Ports
00496 ClassGuid={4D36E978-E325-11CE-BFC1-08002BE10318}
00497 Provider=%ATMEL%
00498 DriverVer=09/12/2006,1.1.1.1
00499 \endcode
00500 
00501  The Signature attribute is mandatory and can be either "$Windows 95$",
00502  "$Windows NT$" or "$Chicago$", depending on which Windows version(s) the
00503  driver supports. "$Chicago$" is used to notify that every Windows version is
00504  supported. Since in this example, the USB to serial converter is a virtual COM
00505  port, the Class attribute should be equal to "Ports". The value of ClassGuid
00506  depends on which class the device uses. The Provider value indicates that the
00507  string descriptor for the driver provider will be defined further, under the
00508  tag ATMEL. Finally, the last tag show the driver version and release date. For
00509  the version number, each digit is optional (except the first one), but must
00510  not be null if present.
00511 
00512  Next come two sections, <b>[SourceDisksNames]</b> and <b>[SourceDisksFiles]</b>. They
00513  are used to specify the installation disks required and the location of each
00514  needed files on these disks. But they are not implemented because the file
00515  is offered by windows or its install disk automatically.
00516 \code
00517 ;[SourceDisksNames]
00518 ;1="Windows Install CD"
00519 ;[SourceDisksFiles]
00520 ;usbser.sys=1
00521 \endcode
00522 
00523  The driver file must now specify where copied files will be stored, using the
00524  <b>[DestinationDirs]</b> section.
00525 \code
00526 [DestinationDirs]
00527 DefaultDestDir=12
00528 \endcode
00529  The target directory must be identified by its ID, which is system-defined.
00530  The ID for the drivers directory is 12.
00531 
00532  The <b>[Manufacturer]</b> section lists the possible manufacturers for all devices
00533  supported by this driver. In this case, the only supported device is an ATMEL
00534  one, so this will be the only value.
00535 \code
00536 [Manufacturer]
00537 %ATMEL%=AtmelMfg
00538 \endcode
00539 
00540  The attribute must be a string tag; its value must be the name of the Models
00541  section in which all supported devices from this manufacturer will be listed.
00542  In this case, it will be named AtmelMfg, which is the next section.
00543 
00544  Each Models section must list the hardware ID of each supported device. For
00545  USB devices, the hardware ID is made up of the Vendor ID, the Product ID and
00546  (optionally) the Device Release Number. Those values are extracted from the
00547  device descriptor provided during the enumeration phase.
00548 \code
00549 [AtmelMfg]
00550 %USBtoSerialConverter%=USBtoSer.Install,USB\VID_03EB&PID_6119
00551 \endcode
00552 
00553  The attribute name is again a string tag, which will be used to describe the
00554  device. The value is comprised of both the device install section name
00555  (USBtoSer.Install) and the hardware ID. The hardware ID is the same as the one
00556  defined in "CDC Serial Device IDs".
00557 
00558  Now, the .inf file must detail the install section of each device previously
00559  listed. In this example, there is only one install section, named
00560  <b>[USBtoSer.Install]</b>:
00561 \code
00562 [USBtoSer.Install]
00563 CopyFiles=USBtoSer.CopyFiles
00564 AddReg=USBtoSer.AddReg
00565 
00566 [USBtoSer.CopyFiles]
00567 usbser.sys,,,0x00000002
00568 
00569 [USBtoSer.AddReg]
00570 HKR,,DevLoader,,*ntkern
00571 HKR,,NTMPDriver,,usbser.sys
00572 
00573 [USBtoSer.Install.Services]
00574 AddService=usbser,0x00000002,USBtoSer.AddService
00575 
00576 [USBtoSer.AddService]
00577 DisplayName=%USBSer%
00578 ServiceType=1r
00579 StartType=3
00580 ServiceBinary=%12%\usbser.sys
00581 \endcode
00582 
00583  The install section is actually divided in five. In the first section, two
00584  other section names are specified: one for the list of files to copy, and one
00585  for the keys to add to the Windows registry. There is only one file to copy,
00586  usbser.sys; a flag (0x00000002) is used to specify that the user cannot skip
00587  copying it. The registry keys are needed to install the driver on older
00588  versions of Windows (such as Windows 98). For newer versions, the
00589  <b>[USBtoSer.Install.Services]</b> registers the needed kernel services; each
00590  service is actually listed in a section on its own.
00591 
00592  Finally, the last section, [Strings], defines all the string constants used
00593  through this file:
00594 \code
00595 [Strings]
00596 ATMEL="ATMEL Corp."
00597 USBtoSerialConverter="AT91 USB to Serial Converter"
00598 USBSer="USB Serial Driver"
00599 \endcode
00600 
00601  \subsection use_win_ser_drv Using the Driver
00602  When a new device is plugged in for the first time, Windows looks for an
00603  appropriate specific or generic driver to use it. If it does not find one, the
00604  user is asked what to do.
00605 
00606  This is the case with the USB to serial converter, since there is no generic
00607  driver for it. To install the custom driver given in the previous section,
00608  Windows must be told where to look for it. This can be done by selecting the
00609  second option, "Install from a list or specific location", when the driver
00610  installation wizards pops up. It will then ask for the directory where the
00611  driver is located. After that, it should recognize the "AT91 USB to Serial
00612  Converter" driver as an appropriate one and display it in the list.
00613 
00614  During the installation, the wizard asks for the location of the usbser.sys
00615  file. If it is already installed on the system, it can be found in
00616  "C:\Windows\System32\Drivers\". Otherwise, it is present on the Windows
00617  installation CD.
00618 
00619  Once the driver is installed properly, a new COM port is added to the system
00620  and can be used with HyperTerminal, for example.
00621 
00622  \section Linux
00623  Linux has two different generic drivers which are appropriate for a USB to
00624  serial converter. The first one is an Abstract Control Model driver designed
00625  for modem devices, and is simply named <b>acm</b>. The other one is a generic USB
00626  to serial driver named <b>usbserial</b>.
00627 
00628  If the support for the <b>acm</b> driver has been compiled in the kernel, Linux
00629  will automatically load it. A new terminal device will be created under
00630  /dev/ttyACMx.
00631 
00632  The usbserial driver must be loaded manually by using the modprobe command
00633  with the vendor ID and product ID values used by the device:
00634 \code
00635  modprobe usbserial vendor=0x03EB product=0x6119
00636 \endcode
00637 
00638  Once the driver is loaded, a new terminal entry appears and should be named
00639  /dev/ttyUSBx.
00640 */
00641 
00642 /**
00643  \page usbd_dual_cdc USB Device Dual Port CDC Serial Device
00644 
00645 */
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Defines