packages/io/usb/serial/slave/v2_0/doc/usbs_serial.sgml

   1 <!-- DOCTYPE reference  PUBLIC "-//OASIS//DTD DocBook V3.1//EN" -->
   2
   3 <!-- {{{ Banner                         -->
   4
   5 <!-- =============================================================== -->
   6 <!--                                                                 -->
   7 <!--     usbs_serial.sgml                                            -->
   8 <!--                                                                 -->
   9 <!--     USB slave-side serial port package.                         -->
  10 <!--                                                                 -->
  11 <!-- =============================================================== -->
  12 <!-- ####COPYRIGHTBEGIN####                                          -->
  13 <!--                                                                 -->
  14 <!-- =============================================================== -->
  15 <!-- Copyright (C) 2008 FSF                                          -->
  16 <!-- This material may be distributed only subject to the terms      -->
  17 <!-- and conditions set forth in the Open Publication License, v1.0  -->
  18 <!-- or later (the latest version is presently available at          -->
  19 <!-- http://www.opencontent.org/openpub/)                            -->
  20 <!-- Distribution of the work or derivative of the work in any       -->
  21 <!-- standard (paper) book form is prohibited unless prior           -->
  22 <!-- permission obtained from the copyright holder                   -->
  23 <!-- =============================================================== -->
  24 <!--                                                                 -->
  25 <!-- ####COPYRIGHTEND####                                            -->
  26 <!-- =============================================================== -->
  27 <!-- #####DESCRIPTIONBEGIN####                                       -->
  28 <!--                                                                 -->
  29 <!-- Author(s):   Andrew Lunn, Frank Pagliughi                       -->
  30 <!-- Contact(s):  asl                                                -->
  31 <!-- Date:        2008/06/18                                         -->
  32 <!-- Version:     0.01                                               -->
  33 <!--                                                                 -->
  34 <!-- ####DESCRIPTIONEND####                                          -->
  35 <!-- =============================================================== -->
  36
  37 <!-- }}} -->
  38
  39 <part id="io-usb-slave-serial">
  40   <!-- reference id="io-usb-slave-serial" -->
  41   <title>eCos Support for USB Serial like Peripherals</title>
  42
  43   <!-- {{{ Intro                          -->
  44
  45   <refentry id="usbs-serial-intro">
  46     <refmeta>
  47       <refentrytitle>Introduction</refentrytitle>
  48     </refmeta>
  49     <refnamediv>
  50       <refname>Introduction</refname>
  51       <refpurpose>
  52         eCos support for USB Serial like Peripherals
  53       </refpurpose>
  54     </refnamediv>
  55
  56     <refsect1><title>Introduction</title>
  57       <para>
  58         The eCos USB-Serial package provides additional support for
  59         USB peripherals that look like a serial port to the
  60         host. These can follow the ACM communication device
  61         specification or simpler devices which just have two bulk
  62         endpoints. Microsoft Windows requires ACM mode. Linux should
  63         operate with both modes, however ACM may cause problems since
  64         the eCos driver does not implement all the class descriptors,
  65         so generic mode is recommended.
  66       </para>
  67       <para>
  68         The USB-Serial package is not tied to any specific
  69         hardware. It requires the presence of USB hardware on the
  70         target and a suitable device driver to make endpoints
  71         available for this code to use.  The configuration system
  72         cannot load the eCos package automatically for specific
  73         targets, in the way that a USB device driver or an ethernet
  74         driver can be loaded automatically. Instead, the package has
  75         to be added explicitly. When using the command line tools this
  76         will involve an operation like the following:
  77       </para>
  78       <screen width=72 format=linespecific>
  79         $ ecosconfig add usbs_serial
  80       </screen>
  81       <para>
  82         Typically, this will automatically cause the USB device driver
  83         to become active.
  84       </para>
  85     </refsect1>
  86   </refentry>
  87
  88   <!-- }}} -->
  89   <!-- {{{ Config                          -->
  90
  91   <refentry id="usbs-serial-config">
  92     <refmeta>
  93       <refentrytitle>Configuration</refentrytitle>
  94     </refmeta>
  95     <refnamediv>
  96       <refname>Configuration</refname>
  97       <refpurpose>Configuration USB Serial like Peripherals</refpurpose>
  98     </refnamediv>
  99
 100     <refsect1><title>Configuration</title>
 101       <para>
 102         The package requires a few basic configurations plus
 103         optionally some additional configuration options.
 104       </para>
 105       <para>
 106         The driver needs two or three endpoints, depending if ACM
 107         communications or a more generic model is used. This is
 108         configured
 109         with <literal>CYGDAT_IO_USB_SLAVE_CLASS_TYPE</literal> which
 110         can take the value <literal>ACM</literal>
 111         or <literal>generic</literal>.
 112       </para>
 113       <para>
 114         The <literal>CYGDAT_IO_USB_SLAVE_SERIAL_EP0</literal> must be
 115         configured with the control end point of the USB
 116         device. <literal>CYGDAT_IO_USB_SLAVE_SERIAL_TX_EP</literal>
 117         must be configured with the endpoint to be used for
 118         transmission and
 119         <literal>CYGDAT_IO_USB_SLAVE_SERIAL_RX_EP</literal> must be
 120         configured with the end point used for reception. Associated
 121         with these
 122         are <literal>CYGNUM_IO_USB_SLAVE_SERIAL_RX_EP_NUM</literal>
 123         and <literal>CYGNUM_IO_USB_SLAVE_SERIAL_TX_EP_NUM</literal>
 124         which are the endpoint numbers and are used during enumeration
 125         of the device. The TX and RX endpoints must operate in BULK
 126         mode.
 127       </para>
 128       <para>
 129         If operation mode ACM is selected a third endpoint is
 130         needed. This must operate in interrupt mode and should be
 131         configured
 132         in <literal>CYGNUM_IO_USB_SLAVE_SERIAL_INTR_EP</literal>
 133         and <literal>
 134         CYGNUM_IO_USB_SLAVE_SERIAL_INTR_EP_NUM</literal>.
 135       </para>
 136       <para>
 137         The USB serial device will make its vendor:product ID known to
 138         the host. This should be configured
 139         with <literal>CYGNUM_IO_USB_SLAVE_SERIAL_VENDOR_ID</literal>
 140         and <literal>CYGNUM_IO_USB_SLAVE_SERIAL_PRODUCT_ID</literal>. NOTE:
 141         The default configurations are not valid for products, but
 142         should work for testing.
 143       </para>
 144       <para>
 145         The USB enumeration also contains text strings to describe the
 146         device. This text string can be set
 147         with <literal>CYGDAT_IO_USB_SLAVE_SERIAL_PRODUCT_STR</literal>.
 148       </para>
 149       <para>
 150         The last configuration option of interest
 151         is <literal>CYGPKG_IO_USB_SLAVE_SERIAL_EXAMPLES</literal>. When
 152         true example programs will be built when the eCos tests are
 153         built. These are not pass/fail test like other eCos tests, but
 154         examples of how the eCos USB serial class can be used.
 155       </para>
 156     </refsect1>
 157   </refentry>
 158
 159   <!-- }}} -->
 160   <!-- {{{ Host Config                          -->
 161
 162   <refentry id="usbs-serial-host-config">
 163     <refmeta>
 164       <refentrytitle>Host Configuration</refentrytitle>
 165     </refmeta>
 166     <refnamediv>
 167       <refname>Host Configuration</refname>
 168       <refpurpose>Host Configuration for USB Serial like Peripherals
 169       </refpurpose>
 170     </refnamediv>
 171
 172     <refsect1>
 173       <title>Host Configuration</title>
 174       <para>
 175         Configuration for two hosts are listed here, Microsoft Windows
 176         and Linux. It should also be possible to use the eCos USB
 177         serial like peripheral driver with other hosts.
 178       </para>
 179       <refsect2><title>Linux</title>
 180         <para>
 181           The eCos USB serial like peripheral driver can be used in
 182           Linux in one of two ways.
 183           <itemizedlist>
 184             <listitem>
 185               <para>
 186                 Using the generic usbserial kernel module passing the
 187                 vendor and product ID as module parameters. e.g.
 188               </para>
 189               <programlisting width=72>
 190                 modprobe usbserial vendor=0xabcd product=0x1234
 191               </programlisting>
 192               <para>
 193                 would load the kernel module so that it would use a
 194                 USB device abcd:1234 as a serial device.
 195               </para>
 196             </listitem>
 197             <listitem>
 198               <para>
 199                 Using the mini driver provided with eCos in the
 200                 <filename class=directory>host/linux</filename>
 201                 directory. This driver must be edited and the correct
 202                 vendor and product ID set to match the vendor and
 203                 product ID used by the device. Once compiled this
 204                 driver can be loaded with:
 205               </para>
 206               <programlisting width=72>
 207                 modprobe usbserial
 208                 modprobe ecos_usbserial
 209               </programlisting>
 210               <para>
 211                 This driver is known to compile with kernel versions
 212                 2.6.18 and probably works fine with other
 213                 kernels. However it fails to compile with kernels
 214                 after 2.6.25.
 215               </para>
 216             </listitem>
 217           </itemizedlist>
 218           Both of these methods will result in the Linux Kernel making
 219           a new serial device available. This is typically
 220           named <filename>/dev/ttyUSB0</filename>.
 221         </para>
 222       </refsect2>
 223       <refsect2><title>Microsoft Windows</title>
 224         <para>
 225           To install the device in a Microsoft Windows system make use
 226           of the INF file
 227           in <filename>host/windows/eCosUsbSerial.inf</filename>. Copy
 228           this INF file and <filename>usbser.sys</filename> from your
 229           version of Windows into an empty directory. Then plug in the
 230           USB device. When prompted to load a driver navigate to the
 231           INF file and select it.
 232         </para>
 233       </refsect2>
 234     </refsect1>
 235
 236   </refentry>
 237
 238   <!-- }}} -->
 239   <!-- {{{ Using                         -->
 240   <refentry id="usbs-serial-using">
 241     <refmeta>
 242       <refentrytitle>API Function</refentrytitle>
 243     </refmeta>
 244     <refnamediv>
 245       <refname>usbs_serial_start</refname>
 246       <refname>usbs_serial_init</refname>
 247       <refname>usbs_serial_start</refname>
 248       <refname>usbs_serial_wait_until_configured</refname>
 249       <refname>usbs_serial_is_configured</refname>
 250       <refname>usbs_serial_start_tx</refname>
 251       <refname>usbs_serial_wait_for_tx</refname>
 252       <refname>usbs_serial_tx</refname>
 253       <refname>usbs_serial_start_rx</refname>
 254       <refname>usbs_serial_wait_for_rx</refname>
 255       <refname>usbs_serial_rx</refname>
 256       <refname>usbs_serial_state_change_handler</refname>
 257       <refpurpose>
 258         eCos USB Serial like Peripherals API
 259       </refpurpose>
 260     </refnamediv>
 261
 262     <refsynopsisdiv>
 263       <funcsynopsis>
 264         <funcsynopsisinfo>
 265 #include &lt;cyg/io/usb/usbs_serial.h&gt;
 266         </funcsynopsisinfo>
 267         <funcprototype>
 268           <funcdef>void
 269             <function>usbs_serial_start</function>
 270           </funcdef>
 271           <paramdef>void</paramdef>
 272         </funcprototype>
 273         <funcprototype>
 274           <funcdef>void
 275             <function>usbs_serial_init</function>
 276           </funcdef>
 277           <paramdef>usbs_serial * <parameter>ser</parameter></paramdef>
 278           <paramdef>usbs_tx_endpoint * <parameter>tx_ep</parameter></paramdef>
 279           <paramdef>usbs_rx_endpoint * <parameter>rx_ep</parameter></paramdef>
 280         </funcprototype>
 281         <funcprototype>
 282           <funcdef>void
 283             <function>usbs_serial_wait_until_configured</function>
 284           </funcdef>
 285           <paramdef>void></paramdef>
 286         </funcprototype>
 287         <funcprototype>
 288           <funcdef>cyg_bool
 289             <function>usbs_serial_is_configured</function>
 290           </funcdef>
 291           <paramdef>void</paramdef>
 292         </funcprototype>
 293         <funcprototype>
 294           <funcdef>void
 295             <function>usbs_serial_start_tx</function>
 296           </funcdef>
 297           <paramdef>usbs_serial * <parameter>ser</parameter></paramdef>
 298           <paramdef>const void *<parameter>buf</parameter></paramdef>
 299           <paramdef>int * <parameter>n</parameter></paramdef>
 300         </funcprototype>
 301         <funcprototype>
 302           <funcdef>int
 303             <function>usbs_serial_wait_for_tx</function>
 304           </funcdef>
 305           <paramdef>usbs_serial * <parameter>ser</parameter></paramdef>
 306         </funcprototype>
 307         <funcprototype>
 308           <funcdef>void
 309             <function>usbs_serial_start_rx</function>
 310           </funcdef>
 311           <paramdef>usbs_serial * <parameter>ser</parameter></paramdef>
 312           <paramdef>const void *<parameter>buf</parameter></paramdef>
 313           <paramdef>int * <parameter>n</parameter></paramdef>
 314         </funcprototype>
 315         <funcprototype>
 316           <funcdef>int
 317             <function>usbs_serial_wait_for_rx</function>
 318           </funcdef>
 319           <paramdef>usbs_serial * <parameter>ser</parameter></paramdef>
 320         </funcprototype>
 321         <funcprototype>
 322           <funcdef>int
 323             <function>usbs_serial_rx</function>
 324           </funcdef>
 325           <paramdef>usbs_serial * <parameter>ser</parameter></paramdef>
 326           <paramdef>const void *<parameter>buf</parameter></paramdef>
 327           <paramdef>int * <parameter>n</parameter></paramdef>
 328         </funcprototype>
 329         <funcprototype>
 330           <funcdef>void
 331             <function>usbs_serial_state_change_handler</function>
 332           </funcdef>
 333           <paramdef>usbs_control_endpoint * <parameter>ep</parameter></paramdef>
 334           <paramdef>void * <parameter>data</parameter></paramdef>
 335           <paramdef>usbs_state_change <parameter>change</parameter></paramdef>
 336           <paramdef>int <parameter>prev_state</parameter></paramdef>
 337         </funcprototype>
 338       </funcsynopsis>
 339     </refsynopsisdiv>
 340
 341     <refsect1 id="usbs-serial-api-description">
 342       <title>Description</title>
 343       <para>
 344         For examples of how to use this API see the
 345         files <filename>.../tests/usbserial_echo.c</filename>
 346         and <filename>.../tests/usb2serial.c</filename>
 347       </para>
 348
 349       <para>
 350         The first function that needs calling
 351         is <function>usbs_serial_start()</function>. This will initialise
 352         the eCos USB slave layer, creating all the enumeration data and
 353         then let the host know that the device exists.
 354       </para>
 355       <para>
 356         Once the USB subsystem has been started it is necessary to wait
 357         for the host to configure the device using the
 358         function <function>usbs_serial_wait_until_configured()</function>. The
 359         host will assign the device an ID and then load the appropriate
 360         device driver in the host in order to make use the device.
 361       </para>
 362       <para>
 363         Once the device is configured it is then possible to make use of
 364         it, i.e. send and receive data. This transfer of data can be
 365         accomplished either asynchronously or synchronously. It is also
 366         possible to mix asynchronously and synchronously between
 367         receiving and sending data.
 368       </para>
 369       <para>
 370         To perform asynchronous operations the
 371         functions <function>usbs_serial_start_rx()</function>
 372         and <function>usbs_serial_start_tx()</function> is used to
 373         start the operation. These functions start the necessary
 374         actions and then return immediately. At a later time the
 375         functions <function>usbs_serial_wait_for_tx()</function>
 376         or <function>usbs_serial_wait_for_rx()</function> should be
 377         called. These will, if necessary, block and then return the
 378         status and any data for the previously started asynchronous
 379         call.
 380       </para>
 381       <para>
 382         To perform synchronous operations the
 383         functions <function>usbs_serial_rx()</function>
 384         and <function>usbs_serial_tx()</function> are used. These
 385         functions will block until the requested action is complete.
 386       </para>
 387     </refsect1>
 388   </refentry>
 389   <!-- }}} -->
 390 </part>
 391 <!-- /reference -->