1 <!-- DOCTYPE reference PUBLIC "-//OASIS//DTD DocBook V3.1//EN" -->
5 <!-- =============================================================== -->
7 <!-- usbs_serial.sgml -->
9 <!-- USB slave-side serial port package. -->
11 <!-- =============================================================== -->
12 <!-- ####COPYRIGHTBEGIN#### -->
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 <!-- =============================================================== -->
25 <!-- ####COPYRIGHTEND#### -->
26 <!-- =============================================================== -->
27 <!-- #####DESCRIPTIONBEGIN#### -->
29 <!-- Author(s): Andrew Lunn, Frank Pagliughi -->
30 <!-- Contact(s): asl -->
31 <!-- Date: 2008/06/18 -->
32 <!-- Version: 0.01 -->
34 <!-- ####DESCRIPTIONEND#### -->
35 <!-- =============================================================== -->
39 <part id="io-usb-slave-serial">
40 <!-- reference id="io-usb-slave-serial" -->
41 <title>eCos Support for USB Serial like Peripherals</title>
45 <refentry id="usbs-serial-intro">
47 <refentrytitle>Introduction</refentrytitle>
50 <refname>Introduction</refname>
52 eCos support for USB Serial like Peripherals
56 <refsect1><title>Introduction</title>
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.
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:
78 <screen width=72 format=linespecific>
79 $ ecosconfig add usbs_serial
82 Typically, this will automatically cause the USB device driver
91 <refentry id="usbs-serial-config">
93 <refentrytitle>Configuration</refentrytitle>
96 <refname>Configuration</refname>
97 <refpurpose>Configuration USB Serial like Peripherals</refpurpose>
100 <refsect1><title>Configuration</title>
102 The package requires a few basic configurations plus
103 optionally some additional configuration options.
106 The driver needs two or three endpoints, depending if ACM
107 communications or a more generic model is used. This is
109 with <literal>CYGDAT_IO_USB_SLAVE_CLASS_TYPE</literal> which
110 can take the value <literal>ACM</literal>
111 or <literal>generic</literal>.
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
119 <literal>CYGDAT_IO_USB_SLAVE_SERIAL_RX_EP</literal> must be
120 configured with the end point used for reception. Associated
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
129 If operation mode ACM is selected a third endpoint is
130 needed. This must operate in interrupt mode and should be
132 in <literal>CYGNUM_IO_USB_SLAVE_SERIAL_INTR_EP</literal>
134 CYGNUM_IO_USB_SLAVE_SERIAL_INTR_EP_NUM</literal>.
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.
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>.
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.
160 <!-- {{{ Host Config -->
162 <refentry id="usbs-serial-host-config">
164 <refentrytitle>Host Configuration</refentrytitle>
167 <refname>Host Configuration</refname>
168 <refpurpose>Host Configuration for USB Serial like Peripherals
173 <title>Host Configuration</title>
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.
179 <refsect2><title>Linux</title>
181 The eCos USB serial like peripheral driver can be used in
182 Linux in one of two ways.
186 Using the generic usbserial kernel module passing the
187 vendor and product ID as module parameters. e.g.
189 <programlisting width=72>
190 modprobe usbserial vendor=0xabcd product=0x1234
193 would load the kernel module so that it would use a
194 USB device abcd:1234 as a serial device.
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:
206 <programlisting width=72>
208 modprobe ecos_usbserial
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
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>.
223 <refsect2><title>Microsoft Windows</title>
225 To install the device in a Microsoft Windows system make use
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.
240 <refentry id="usbs-serial-using">
242 <refentrytitle>API Function</refentrytitle>
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>
258 eCos USB Serial like Peripherals API
265 #include <cyg/io/usb/usbs_serial.h>
269 <function>usbs_serial_start</function>
271 <paramdef>void</paramdef>
275 <function>usbs_serial_init</function>
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>
283 <function>usbs_serial_wait_until_configured</function>
285 <paramdef>void></paramdef>
289 <function>usbs_serial_is_configured</function>
291 <paramdef>void</paramdef>
295 <function>usbs_serial_start_tx</function>
297 <paramdef>usbs_serial * <parameter>ser</parameter></paramdef>
298 <paramdef>const void *<parameter>buf</parameter></paramdef>
299 <paramdef>int * <parameter>n</parameter></paramdef>
303 <function>usbs_serial_wait_for_tx</function>
305 <paramdef>usbs_serial * <parameter>ser</parameter></paramdef>
309 <function>usbs_serial_start_rx</function>
311 <paramdef>usbs_serial * <parameter>ser</parameter></paramdef>
312 <paramdef>const void *<parameter>buf</parameter></paramdef>
313 <paramdef>int * <parameter>n</parameter></paramdef>
317 <function>usbs_serial_wait_for_rx</function>
319 <paramdef>usbs_serial * <parameter>ser</parameter></paramdef>
323 <function>usbs_serial_rx</function>
325 <paramdef>usbs_serial * <parameter>ser</parameter></paramdef>
326 <paramdef>const void *<parameter>buf</parameter></paramdef>
327 <paramdef>int * <parameter>n</parameter></paramdef>
331 <function>usbs_serial_state_change_handler</function>
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>
341 <refsect1 id="usbs-serial-api-description">
342 <title>Description</title>
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>
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.
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.
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.
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
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.