Mercurial > ecos

annotate packages/io/usb/slave/current/doc/usbs.sgml @ 208:e0c0827131d1 ecos

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Merge from eCos master repository on 2002-05-20-20:11:54-BST
author jlarmour
date Mon, 20 May 2002 22:19:26 +0000
parents 022f1e506033
children d2c90368aeef
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
151
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1 <!DOCTYPE reference PUBLIC "-//OASIS//DTD DocBook V3.1//EN">
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
3 <!-- {{{ Banner -->
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
4
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
5 <!-- =============================================================== -->
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
6 <!-- -->
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
7 <!-- usbs.sgml -->
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
8 <!-- -->
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
9 <!-- Generic USB-slave documentation. -->
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
10 <!-- -->
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
11 <!-- =============================================================== -->
208
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
12 ####ECOSGPLCOPYRIGHTBEGIN####
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
13 -------------------------------------------
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
14 This file is part of eCos, the Embedded Configurable Operating System.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
15 Copyright (C) 1998, 1999, 2000, 2001, 2002 Red Hat, Inc.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
16
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
17 eCos is free software; you can redistribute it and/or modify it under
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
18 the terms of the GNU General Public License as published by the Free
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
19 Software Foundation; either version 2 or (at your option) any later version.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
20
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
21 eCos is distributed in the hope that it will be useful, but WITHOUT ANY
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
22 WARRANTY; without even the implied warranty of MERCHANTABILITY or
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
23 FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
24 for more details.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
25
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
26 You should have received a copy of the GNU General Public License along
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
27 with eCos; if not, write to the Free Software Foundation, Inc.,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
28 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
29
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
30 As a special exception, if other files instantiate templates or use macros
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
31 or inline functions from this file, or you compile this file and link it
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
32 with other works to produce a work based on this file, this file does not
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
33 by itself cause the resulting work to be covered by the GNU General Public
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
34 License. However the source code for this file must still be made available
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
35 in accordance with section (3) of the GNU General Public License.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
36
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
37 This exception does not invalidate any other reasons why a work based on
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
38 this file might be covered by the GNU General Public License.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
39
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
40 Alternative licenses for eCos may be arranged by contacting Red Hat, Inc.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
41 at http://sources.redhat.com/ecos/ecos-license
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
42 -------------------------------------------
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
43 ####ECOSGPLCOPYRIGHTEND####
151
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
44 <!-- =============================================================== -->
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
45 <!-- #####DESCRIPTIONBEGIN#### -->
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
46 <!-- -->
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
47 <!-- Author(s): bartv -->
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
48 <!-- Contact(s): bartv -->
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
49 <!-- Date: 2001/01/03 -->
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
50 <!-- Version: 0.01 -->
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
51 <!-- -->
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
52 <!-- ####DESCRIPTIONEND#### -->
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
53 <!-- =============================================================== -->
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
54
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
55 <!-- }}} -->
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
56
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
57 <reference id="io-usb-slave">
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
58 <title>eCos USB Slave Support</title>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
59
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
60 <!-- {{{ Intro -->
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
61
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
62 <refentry id="usbs-intro">
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
63 <refmeta>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
64 <refentrytitle>Introduction</refentrytitle>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
65 </refmeta>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
66 <refnamediv>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
67 <refname>Introduction</refname>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
68 <refpurpose>eCos support for USB slave devices</refpurpose>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
69 </refnamediv>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
70
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
71 <refsect1><title>Introduction</title>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
72 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
73 The eCos USB slave support allows developers to produce USB
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
74 peripherals. It consists of a number of different eCos packages:
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
75 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
76 <orderedlist>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
77
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
78 <listitem>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
79 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
80 Device drivers for specific implementations of USB slave hardware, for
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
81 example the on-chip USB Device Controller provided by the Intel SA1110
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
82 processor. A typical USB peripheral will only provide one USB slave
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
83 port and therefore only one such device driver package will be needed.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
84 Usually the device driver package will be loaded automatically when
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
85 you create an eCos configuration for target hardware that has a USB
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
86 slave device. If you select a target which does have a USB slave
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
87 device but no USB device driver is loaded, this implies that no such
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
88 device driver is currently available.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
89 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
90 </listitem>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
91
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
92 <listitem>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
93 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
94 The common USB slave package. This serves two purposes. It defines the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
95 API that specific device drivers should implement. It also provides
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
96 various utilities that will be needed by most USB device drivers and
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
97 applications, such as handlers for standard control messages.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
98 Usually this package will be loaded automatically at the same time as
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
99 the USB device driver.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
100 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
101 </listitem>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
102
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
103 <listitem>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
104 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
105 The common USB package. This merely provides some information common
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
106 to both the host and slave sides of USB, such as details of the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
107 control protocol. It is also used to place the other USB-related
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
108 packages appropriately in the overall configuration hierarchy. Usually
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
109 this package will be loaded at the same time as the USB device driver.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
110 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
111 </listitem>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
112
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
113 <listitem>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
114 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
115 Class-specific USB support packages. These make it easier to develop
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
116 specific classes of USB peripheral, such as a USB-ethernet device. If
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
117 no suitable package is available for a given class of peripheral then
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
118 the USB device driver can instead be accessed directly from
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
119 application code. Such packages will never be loaded automatically
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
120 since the configuration system has no way of knowing what class of USB
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
121 peripheral is being developed. Instead developers have to add the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
122 appropriate package or packages explicitly.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
123 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
124 </listitem>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
125
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
126 </orderedlist>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
127
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
128 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
129 These packages only provide support for developing USB peripherals,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
130 not USB hosts.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
131 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
132 </refsect1>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
133
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
134 <refsect1><title>USB Concepts</title>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
135 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
136 Information about USB can be obtained from a number of sources
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
137 including the <ulink url="http://www.usb.org/">USB Implementers Forum
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
138 web site</ulink>. Only a brief summary is provided here.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
139 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
140 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
141 A USB network is asymmetrical: it consists of a single host, one or
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
142 more slave devices, and possibly some number of intermediate hubs. The
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
143 host side is significantly more complicated than the slave side.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
144 Essentially, all operations are initiated by the host. For example, if
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
145 the host needs to receive some data from a particular USB peripheral
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
146 then it will send an IN token to that peripheral; the latter should
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
147 respond with either a NAK or with appropriate data. Similarly, when
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
148 the host wants to transmit data to a peripheral it will send an OUT
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
149 token followed by the data; the peripheral will return a NAK if it is
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
150 currently unable to receive more data or if there was corruption,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
151 otherwise it will return an ACK. All transfers are check-summed and
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
152 there is a clearly-defined error recovery process. USB peripherals can
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
153 only interact with the host, not with each other.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
154 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
155 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
156 USB supports four different types of communication: control messages,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
157 interrupt transfers, isochronous transfers, and bulk transfers.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
158 Control messages are further subdivided into four categories:
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
159 standard, class, vendor and a reserved category. All USB peripherals
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
160 must respond to certain standard control messages, and usually this
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
161 will be handled by the common USB slave package (for complicated
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
162 peripherals, application support will be needed). Class and vendor
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
163 control messages may be handled by an class-specific USB support
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
164 package, for example the USB-ethernet package will handle control
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
165 messages such as getting the MAC address or enabling/disabling
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
166 promiscuous mode. Alternatively, some or all of these messages will
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
167 have to be handled by application code.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
168 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
169 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
170 Interrupt transfers are used for devices which need to be polled
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
171 regularly. For example, a USB keyboard might be polled once every
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
172 millisecond. The host will not poll the device more frequently than
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
173 this, so interrupt transfers are best suited to peripherals that
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
174 involve a relatively small amount of data. Isochronous transfers are
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
175 intended for multimedia-related peripherals where typically a large
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
176 amount of video or audio data needs to be exchanged continuously.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
177 Given appropriate host support a USB peripheral can reserve some of
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
178 the available bandwidth. Isochronous transfers are not reliable; if a
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
179 particular packet is corrupted then it will just be discarded and
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
180 software is expected to recover from this. Bulk transfers are used for
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
181 everything else: after taking care of any pending control, isochronous
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
182 and interrupt transfers the host will use whatever bandwidth remains
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
183 for bulk transfers. Bulk transfers are reliable.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
184 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
185 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
186 Transfers are organized into USB packets, with the details depending
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
187 on the transfer type. Control messages always involve an initial
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
188 8-byte packet from host to peripheral, optionally followed by some
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
189 additional packets; in theory these additional packets can be up to 64
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
190 bytes, but hardware may limit it to 8 bytes. Interrupt transfers
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
191 involve a single packet of up to 64 bytes. Isochronous transfers
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
192 involve a single packet of up to 1024 bytes. Bulk transfers involve
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
193 multiple packets. There will be some number, possibly zero, of 64-byte
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
194 packets. The transfer is terminated by a single packet of less than 64
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
195 bytes. If the transfer involves an exact multiple of 64 bytes than the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
196 final packet will be 0 bytes, consisting of just a header and checksum
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
197 which typically will be generated by the hardware. There is no
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
198 pre-defined limit on the size of a bulk transfer. Instead higher-level
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
199 protocols are expected to handle this, so for a USB-ethernet
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
200 peripheral the protocol could impose a limit of 1514 bytes of data
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
201 plus maybe some additional protocol overhead.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
202 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
203 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
204 Transfers from the host to a peripheral are addressed not just to that
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
205 peripheral but to a specific endpoint within that peripheral.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
206 Similarly, the host requests incoming data from a specific endpoint
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
207 rather than from the peripheral as a whole. For example, a combined
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
208 keyboard/touchpad device could provide the keyboard events on endpoint
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
209 1 and the mouse events on endpoint 2. A given USB peripheral can have
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
210 up to 16 endpoints for incoming data and another 16 for outgoing data.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
211 However, given the comparatively high speed of USB I/O this endpoint
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
212 addressing is typically implemented in hardware rather than software,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
213 and the hardware will only implement a small number of endpoints.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
214 Endpoint 0 is generally used only for control messages.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
215 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
216 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
217 In practice, many of these details are irrelevant to application code
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
218 or to class packages. Instead, such higher-level code usually just
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
219 performs blocking <function>read</function> and
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
220 <function>write</function>, or non-blocking USB-specific calls, to
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
221 transfer data between host and target via a specific endpoint. Control
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
222 messages are more complicated but are usually handled by existing
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
223 code.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
224 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
225 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
226 When a USB peripheral is plugged into the host there is an initial
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
227 enumeration and configuration process. The peripheral provides
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
228 information such as its class of device (audio, video, etc.), a
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
229 vendor id, which endpoints should be used for what kind of data, and
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
230 so on. The host OS uses this information to identify a suitable host
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
231 device driver. This could be a generic driver for a class of
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
232 peripherals, or it could be a vendor-specific driver. Assuming a
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
233 suitable driver is installed the host will then activate the USB
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
234 peripheral and perform additional application-specific initialisation.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
235 For example for a USB-ethernet device this would involve obtaining an
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
236 ethernet MAC address. Most USB peripherals will be fairly simple, but
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
237 it is possible to build multifunction peripherals with multiple
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
238 configurations, interfaces, and alternate interface settings.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
239 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
240 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
241 It is not possible for any of the eCos packages to generate all the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
242 enumeration data automatically. Some of the required information such
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
243 as the vendor id cannot be supplied by generic packages; only by the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
244 application developer. Class support code such as the USB-ethernet
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
245 package could in theory supply some of the information automatically,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
246 but there are also hardware dependencies such as which endpoints get
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
247 used for incoming and outgoing ethernet frames. Instead it is the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
248 responsibility of the application developer to provide all the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
249 enumeration data and perform some additional initialisation. In
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
250 addition, the common USB slave package can handle all the standard
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
251 control messages for a simple USB peripheral, but for something like a
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
252 multifunction peripheral additional application support is needed.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
253 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
254
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
255 <note><para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
256 The initial implementation of the eCos USB slave packages involved
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
257 hardware that only supported control and bulk transfers, not
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
258 isochronous or interrupt. There may be future changes to the USB
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
259 code and API to allow for isochronous and interrupt transfers,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
260 especially the former. Other changes may be required to support
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
261 different USB devices. At present there is no support for USB remote
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
262 wakeups, since again it is not supported by the hardware.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
263 </para></note>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
264
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
265 </refsect1>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
266
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
267 <refsect1><title>eCos USB I/O Facilities</title>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
268 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
269 For protocols other than control messages, eCos provides two ways of
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
270 performing USB I/O. The first involves device table or devtab entries such
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
271 as <link linkend="usbs-devtab"><literal>/dev/usb1r</literal></link>,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
272 with one entry per endpoint per USB device. It is possible to
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
273 <function>open</function> these devices and use conventional blocking
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
274 I/O functions such as <function>read</function> and
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
275 <function>write</function> to exchange data between host and
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
276 peripheral.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
277 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
278 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
279 There is also a lower-level USB-specific API, consisting of functions
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
280 such as <link
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
281 linkend="usbs-start-rx"><function>usbs_start_rx_buffer</function></link>.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
282 A USB device driver will supply a data structure for each endpoint,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
283 for example a <link
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
284 linkend="usbs-data"><structname>usbs_rx_endpoint</structname></link>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
285 structure for every receive endpoint. The first argument to
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
286 <function>usbs_start_rx_buffer</function> should be a pointer to such
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
287 a data structure. The USB-specific API is non-blocking: the initial
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
288 call merely starts the transfer; some time later, once the transfer
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
289 has completed or has been aborted, the device driver will invoke a
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
290 completion function.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
291 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
292 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
293 Control messages are different. With four different categories of
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
294 control messages including application and vendor specific ones, the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
295 conventional
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
296 <function>open</function>/<function>read</function>/<function>write</function>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
297 model of I/O cannot easily be applied. Instead, a USB device driver
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
298 will supply a <link
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
299 linkend="usbs-control"><structname>usbs_control_endpoint</structname></link>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
300 data structure which can be manipulated appropriately. In practice the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
301 standard control messages will usually be handled by the common USB
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
302 slave package, and other control messages will be handled by
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
303 class-specific code such as the USB-ethernet package. Typically,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
304 application code remains responsible for supplying the <link
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
305 linkend="usbs-enum">enumeration data</link> and for actually <link
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
306 linkend="usbs-start">starting</link> up the USB device.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
307 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
308 </refsect1>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
309
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
310 <refsect1><title>Enabling the USB code</title>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
311 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
312 If the target hardware contains a USB slave device then the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
313 appropriate USB device driver and the common packages will typically
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
314 be loaded into the configuration automatically when that target is
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
315 selected (assuming a suitable device driver exists). However, the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
316 driver will not necessarily be active. For example a processor might
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
317 have an on-chip USB device, but not all applications using that
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
318 processor will want to use USB functionality. Hence by default the USB
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
319 device is disabled, ensuring that applications do not suffer any
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
320 memory or other penalties for functionality that is not required.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
321 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
322 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
323 If the application developer explicitly adds a class support package
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
324 such as the USB-ethernet one then this implies that the USB device is
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
325 actually needed, and the device will be enabled automatically.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
326 However, if no suitable class package is available and the USB device
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
327 will instead be accessed by application code, it is necessary to
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
328 enable the USB device manually. Usually the easiest way to do this is
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
329 to enable the configuration option
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
330 <literal>CYGGLO_IO_USB_SLAVE_APPLICATION</literal>, and the USB device
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
331 driver and related packages will adjust accordingly. Alternatively,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
332 the device driver may provide some configuration options to provide
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
333 more fine-grained control.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
334 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
335 </refsect1>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
336
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
337 </refentry>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
338
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
339 <!-- }}} -->
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
340 <!-- {{{ Enumeration Data -->
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
341
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
342 <refentry id="usbs-enum">
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
343 <refmeta>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
344 <refentrytitle>USB Enumeration Data</refentrytitle>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
345 </refmeta>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
346 <refnamediv>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
347 <refname>Enumeration Data</refname>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
348 <refpurpose>The USB enumeration data structures</refpurpose>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
349 </refnamediv>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
350
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
351 <refsynopsisdiv>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
352 <synopsis>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
353 #include &lt;cyg/io/usb/usb.h&gt;
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
354 #include &lt;cyg/io/usb/usbs.h&gt;
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
355
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
356 typedef struct usb_device_descriptor {
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
357 &hellip;
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
358 } usb_device_descriptor __attribute__((packed));
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
359
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
360 typedef struct usb_configuration_descriptor {
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
361 &hellip;
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
362 } usb_configuration_descriptor __attribute__((packed));
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
363
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
364 typedef struct usb_interface_descriptor {
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
365 &hellip;
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
366 } usb_interface_descriptor __attribute__((packed));
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
367
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
368 typedef struct usb_endpoint_descriptor {
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
369 &hellip;
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
370 } usb_endpoint_descriptor;
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
371
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
372 typedef struct usbs_enumeration_data {
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
373 usb_device_descriptor device;
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
374 int total_number_interfaces;
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
375 int total_number_endpoints;
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
376 int total_number_strings;
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
377 const usb_configuration_descriptor* configurations;
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
378 const usb_interface_descriptor* interfaces;
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
379 const usb_endpoint_descriptor* endpoints;
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
380 const unsigned char** strings;
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
381 } usbs_enumeration_data;
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
382 </synopsis>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
383 </refsynopsisdiv>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
384
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
385 <refsect1><title>USB Enumeration Data</title>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
386 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
387 When a USB host detects that a peripheral has been plugged in or
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
388 powered up, one of the first steps is to ask the peripheral to
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
389 describe itself by supplying enumeration data. Some of this data
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
390 depends on the class of peripheral. Other fields are vendor-specific.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
391 There is also a dependency on the hardware, specifically which
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
392 endpoints are available should be used. In general it is not possible
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
393 for generic code to provide this information, so it is the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
394 responsibility of application code to provide a suitable
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
395 <structname>usbs_enumeration_data</structname> data structure and
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
396 install it in the endpoint 0 data structure during initialization.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
397 This must happen before the USB device is enabled by a call to
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
398 <function>usbs_start</function>, for example:
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
399 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
400 <programlisting width=72>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
401 const usbs_enumeration_data usb_enum_data = {
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
402 &hellip;
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
403 };
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
404
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
405 int
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
406 main(int argc, char** argv)
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
407 {
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
408 usbs_sa11x0_ep0.enumeration_data = &amp;usb_enum_data;
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
409 &hellip;
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
410 usbs_start(&amp;usbs_sa11x0_ep0);
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
411 &hellip;
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
412 }
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
413 </programlisting>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
414 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
415 For most applications the enumeration data will be static, although
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
416 the <structname>usbs_enumeration_data</structname> structure can be
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
417 filled in at run-time if necessary. Full details of the enumeration
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
418 data can be found in the Universal Serial Bus specification obtainable
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
419 from the <ulink url="http://www.usb.org/">USB Implementers Forum web
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
420 site</ulink>, although the meaning of most fields is fairly obvious.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
421 The various data structures and utility macros are defined in the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
422 header files <filename class="headerfile">cyg/io/usb/usb.h</filename>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
423 and <filename class="headerfile">cyg/io/usb/usbs.h</filename>. Note
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
424 that the example code below makes use of the gcc labelled element
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
425 extension.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
426 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
427
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
428 <refsect2><title><structname>usb_device_descriptor</structname></title>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
429 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
430 The main information about a USB peripheral comes from a single
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
431 <structname>usb_device_descriptor</structname> structure, which is
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
432 embedded in the <structname>usbs_enumeration_data</structname>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
433 structure. A typical example might look like this:
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
434 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
435 <programlisting width=72>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
436 const usbs_enumeration_data usb_enum_data = {
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
437 {
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
438 length: USB_DEVICE_DESCRIPTOR_LENGTH,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
439 type: USB_DEVICE_DESCRIPTOR_TYPE,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
440 usb_spec_lo: USB_DEVICE_DESCRIPTOR_USB11_LO,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
441 usb_spec_hi: USB_DEVICE_DESCRIPTOR_USB11_HI,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
442 device_class: USB_DEVICE_DESCRIPTOR_CLASS_VENDOR,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
443 device_subclass: USB_DEVICE_DESCRIPTOR_SUBCLASS_VENDOR,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
444 device_protocol: USB_DEVICE_DESCRIPTOR_PROTOCOL_VENDOR,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
445 max_packet_size: 8,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
446 vendor_lo: 0x42,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
447 vendor_hi: 0x42,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
448 product_lo: 0x42,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
449 product_hi: 0x42,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
450 device_lo: 0x00,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
451 device_hi: 0x01,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
452 manufacturer_str: 1,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
453 product_str: 2,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
454 serial_number_str: 0,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
455 number_configurations: 1
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
456 },
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
457 &hellip;
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
458 };
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
459 </programlisting>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
460 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
461 The length and type fields are specified by the USB standard. The
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
462 <structfield>usb_spec_lo</structfield> and
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
463 <structfield>usb_spec_hi</structfield> fields identify the particular
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
464 revision of the standard that the peripheral implements, for example
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
465 revision 1.1.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
466 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
467 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
468 The device class, subclass, and protocol fields are used by generic
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
469 host-side USB software to determine which host-side device driver
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
470 should be loaded to interact with the peripheral. A number of standard
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
471 classes are defined, for example mass-storage devices and
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
472 human-interface devices. If a peripheral implements one of the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
473 standard classes then a standard existing host-side device driver may
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
474 exist, eliminating the need to write a custom driver. The value
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
475 <literal>0xFF</literal> (<literal>VENDOR</literal>) is reserved for
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
476 peripherals that implement a vendor-specific protocol rather than a
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
477 standard one. Such peripherals will require a custom host-side device
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
478 driver. The value <literal>0x00</literal>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
479 (<literal>INTERFACE</literal>) is reserved and indicates that the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
480 protocol used by the peripheral is defined at the interface level
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
481 rather than for the peripheral as a whole.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
482 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
483 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
484 The <structfield>max_package_size</structfield> field specifies the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
485 maximum length of a control message. There is a lower bound of eight
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
486 bytes, and typical hardware will not support anything larger because
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
487 control messages are usually small and not performance-critical.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
488 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
489 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
490 The <structfield>vendor_lo</structfield> and
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
491 <structfield>vendor_hi</structfield> fields specify a vendor id, which
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
492 must be obtained from the USB Implementor's Forum. The numbers used in
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
493 the code fragment above are examples only and must not be used in real
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
494 USB peripherals. The product identifier is determined by the vendor,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
495 and different USB peripherals should use different identifiers. The
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
496 device identifier field should indicate a release number in
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
497 binary-coded decimal.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
498 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
499 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
500 The above fields are all numerical in nature. A USB peripheral can
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
501 also provide a number of strings as described <link
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
502 linkend="usbs-enum-strings">below</link>, for example the name of the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
503 vendor can be provided. The various <structfield>_str</structfield>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
504 fields act as indices into an array of strings, with index 0
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
505 indicating that no string is available.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
506 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
507 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
508 A typical USB peripheral involves just a single configuration. However
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
509 more complicated peripherals can support multiple configurations. Only
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
510 one configuration will be active at any one time, and the host will
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
511 switch between them as appropriate. If a peripheral does involve
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
512 multiple configurations then typically it will be the responsibility
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
513 of application code to <link
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
514 linkend="usbs-control-standard">handle</link> the standard
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
515 set-configuration control message.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
516 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
517 </refsect2>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
518
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
519 <refsect2><title><structname>usb_configuration_descriptor</structname></title>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
520 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
521 A USB peripheral involves at least one and possible several different
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
522 configurations. The <structname>usbs_enumeration_data</structname>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
523 structure requires a pointer to an array, possibly of length 1, of
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
524 <structname>usb_configuration_descriptor</structname> structures.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
525 Usually a single structure suffices:
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
526 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
527 <programlisting width=72>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
528 const usb_configuration_descriptor usb_configuration = {
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
529 length: USB_CONFIGURATION_DESCRIPTOR_LENGTH,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
530 type: USB_CONFIGURATION_DESCRIPTOR_TYPE,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
531 total_length_lo: USB_CONFIGURATION_DESCRIPTOR_TOTAL_LENGTH_LO(1, 2),
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
532 total_length_hi: USB_CONFIGURATION_DESCRIPTOR_TOTAL_LENGTH_HI(1, 2),
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
533 number_interfaces: 1,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
534 configuration_id: 1,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
535 configuration_str: 0,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
536 attributes: USB_CONFIGURATION_DESCRIPTOR_ATTR_REQUIRED |
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
537 USB_CONFIGURATION_DESCRIPTOR_ATTR_SELF_POWERED,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
538 max_power: 50
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
539 };
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
540
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
541 const usbs_enumeration_data usb_enum_data = {
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
542 &hellip;
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
543 configurations: &amp;usb_configuration,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
544 &hellip;
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
545 };
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
546 </programlisting>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
547 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
548 The values for the <structfield>length</structfield> and
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
549 <structfield>type</structfield> fields are determined by the standard.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
550 The <structfield>total_length</structfield> field depends on the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
551 number of interfaces and endpoints used by this configuration, and
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
552 convenience macros are provided to calculate this: the first argument
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
553 to the macros specify the number of interfaces, the second the number
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
554 of endpoints. The <structfield>number_interfaces</structfield> field
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
555 is self-explanatory. If the peripheral involves multiple
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
556 configurations then each one must have a unique id, and this will be
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
557 used in the set-configuration control message. The id
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
558 <literal>0</literal> is reserved, and a set-configuration control
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
559 message that uses this id indicates that the peripheral should be
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
560 inactive. Configurations can have a string description if required.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
561 The <structfield>attributes</structfield> field must have the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
562 <literal>REQUIRED</literal> bit set; the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
563 <literal>SELF_POWERED</literal> bit informs the host that the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
564 peripheral has its own power supply and will not draw any power over
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
565 the bus, leaving more bus power available to other peripherals; the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
566 <literal>REMOTE_WAKEUP</literal> bit is used if the peripheral can
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
567 interrupt the host when the latter is in power-saving mode. For
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
568 peripherals that are not self-powered, the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
569 <structfield>max_power</structfield> field specifies the power
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
570 requirements in units of 2mA.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
571 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
572 </refsect2>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
573
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
574 <refsect2><title><structname>usb_interface_descriptor</structname></title>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
575 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
576 A USB configuration involves one or more interfaces, typically
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
577 corresponding to different streams of data. For example, one interface
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
578 might involve video data while another interface is for audio.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
579 Multiple interfaces in a single configuration will be active at the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
580 same time.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
581 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
582 <programlisting width=72>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
583 const usb_interface_descriptor usb_interface = {
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
584 length: USB_INTERFACE_DESCRIPTOR_LENGTH,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
585 type: USB_INTERFACE_DESCRIPTOR_TYPE,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
586 interface_id: 0,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
587 alternate_setting: 0,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
588 number_endpoints: 2,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
589 interface_class: USB_INTERFACE_DESCRIPTOR_CLASS_VENDOR,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
590 interface_subclass: USB_INTERFACE_DESCRIPTOR_SUBCLASS_VENDOR,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
591 interface_protocol: USB_INTERFACE_DESCRIPTOR_PROTOCOL_VENDOR,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
592 interface_str: 0
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
593 };
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
594
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
595 const usbs_enumeration_data usb_enum_data = {
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
596 &hellip;
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
597 total_number_interfaces: 1,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
598 interfaces: &amp;usb_interface,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
599 &hellip;
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
600 };
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
601 </programlisting>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
602 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
603 Again, the <structfield>length</structfield> and
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
604 <structfield>type</structfield> fields are specified by the standard.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
605 Each interface within a configuration requires its own id. However, a
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
606 given interface may have several alternate settings, in other words
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
607 entries in the interfaces array with the same id but different
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
608 <structfield>alternate_setting</structfield> fields. For example,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
609 there might be one setting which requires a bandwidth of 100K/s and
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
610 another setting that only needs 50K/s. The host can use the standard
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
611 set-interface control message to choose the most appropriate setting.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
612 The handling of this request is the responsibility of higher-level
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
613 code, so the application may have to <link
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
614 linkend="usbs-control-standard">install</link> its own handler.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
615 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
616 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
617 The number of endpoints used by an interface is specified in the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
618 <structfield>number_endpoints</structfield> field. Exact details of
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
619 which endpoints are used is held in a separate array of endpoint
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
620 descriptors. The class, subclass and protocol fields are used by
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
621 host-side code to determine which host-side device driver should
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
622 handle this specific interface. Usually this is determined on a
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
623 per-peripheral basis in the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
624 <structname>usb_device_descriptor</structname> structure, but that can
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
625 defer the details to individual interfaces. A per-interface string
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
626 is allowed as well.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
627 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
628 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
629 For USB peripherals involving multiple configurations, the array of
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
630 <structname>usb_interface_descriptor</structname> structures should
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
631 first contain all the interfaces for the first configuration, then all
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
632 the interfaces for the second configuration, and so on.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
633 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
634 </refsect2>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
635
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
636 <refsect2><title id="usbs-enum-endpoint"><structname>usb_endpoint_descriptor</structname></title>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
637 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
638 The host also needs information about which endpoint should be used
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
639 for what. This involves an array of endpoint descriptors:
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
640 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
641 <programlisting width=72>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
642 const usb_endpoint_descriptor usb_endpoints[] = {
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
643 {
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
644 length: USB_ENDPOINT_DESCRIPTOR_LENGTH,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
645 type: USB_ENDPOINT_DESCRIPTOR_TYPE,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
646 endpoint: USB_ENDPOINT_DESCRIPTOR_ENDPOINT_OUT | 1,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
647 attributes: USB_ENDPOINT_DESCRIPTOR_ATTR_BULK,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
648 max_packet_lo: 64,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
649 max_packet_hi: 0,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
650 interval: 0
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
651 },
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
652 {
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
653 length: USB_ENDPOINT_DESCRIPTOR_LENGTH,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
654 type: USB_ENDPOINT_DESCRIPTOR_TYPE,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
655 endpoint: USB_ENDPOINT_DESCRIPTOR_ENDPOINT_IN | 2,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
656 attributes: USB_ENDPOINT_DESCRIPTOR_ATTR_BULK,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
657 max_packet_lo: 64,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
658 max_packet_hi: 0,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
659 interval: 0
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
660 }
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
661 };
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
662
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
663 const usbs_enumeration_data usb_enum_data = {
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
664 &hellip;
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
665 total_number_endpoints: 2,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
666 endpoints: usb_endpoints,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
667 &hellip;
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
668 };
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
669 </programlisting>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
670 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
671 As usual the values for the <structfield>length</structfield> and
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
672 <structfield>type</structfield> fields are specified by the standard.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
673 The <structfield>endpoint</structfield> field gives both the endpoint
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
674 number and the direction, so in the above example endpoint 1 is used
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
675 for OUT (host to peripheral) transfers and endpoint 2 is used for IN
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
676 (peripheral to host) transfers. The
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
677 <structfield>attributes</structfield> field indicates the USB protocol
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
678 that should be used on this endpoint: <literal>CONTROL</literal>,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
679 <literal>ISOCHRONOUS</literal>, <literal>BULK</literal> or
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
680 <literal>INTERRUPT</literal>. The
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
681 <structfield>max_packet</structfield> field specifies the maximum size
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
682 of a single USB packet. For bulk transfers this will typically be 64
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
683 bytes. For isochronous transfers this can be up to 1023 bytes. For
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
684 interrupt transfers it can be up to 64 bytes, although usually a
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
685 smaller value will be used. The <structfield>interval</structfield>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
686 field is ignored for control and bulk transfers. For isochronous
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
687 transfers it should be set to 1. For interrupt transfers it can be a
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
688 value between 1 and 255, and indicates the number of milliseconds
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
689 between successive polling operations.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
690 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
691 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
692 For USB peripherals involving multiple configurations or interfaces
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
693 the array of endpoint descriptors should be organized sequentially:
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
694 first the endpoints corresponding to the first interface of the first
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
695 configuration, then the second interface in that configuration, and so
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
696 on; then all the endpoints for all the interfaces in the second
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
697 configuration; etc.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
698 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
699 </refsect2>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
700
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
701 <refsect2><title id="usbs-enum-strings">Strings</title>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
702 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
703 The enumeration data can contain a number of strings with additional
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
704 information. Unicode encoding is used for the strings, and it is
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
705 possible for a peripheral to supply a given string in multiple
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
706 languages using the appropriate characters. The first two bytes of
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
707 each string give a length and type field. The first string is special;
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
708 after the two bytes header it consists of an array of 2-byte language
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
709 id codes, indicating the supported languages. The language code
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
710 0x0409 corresponds to English (United States).
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
711 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
712 <programlisting width=72>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
713 const unsigned char* usb_strings[] = {
184
022f1e506033 Merge from eCos master repository on 2001-10-02-17:59:22-BST
jlarmour
parents: 151
diff changeset
714 "\004\003\011\004",
022f1e506033 Merge from eCos master repository on 2001-10-02-17:59:22-BST
jlarmour
parents: 151
diff changeset
715 "\020\003R\000e\000d\000 \000H\000a\000t\000"
151
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
716 };
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
717
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
718 const usbs_enumeration_data usb_enum_data = {
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
719 &hellip;
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
720 total_number_strings: 2,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
721 strings: usb_strings,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
722 &hellip;
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
723 };
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
724 </programlisting>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
725 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
726 The default handler for standard control messages assumes that the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
727 peripheral only uses a single language. If this is not the case then
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
728 higher-level code will have to handle the standard get-descriptor
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
729 control messages when a string descriptor is requested.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
730 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
731 </refsect2>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
732
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
733 <refsect2><title><structname>usbs_enumeration_data</structname></title>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
734 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
735 The <structname>usbs_enumeration_data</structname> data structure
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
736 collects together all the various descriptors that make up the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
737 enumeration data. It is the responsibility of application code to
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
738 supply a suitable data structure and install it in the control
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
739 endpoints's <structfield>enumeration_data</structfield> field before
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
740 the USB device is started.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
741 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
742 </refsect2>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
743
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
744 </refsect1>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
745 </refentry>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
746
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
747 <!-- }}} -->
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
748 <!-- {{{ usbs_start() -->
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
749
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
750 <refentry id="usbs-start">
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
751 <refmeta>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
752 <refentrytitle>Starting up a USB Device</refentrytitle>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
753 </refmeta>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
754 <refnamediv>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
755 <refname><function>usbs_start</function></refname>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
756 <refpurpose>Starting up a USB Device</refpurpose>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
757 </refnamediv>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
758
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
759 <refsynopsisdiv>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
760 <funcsynopsis>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
761 <funcsynopsisinfo>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
762 #include &lt;cyg/io/usb/usbs.h&gt;
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
763 </funcsynopsisinfo>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
764 <funcprototype>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
765 <funcdef>void <function>usbs_start</function></funcdef>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
766 <paramdef>usbs_control_endpoint* <parameter>ep0</parameter></paramdef>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
767 </funcprototype>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
768 </funcsynopsis>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
769 </refsynopsisdiv>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
770
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
771 <refsect1><title>Description</title>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
772 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
773 Initializing a USB device requires some support from higher-level
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
774 code, typically the application, in the form of enumeration data.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
775 Hence it is not possible for the low-level USB driver to activate a
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
776 USB device itself. Instead the higher-level code has to take care of
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
777 this by invoking <function>usbs_start</function>. This function takes
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
778 a pointer to a USB control endpoint data structure. USB device drivers
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
779 should provide exactly one such data structure for every USB device,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
780 so the pointer uniquely identifies the device.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
781 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
782 <programlisting width=72>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
783 const usbs_enumeration_data usb_enum_data = {
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
784 &hellip;
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
785 };
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
786
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
787 int
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
788 main(int argc, char** argv)
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
789 {
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
790 usbs_sa11x0_ep0.enumeration_data = &amp;usb_enum_data;
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
791 &hellip;
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
792 usbs_start(&amp;usbs_sa11x0_ep0);
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
793 &hellip;
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
794 }
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
795 </programlisting>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
796 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
797 The exact behaviour of <function>usbs_start</function> depends on the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
798 USB hardware and the device driver. A typical implementation would
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
799 change the USB data pins from tristated to active. If the peripheral
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
800 is already plugged into a host then the latter should detect this
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
801 change and start interacting with the peripheral, including requesting
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
802 the enumeration data. Some of this may happen before
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
803 <function>usbs_start</function> returns, but given that multiple
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
804 interactions between USB host and peripheral are required it is likely
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
805 that the function will return before the peripheral is fully
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
806 configured. Control endpoints provide a <link
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
807 linkend="usbs-control-state">mechanism</link> for informing
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
808 higher-level code of USB state changes.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
809 <function>usbs_start</function> will return even if the peripheral is
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
810 not currently connected to a host: it will not block until the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
811 connection is established.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
812 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
813 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
814 <function>usbs_start</function> should only be called once for a given
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
815 USB device. There are no defined error conditions. Note that the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
816 function affects the entire USB device and not just the control
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
817 endpoint: there is no need to start any data endpoints as well.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
818 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
819 </refsect1>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
820 </refentry>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
821
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
822 <!-- }}} -->
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
823 <!-- {{{ Devtab Entries -->
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
824
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
825 <refentry id="usbs-devtab">
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
826 <refmeta>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
827 <refentrytitle>Devtab Entries</refentrytitle>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
828 </refmeta>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
829 <refnamediv>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
830 <refname>Devtab Entries</refname>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
831 <refpurpose>Data endpoint data structure</refpurpose>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
832 </refnamediv>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
833
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
834 <refsynopsisdiv>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
835 <synopsis>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
836 /dev/usb0c
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
837 /dev/usb1r
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
838 /dev/usb2w
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
839 </synopsis>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
840 </refsynopsisdiv>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
841
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
842 <refsect1><title>Devtab Entries</title>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
843 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
844 USB device drivers provide two ways of transferring data between host
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
845 and peripheral. The first involves USB-specific functionality such as
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
846 <link
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
847 linkend="usbs-start-rx"><function>usbs_start_rx_buffer</function></link>.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
848 This provides non-blocking I/O: a transfer is started, and some time
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
849 later the device driver will call a supplied completion function. The
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
850 second uses the conventional I/O model: there are entries in the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
851 device table corresponding to the various endpoints. Standard calls
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
852 such as <function>open</function> can then be used to get a suitable
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
853 handle. Actual I/O happens via blocking <function>read</function> and
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
854 <function>write</function> calls. In practice the blocking operations
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
855 are simply implemented using the underlying non-blocking
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
856 functionality.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
857 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
858 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
859 Each endpoint will have its own devtab entry. The exact names are
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
860 controlled by the device driver package, but typically the root will
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
861 be <literal>/dev/usb</literal>. This is followed by one or more
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
862 decimal digits giving the endpoint number, followed by
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
863 <literal>c</literal> for a control endpoint, <literal>r</literal> for
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
864 a receive endpoint (host to peripheral), and <literal>w</literal> for
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
865 a transmit endpoint (peripheral to host). If the target hardware
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
866 involves more than one USB device then different roots should be used,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
867 for example <literal>/dev/usb0c</literal> and
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
868 <literal>/dev/usb1_0c</literal>. This may require explicit
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
869 manipulation of device driver configuration options by the application
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
870 developer.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
871 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
872 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
873 At present the devtab entry for a control endpoint does not support
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
874 any I/O operations.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
875 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
876
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
877 <refsect2><title><function>write</function> operations</title>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
878 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
879 <function>cyg_io_write</function> and similar functions in
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
880 higher-level packages can be used to perform a transfer from
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
881 peripheral to host. Successive write operations will not be coalesced.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
882 For example, when doing a 1000 byte write to an endpoint that uses the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
883 bulk transfer protocol this will involve 15 full-size 64-byte packets
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
884 and a terminating 40-byte packet. USB device drivers are not expected
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
885 to do any locking, and if higher-level code performs multiple
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
886 concurrent write operations on a single endpoint then the resulting
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
887 behaviour is undefined.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
888 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
889 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
890 A USB <function>write</function> operation will never transfer less
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
891 data than specified. It is the responsibility of higher-level code to
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
892 ensure that the amount of data being transferred is acceptable to the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
893 host-side code. Usually this will be defined by a higher-level
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
894 protocol. If an attempt is made to transfer more data than the host
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
895 expects then the resulting behaviour is undefined.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
896 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
897 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
898 There are two likely error conditions. <literal>EPIPE</literal>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
899 indicates that the connection between host and target has been broken.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
900 <literal>EAGAIN</literal> indicates that the endpoint has been
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
901 stalled, either at the request of the host or by other activity
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
902 inside the peripheral.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
903 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
904 </refsect2>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
905
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
906 <refsect2><title><function>read</function> operations</title>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
907 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
908 <function>cyg_io_read</function> and similar functions in higher-level
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
909 packages can be used to perform a transfer from host to peripheral.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
910 This should be a complete transfer: higher-level protocols should
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
911 define an upper bound on the amount of data being transferred, and the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
912 <function>read</function> operation should involve at least this
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
913 amount of data. The return value will indicate the actual transfer
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
914 size, which may be less than requested.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
915 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
916 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
917 Some device drivers may support partial reads, but USB device drivers
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
918 are not expected to perform any buffering because that involves both
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
919 memory and code overheads. One technique that may work for bulk
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
920 transfers is to exploit the fact that such transfers happen in 64-byte
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
921 packets. It is possible to <function>read</function> an initial 64
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
922 bytes, corresponding to the first packet in the transfer. These 64
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
923 bytes can then be examined to determine the total transfer size, and
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
924 the remaining data can be transferred in another
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
925 <function>read</function> operation. This technique is not guaranteed
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
926 to work with all USB hardware. Also, if the delay between accepting
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
927 the first packet and the remainder of the transfer is excessive then
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
928 this could cause timeout problems for the host-side software. For
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
929 these reasons the use of partial reads should be avoided.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
930 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
931 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
932 There are two likely error conditions. <literal>EPIPE</literal>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
933 indicates that the connection between host and target has been broken.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
934 <literal>EAGAIN</literal> indicates that the endpoint has been
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
935 stalled, either at the request of the host or by other activity
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
936 inside the peripheral.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
937 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
938 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
939 USB device drivers are not expected to do any locking. If higher-level
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
940 code performs multiple concurrent read operations on a single endpoint
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
941 then the resulting behaviour is undefined.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
942 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
943 </refsect2>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
944
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
945 <refsect2><title><function>select</function> operations</title>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
946 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
947 Typical USB device drivers will not provide any support for
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
948 <function>select</function>. Consider bulk transfers from the host to
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
949 the peripheral. At the USB device driver level there is no way of
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
950 knowing in advance how large a transfer will be, so it is not feasible
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
951 for the device driver to buffer the entire transfer. It may be
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
952 possible to buffer part of the transfer, for example the first 64-byte
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
953 packet, and copy this into application space at the start of a
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
954 <function>read</function>, but this adds code and memory overheads.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
955 Worse, it means that there is an unknown but potentially long delay
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
956 between a peripheral accepting the first packet of a transfer and the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
957 remaining packets, which could confuse or upset the host-side
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
958 software.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
959 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
960 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
961 With some USB hardware it may be possible for the device driver to
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
962 detect OUT tokens from the host without actually accepting the data,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
963 and this would indicate that a <function>read</function> is likely to
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
964 succeed. However, it would not be reliable since the host-side I/O
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
965 operation could time out. A similar mechanism could be used to
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
966 implement <function>select</function> for outgoing data, but again
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
967 this would not be reliable.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
968 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
969 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
970 Some device drivers may provide partial support for
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
971 <function>select</function> anyway, possibly under the control of a
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
972 configuration option. The device driver's documentation should be
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
973 consulted for further information. It is also worth noting that the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
974 USB-specific non-blocking API can often be used as an alternative to
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
975 <function>select</function>.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
976 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
977 </refsect2>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
978
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
979 <refsect2><title><function>get_config</function> and
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
980 <function>set_config</function> operations</title>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
981 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
982 There are no <function>set_config</function> or
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
983 <function>get_config</function> (also known as
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
984 <function>ioctl</function>) operations defined for USB devices.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
985 Some device drivers may provide hardware-specific facilities this way.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
986 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
987 <note>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
988 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
989 Currently the USB-specific functions related to <link
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
990 linkend="usbs-halt">halted endpoints</link> cannot be accessed readily
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
991 via devtab entries. This functionality should probably be made
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
992 available via <function>set_config</function> and
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
993 <function>get_config</function>. It may also prove useful to provide
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
994 a <function>get_config</function> operation that maps from the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
995 devtab entries to the underlying endpoint data structures.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
996 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
997 </note>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
998 </refsect2>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
999
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1000 <refsect2><title>Presence</title>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1001 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1002 The devtab entries are optional. If the USB device is accessed
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1003 primarily by class-specific code such as the USB-ethernet package and
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1004 that package uses the USB-specific API directly, the devtab entries
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1005 are redundant. Even if application code does need to access the USB
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1006 device, the non-blocking API may be more convenient than the blocking
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1007 I/O provided via the devtab entries. In these cases the devtab entries
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1008 serve no useful purpose, but they still impose a memory overhead. It
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1009 is possible to suppress the presence of these entries by disabling the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1010 configuration option
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1011 <literal>CYGGLO_IO_USB_SLAVE_PROVIDE_DEVTAB_ENTRIES</literal>.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1012 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1013 </refsect2>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1014 </refsect1>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1015 </refentry>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1016
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1017 <!-- }}} -->
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1018 <!-- {{{ usbs_start_rx_buffer() -->
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1019
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1020 <refentry id="usbs-start-rx">
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1021 <refmeta>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1022 <refentrytitle>Receiving Data from the Host</refentrytitle>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1023 </refmeta>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1024 <refnamediv>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1025 <refname><function>usbs_start_rx_buffer</function></refname>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1026 <refpurpose>Receiving Data from the Host</refpurpose>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1027 </refnamediv>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1028
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1029 <refsynopsisdiv>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1030 <funcsynopsis>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1031 <funcsynopsisinfo>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1032 #include &lt;cyg/io/usb/usbs.h&gt;
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1033 </funcsynopsisinfo>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1034 <funcprototype>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1035 <funcdef>void <function>usbs_start_rx_buffer</function></funcdef>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1036 <paramdef>usbs_rx_endpoint* <parameter>ep</parameter></paramdef>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1037 <paramdef>unsigned char* <parameter>buffer</parameter></paramdef>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1038 <paramdef>int <parameter>length</parameter></paramdef>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1039 <paramdef>void (*)(void*,int) <parameter>complete_fn</parameter></paramdef>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1040 <paramdef>void * <parameter>complete_data</parameter></paramdef>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1041 </funcprototype>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1042
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1043 <funcprototype>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1044 <funcdef>void <function>usbs_start_rx</function></funcdef>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1045 <paramdef>usbs_rx_endpoint* <parameter>ep</parameter></paramdef>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1046 </funcprototype>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1047
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1048 </funcsynopsis>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1049 </refsynopsisdiv>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1050
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1051 <refsect1><title><function>Description</function></title>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1052 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1053 <function>usbs_start_rx_buffer</function> is a USB-specific function
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1054 to accept a transfer from host to peripheral. It can be used for bulk,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1055 interrupt or isochronous transfers, but not for control messages.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1056 Instead those involve manipulating the <link
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1057 linkend="usbs-control"><structname>usbs_control_endpoint</structname></link>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1058 data structure directly. The function takes five arguments:
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1059 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1060 <orderedlist>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1061 <listitem>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1062 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1063 The first argument identifies the specific endpoint that should be
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1064 used. Different USB devices will support different sets of endpoints
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1065 and the device driver will provide appropriate data structures. The
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1066 device driver's documentation should be consulted for details of which
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1067 endpoints are available.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1068 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1069 </listitem>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1070 <listitem>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1071 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1072 The <parameter>buffer</parameter> and <parameter>length</parameter>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1073 arguments control the actual transfer. USB device drivers are not
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1074 expected to perform any buffering or to support partial transfers, so
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1075 the length specified should correspond to the maximum transfer that is
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1076 currently possible and the buffer should be at least this large. For
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1077 isochronous transfers the USB specification imposes an upper bound of
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1078 1023 bytes, and a smaller limit may be set in the <link
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1079 linkend="usbs-enum-endpoint">enumeration data</link>. Interrupt
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1080 transfers are similarly straightforward with an upper bound of 64
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1081 bytes, or less as per the enumeration data. Bulk transfers are more
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1082 complicated because they can involve multiple 64-byte packets plus a
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1083 terminating packet of less than 64 bytes, so there is no predefined
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1084 limit on the transfer size. Instead it is left to higher-level
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1085 protocols to specify an appropriate upper bound.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1086 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1087 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1088 One technique that may work for bulk transfers is to exploit the fact
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1089 that such transfers happen in 64-byte packets: it may be possible to
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1090 receive an initial 64 bytes, corresponding to the first packet in the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1091 transfer; these 64 bytes can then be examined to determine the total
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1092 transfer size, and the remaining data can be transferred in another
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1093 receive operation. This technique is not guaranteed to work with all
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1094 USB hardware. Also, if the delay between accepting the first packet and
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1095 the remainder of the transfer is excessive then this could cause
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1096 timeout problems for the host-side software. For these reasons this
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1097 technique should be avoided.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1098 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1099 </listitem>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1100 <listitem>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1101 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1102 <function>usbs_start_rx_buffer</function> is non-blocking. It merely
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1103 starts the receive operation, and does not wait for completion. At
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1104 some later point the USB device driver will invoke the completion
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1105 function parameter with two arguments: the completion data defined by
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1106 the last parameter and a result field. A result &gt;=
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1107 <literal>0</literal> indicates a successful transfer of that many
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1108 bytes, which may be less than the upper bound imposed by the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1109 <parameter>length</parameter> argument. A result &lt;
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1110 <literal>0</literal> indicates an error. The most likely errors are
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1111 <literal>-EPIPE</literal> to indicate that the connection between the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1112 host and the target has been broken, and <literal>-EAGAIN</literal>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1113 for when the endpoint has been <link
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1114 linkend="usbs-halt">halted</link>. Specific USB device drivers may
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1115 specify additional error conditions.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1116 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1117 </listitem>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1118 </orderedlist>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1119 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1120 The normal sequence of events is that the USB device driver will
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1121 update the appropriate hardware registers. At some point after that
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1122 the host will attempt to send data by transmitting an OUT token
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1123 followed by a data packet, and since a receive operation is now in
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1124 progress the data will be accepted and ACK'd. If there were no receive
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1125 operation then the peripheral would instead generate a NAK. The USB
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1126 hardware will generate an interrupt once the whole packet has been
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1127 received, and the USB device driver will service this interrupt and
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1128 arrange for a DSR to be called. Isochronous and interrupt transfers
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1129 involve just a single packet. However, bulk transfers may involve
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1130 multiple packets so the device driver has to check whether the packet
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1131 was a full 64 bytes or whether it was a terminating packet of less
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1132 than this. When the device driver DSR detects a complete transfer it
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1133 will inform higher-level code by invoking the supplied completion
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1134 function.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1135 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1136 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1137 This means that the completion function will normally be invoked by a
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1138 DSR and not in thread context - although some USB device drivers may
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1139 have a different implementation. Therefore the completion function is
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1140 restricted in what it can do. In particular it must not make any
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1141 calls that will or may block such as locking a mutex or allocating
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1142 memory. The kernel documentation should be consulted for more details
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1143 of DSR's and interrupt handling generally.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1144 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1145 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1146 It is possible that the completion function will be invoked before
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1147 <function>usbs_start_rx_buffer</function> returns. Such an event would
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1148 be unusual because the transfer cannot happen until the next time the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1149 host tries to send data to this peripheral, but it may happen if for
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1150 example another interrupt happens and a higher priority thread is
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1151 scheduled to run. Also, if the endpoint is currently halted then the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1152 completion function will be invoked immediately with
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1153 <literal>-EAGAIN</literal>: typically this will happen in the current
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1154 thread rather than in a separate DSR. The completion function is
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1155 allowed to start another transfer immediately by calling
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1156 <function>usbs_start_rx_buffer</function> again.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1157 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1158 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1159 USB device drivers are not expected to perform any locking. It is the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1160 responsibility of higher-level code to ensure that there is only one
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1161 receive operation for a given endpoint in progress at any one time. If
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1162 there are concurrent calls to
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1163 <function>usbs_start_rx_buffer</function> then the resulting behaviour
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1164 is undefined. For typical USB applications this does not present any
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1165 problems, because only one piece of code will access a given endpoint
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1166 at any particular time.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1167 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1168 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1169 The following code fragment illustrates a very simple use of
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1170 <function>usbs_start_rx_buffer</function> to implement a blocking
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1171 receive, using a semaphore to synchronise between the foreground
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1172 thread and the DSR. For a simple example like this no completion data
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1173 is needed.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1174 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1175 <programlisting width=72>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1176 static int error_code = 0;
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1177 static cyg_sem_t completion_wait;
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1178
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1179 static void
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1180 completion_fn(void* data, int result)
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1181 {
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1182 error_code = result;
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1183 cyg_semaphore_post(&amp;completion_wait);
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1184 }
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1185
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1186 int
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1187 blocking_receive(usbs_rx_endpoint* ep, unsigned char* buf, int len)
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1188 {
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1189 error_code = 0;
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1190 usbs_start_rx_buffer(ep, buf, len, &amp;completion_fn, NULL);
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1191 cyg_semaphore_wait(&amp;completion_wait);
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1192 return error_code;
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1193 }
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1194 </programlisting>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1195 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1196 There is also a utility function <function>usbs_start_rx</function>. This
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1197 can be used by code that wants to manipulate <link
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1198 linkend="usbs-data">data endpoints</link> directly, specifically the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1199 <structfield>complete_fn</structfield>,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1200 <structfield>complete_data</structfield>,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1201 <structfield>buffer</structfield> and
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1202 <structfield>buffer_size</structfield> fields.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1203 <function>usbs_start_tx</function> just invokes a function
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1204 supplied by the device driver.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1205 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1206 </refsect1>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1207 </refentry>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1208
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1209 <!-- }}} -->
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1210 <!-- {{{ usbs_start_tx_buffer() -->
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1211
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1212 <refentry id="usbs-start-tx">
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1213 <refmeta>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1214 <refentrytitle>Sending Data to the Host</refentrytitle>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1215 </refmeta>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1216 <refnamediv>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1217 <refname><function>usbs_start_tx_buffer</function></refname>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1218 <refpurpose>Sending Data to the Host</refpurpose>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1219 </refnamediv>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1220
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1221 <refsynopsisdiv>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1222 <funcsynopsis>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1223 <funcsynopsisinfo>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1224 #include &lt;cyg/io/usb/usbs.h&gt;
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1225 </funcsynopsisinfo>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1226 <funcprototype>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1227 <funcdef>void <function>usbs_start_tx_buffer</function></funcdef>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1228 <paramdef>usbs_tx_endpoint* <parameter>ep</parameter></paramdef>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1229 <paramdef>const unsigned char* <parameter>buffer</parameter></paramdef>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1230 <paramdef>int <parameter>length</parameter></paramdef>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1231 <paramdef>void (*)(void*,int) <parameter>complete_fn</parameter></paramdef>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1232 <paramdef>void * <parameter>complete_data</parameter></paramdef>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1233 </funcprototype>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1234
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1235 <funcprototype>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1236 <funcdef>void <function>usbs_start_tx</function></funcdef>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1237 <paramdef>usbs_tx_endpoint* <parameter>ep</parameter></paramdef>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1238 </funcprototype>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1239
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1240 </funcsynopsis>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1241 </refsynopsisdiv>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1242
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1243 <refsect1><title><function>Description</function></title>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1244 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1245 <function>usbs_start_tx_buffer</function> is a USB-specific function
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1246 to transfer data from peripheral to host. It can be used for bulk,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1247 interrupt or isochronous transfers, but not for control messages;
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1248 instead those involve manipulating the <link
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1249 linkend="usbs-control"><structname>usbs_control_endpoint</structname></link>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1250 data structure directly. The function takes five arguments:
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1251 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1252 <orderedlist>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1253 <listitem>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1254 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1255 The first argument identifies the specific endpoint that should be
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1256 used. Different USB devices will support different sets of endpoints
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1257 and the device driver will provide appropriate data structures. The
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1258 device driver's documentation should be consulted for details of which
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1259 endpoints are available.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1260 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1261 </listitem>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1262 <listitem>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1263 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1264 The <parameter>buffer</parameter> and <parameter>length</parameter>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1265 arguments control the actual transfer. USB device drivers are not
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1266 allowed to modify the buffer during the transfer, so the data can
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1267 reside in read-only memory. The transfer will be for all the data
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1268 specified, and it is the responsibility of higher-level code to make
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1269 sure that the host is expecting this amount of data. For isochronous
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1270 transfers the USB specification imposes an upper bound of 1023 bytes,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1271 but a smaller limit may be set in the <link
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1272 linkend="usbs-enum-endpoint">enumeration data</link>. Interrupt
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1273 transfers have an upper bound of 64 bytes or less, as per the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1274 enumeration data. Bulk transfers are more complicated because they can
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1275 involve multiple 64-byte packets plus a terminating packet of less
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1276 than 64 bytes, so the basic USB specification does not impose an upper
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1277 limit on the total transfer size. Instead it is left to higher-level
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1278 protocols to specify an appropriate upper bound. If the peripheral
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1279 attempts to send more data than the host is willing to accept then the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1280 resulting behaviour is undefined and may well depend on the specific
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1281 host operating system being used.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1282 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1283 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1284 For bulk transfers, the USB device driver or the underlying hardware
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1285 will automatically split the transfer up into the appropriate number
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1286 of full-size 64-byte packets plus a single terminating packet, which
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1287 may be 0 bytes.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1288 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1289 </listitem>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1290 <listitem>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1291 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1292 <function>usbs_start_tx_buffer</function> is non-blocking. It merely
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1293 starts the transmit operation, and does not wait for completion. At
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1294 some later point the USB device driver will invoke the completion
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1295 function parameter with two arguments: the completion data defined by
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1296 the last parameter, and a result field. This result will be either an
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1297 error code &lt; <literal>0</literal>, or the amount of data
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1298 transferred which should correspond to the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1299 <parameter>length</parameter> argument. The most likely errors are
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1300 <literal>-EPIPE</literal> to indicate that the connection between the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1301 host and the target has been broken, and <literal>-EAGAIN</literal>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1302 for when the endpoint has been <link
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1303 linkend="usbs-halt">halted</link>. Specific USB device drivers may
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1304 define additional error conditions.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1305 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1306 </listitem>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1307 </orderedlist>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1308 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1309 The normal sequence of events is that the USB device driver will
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1310 update the appropriate hardware registers. At some point after that
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1311 the host will attempt to fetch data by transmitting an IN token. Since
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1312 a transmit operation is now in progress the peripheral can send a
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1313 packet of data, and the host will generate an ACK. At this point the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1314 USB hardware will generate an interrupt, and the device driver will
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1315 service this interrupt and arrange for a DSR to be called. Isochronous
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1316 and interrupt transfers involve just a single packet. However, bulk
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1317 transfers may involve multiple packets so the device driver has to
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1318 check whether there is more data to send and set things up for the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1319 next packet. When the device driver DSR detects a complete transfer it
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1320 will inform higher-level code by invoking the supplied completion
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1321 function.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1322 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1323 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1324 This means that the completion function will normally be invoked by a
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1325 DSR and not in thread context - although some USB device drivers may
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1326 have a different implementation. Therefore the completion function is
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1327 restricted in what it can do, in particular it must not make any
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1328 calls that will or may block such as locking a mutex or allocating
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1329 memory. The kernel documentation should be consulted for more details
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1330 of DSR's and interrupt handling generally.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1331 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1332 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1333 It is possible that the completion function will be invoked before
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1334 <function>usbs_start_tx_buffer</function> returns. Such an event would
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1335 be unusual because the transfer cannot happen until the next time the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1336 host tries to fetch data from this peripheral, but it may happen if,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1337 for example, another interrupt happens and a higher priority thread is
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1338 scheduled to run. Also, if the endpoint is currently halted then the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1339 completion function will be invoked immediately with
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1340 <literal>-EAGAIN</literal>: typically this will happen in the current
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1341 thread rather than in a separate DSR. The completion function is
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1342 allowed to start another transfer immediately by calling
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1343 <function>usbs_start_tx_buffer</function> again.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1344 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1345 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1346 USB device drivers are not expected to perform any locking. It is the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1347 responsibility of higher-level code to ensure that there is only one
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1348 transmit operation for a given endpoint in progress at any one time.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1349 If there are concurrent calls to
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1350 <function>usbs_start_tx_buffer</function> then the resulting behaviour
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1351 is undefined. For typical USB applications this does not present any
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1352 problems because only piece of code will access a given endpoint at
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1353 any particular time.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1354 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1355 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1356 The following code fragment illustrates a very simple use of
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1357 <function>usbs_start_tx_buffer</function> to implement a blocking
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1358 transmit, using a semaphore to synchronise between the foreground
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1359 thread and the DSR. For a simple example like this no completion data
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1360 is needed.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1361 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1362 <programlisting width=72>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1363 static int error_code = 0;
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1364 static cyg_sem_t completion_wait;
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1365
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1366 static void
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1367 completion_fn(void* data, int result)
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1368 {
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1369 error_code = result;
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1370 cyg_semaphore_post(&amp;completion_wait);
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1371 }
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1372
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1373 int
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1374 blocking_transmit(usbs_tx_endpoint* ep, const unsigned char* buf, int len)
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1375 {
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1376 error_code = 0;
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1377 usbs_start_tx_buffer(ep, buf, len, &amp;completion_fn, NULL);
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1378 cyg_semaphore_wait(&amp;completion_wait);
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1379 return error_code;
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1380 }
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1381 </programlisting>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1382 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1383 There is also a utility function <function>usbs_start</function>. This
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1384 can be used by code that wants to manipulate <link
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1385 linkend="usbs-data">data endpoints</link> directly, specifically the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1386 <structfield>complete_fn</structfield>,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1387 <structfield>complete_data</structfield>,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1388 <structfield>buffer</structfield> and
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1389 <structfield>buffer_size</structfield> fields.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1390 <function>usbs_start_tx</function> just calls a function supplied by
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1391 the device driver.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1392 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1393 </refsect1>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1394 </refentry>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1395
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1396 <!-- }}} -->
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1397 <!-- {{{ Halted endpoints -->
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1398
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1399 <refentry id="usbs-halt">
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1400 <refmeta>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1401 <refentrytitle>Halted Endpoints</refentrytitle>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1402 </refmeta>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1403 <refnamediv>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1404 <refname>Halted Endpoints</refname>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1405 <refpurpose>Support for Halting and Halted Endpoints</refpurpose>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1406 </refnamediv>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1407
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1408 <refsynopsisdiv>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1409 <funcsynopsis>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1410
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1411 <funcsynopsisinfo>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1412 #include &lt;cyg/io/usb/usbs.h&gt;
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1413 </funcsynopsisinfo>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1414
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1415 <funcprototype>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1416 <funcdef>cyg_bool <function>usbs_rx_endpoint_halted</function></funcdef>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1417 <paramdef>usbs_rx_endpoint* <parameter>ep</parameter></paramdef>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1418 </funcprototype>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1419 <funcprototype>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1420 <funcdef>void <function>usbs_set_rx_endpoint_halted</function></funcdef>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1421 <paramdef>usbs_rx_endpoint* <parameter>ep</parameter></paramdef>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1422 <paramdef>cyg_bool <parameter>new_state</parameter></paramdef>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1423 </funcprototype>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1424 <funcprototype>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1425 <funcdef>void <function>usbs_start_rx_endpoint_wait</function></funcdef>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1426 <paramdef>usbs_rx_endpoint* <parameter>ep</parameter></paramdef>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1427 <paramdef>void (*)(void*, int) <parameter>complete_fn</parameter></paramdef>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1428 <paramdef>void * <parameter>complete_data</parameter></paramdef>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1429 </funcprototype>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1430
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1431 <funcprototype>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1432 <funcdef>cyg_bool
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1433 <function>usbs_tx_endpoint_halted</function></funcdef>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1434 <paramdef>usbs_tx_endpoint* <parameter>ep</parameter></paramdef>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1435 </funcprototype>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1436 <funcprototype>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1437 <funcdef>void <function>usbs_set_tx_endpoint_halted</function></funcdef>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1438 <paramdef>usbs_tx_endpoint* <parameter>ep</parameter></paramdef>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1439 <paramdef>cyg_bool <parameter>new_state</parameter></paramdef>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1440 </funcprototype>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1441 <funcprototype>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1442 <funcdef>void <function>usbs_start_tx_endpoint_wait</function></funcdef>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1443 <paramdef>usbs_tx_endpoint* <parameter>ep</parameter></paramdef>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1444 <paramdef>void (*)(void*, int) <parameter>complete_fn</parameter></paramdef>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1445 <paramdef>void * <parameter>complete_data</parameter></paramdef>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1446 </funcprototype>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1447
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1448 </funcsynopsis>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1449 </refsynopsisdiv>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1450
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1451 <refsect1><title><function>Description</function></title>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1452 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1453 Normal USB traffic involves straightforward handshakes, with either an
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1454 <literal>ACK</literal> to indicate that a packet was transferred
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1455 without errors, or a <literal>NAK</literal> if an error occurred, or
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1456 if a peripheral is currently unable to process another packet from the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1457 host, or has no packet to send to the host. There is a third form of
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1458 handshake, a <literal>STALL</literal>, which indicates that the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1459 endpoint is currently <emphasis>halted</emphasis>.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1460 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1461 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1462 When an endpoint is halted it means that the host-side code needs to
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1463 take some sort of recovery action before communication over that
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1464 endpoint can resume. The exact circumstances under which this can
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1465 happen are not defined by the USB specification, but one example would
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1466 be a protocol violation if say the peripheral attempted to transmit
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1467 more data to the host than was permitted by the protocol in use. The
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1468 host can use the standard control messages get-status, set-feature and
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1469 clear-feature to examine and manipulate the halted status of a given
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1470 endpoint. There are USB-specific functions which can be used inside
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1471 the peripheral to achieve the same effect. Once an endpoint has been
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1472 halted the host can then interact with the peripheral using class or
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1473 vendor control messages to perform appropriate recovery, and then the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1474 halted condition can be cleared.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1475 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1476 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1477 Halting an endpoint does not constitute a device state change, and
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1478 there is no mechanism by which higher-level code can be informed
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1479 immediately. However, any ongoing receive or transmit operations will
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1480 be aborted with an <literal>-EAGAIN</literal> error, and any new
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1481 receives or transmits will fail immediately with the same error.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1482 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1483 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1484 There are six functions to support halted endpoints, one set for
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1485 receive endpoints and another for transmit endpoints, with both sets
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1486 behaving in essentially the same way. The first,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1487 <function>usbs_rx_endpoint_halted</function>, can be used to determine
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1488 whether or not an endpoint is currently halted: it takes a single
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1489 argument that identifies the endpoint of interest. The second
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1490 function, <function>usbs_set_rx_endpoint_halted</function>, can be
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1491 used to change the halted condition of an endpoint: it takes two
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1492 arguments; one to identify the endpoint and another to specify the new
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1493 state. The last function
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1494 <function>usbs_start_rx_endpoint_wait</function> operates in much the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1495 same way as <function>usbs_start_rx_buffer</function>: when the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1496 endpoint is no longer halted the device driver will invoke the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1497 supplied completion function with a status of 0. The completion
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1498 function has the same signature as that for a transfer operation.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1499 Often it will be possible to use a single completion function and have
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1500 the foreground code invoke either
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1501 <function>usbs_start_rx_buffer</function> or
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1502 <function>usbs_start_rx_endpoint_wait</function> depending on the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1503 current state of the endpoint.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1504 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1505 </refsect1>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1506 </refentry>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1507
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1508 <!-- }}} -->
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1509 <!-- {{{ Control Endpoint -->
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1510
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1511 <refentry id="usbs-control">
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1512 <refmeta>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1513 <refentrytitle>Control Endpoints</refentrytitle>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1514 </refmeta>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1515 <refnamediv>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1516 <refname>Control Endpoints</refname>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1517 <refpurpose>Control endpoint data structure</refpurpose>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1518 </refnamediv>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1519
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1520 <refsynopsisdiv>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1521 <synopsis>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1522 #include &lt;cyg/io/usb/usbs.h&gt;
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1523
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1524 typedef struct usbs_control_endpoint {
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1525 *hellip;
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1526 } usbs_control_endpoint;
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1527 </synopsis>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1528 </refsynopsisdiv>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1529
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1530 <refsect1><title><literal>usbs_control_endpoint</literal> Data Structure</title>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1531 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1532 The device driver for a USB slave device should supply one
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1533 <structname>usbs_control_endpoint</structname> data structure per USB
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1534 device. This corresponds to endpoint 0 which will be used for all
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1535 control message interaction between the host and that device. The data
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1536 structure is also used for internal management purposes, for example
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1537 to keep track of the current state. In a typical USB peripheral there
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1538 will only be one such data structure in the entire system, but if
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1539 there are multiple USB slave ports, allowing the peripheral to be
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1540 connected to multiple hosts, then there will be a separate data
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1541 structure for each one. The name or names of the data structures are
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1542 determined by the device drivers. For example, the SA11x0 USB device
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1543 driver package provides <literal>usbs_sa11x0_ep0</literal>.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1544 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1545 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1546 The operations on a control endpoint do not fit cleanly into a
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1547 conventional open/read/write I/O model. For example, when the host
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1548 sends a control message to the USB peripheral this may be one of four
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1549 types: standard, class, vendor and reserved. Some or all of the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1550 standard control messages will be handled automatically by the common
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1551 USB slave package or by the device driver itself. Other standard
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1552 control messages and the other types of control messages may be
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1553 handled by a class-specific package or by application code. Although
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1554 it would be possible to have devtab entries such as
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1555 <literal>/dev/usbs_ep0/standard</literal> and
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1556 <literal>/dev/usbs_ep0/class</literal>, and then support read and
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1557 write operations on these devtab entries, this would add significant
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1558 overhead and code complexity. Instead, all of the fields in the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1559 control endpoint data structure are public and can be manipulated
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1560 directly by higher level code if and when required.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1561 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1562 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1563 Control endpoints involve a number of callback functions, with
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1564 higher-level code installing suitable function pointers in the control
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1565 endpoint data structure. For example, if the peripheral involves
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1566 vendor-specific control messages then a suitable handler for these
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1567 messages should be installed. Although the exact details depend on the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1568 device driver, typically these callback functions will be invoked at
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1569 DSR level rather than thread level. Therefore, only certain eCos
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1570 functions can be invoked; specifically, those functions that are
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1571 guaranteed not to block. If a potentially blocking function such as a
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1572 semaphore wait or a mutex lock operation is invoked from inside the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1573 callback then the resulting behaviour is undefined, and the system as
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1574 a whole may fail. In addition, if one of the callback functions
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1575 involves significant processing effort then this may adversely affect
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1576 the system's real time characteristics. The eCos kernel documentation
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1577 should be consulted for more details of DSR handling.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1578 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1579
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1580 <refsect2><title>Initialization</title>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1581 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1582 The <structname>usbs_control_endpoint</structname> data structure
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1583 contains the following fields related to initialization.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1584 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1585 <programlisting width=72>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1586 typedef struct usbs_control_endpoint {
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1587 &hellip;
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1588 const usbs_enumeration_data* enumeration_data;
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1589 void (*start_fn)(usbs_control_endpoint*);
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1590 &hellip;
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1591 };
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1592 </programlisting>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1593 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1594 It is the responsibility of higher-level code, usually the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1595 application, to define the USB enumeration data. This needs to be
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1596 installed in the control endpoint data structure early on during
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1597 system startup, before the USB device is actually started and any
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1598 interaction with the host is possible. Details of the enumeration data
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1599 are supplied in the section <link linkend="usbs-enum">USB Enumeration
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1600 Data</link>. Typically, the enumeration data is constant for a given
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1601 peripheral, although it can be constructed dynamically if necessary.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1602 However, the enumeration data cannot change while the peripheral is
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1603 connected to a host: the peripheral cannot easily claim to be a
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1604 keyboard one second and a printer the next.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1605 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1606 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1607 The <structfield>start_fn</structfield> member is normally accessed
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1608 via the utility <link
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1609 linkend="usbs-start"><function>usbs_start</function></link> rather
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1610 than directly. It is provided by the device driver and should be
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1611 invoked once the system is fully initialized and interaction with the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1612 host is possible. A typical implementation would change the USB data
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1613 pins from tristated to active. If the peripheral is already plugged
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1614 into a host then the latter should detect this change and start
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1615 interacting with the peripheral, including requesting the enumeration
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1616 data.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1617 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1618 </refsect2>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1619
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1620 <refsect2><title id="usbs-control-state">State</title>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1621 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1622 There are three <structname>usbs_control_endpoint</structname> fields
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1623 related to the current state of a USB slave device, plus some state
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1624 constants and an enumeration of the possible state changes:
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1625 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1626 <programlisting width=72>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1627 typedef struct usbs_control_endpoint {
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1628 &hellip;
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1629 int state;
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1630 void (*state_change_fn)(struct usbs_control_endpoint*, void*,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1631 usbs_state_change, int);
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1632 void* state_change_data;
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1633 &hellip;
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1634 };
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1635
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1636 #define USBS_STATE_DETACHED 0x01
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1637 #define USBS_STATE_ATTACHED 0x02
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1638 #define USBS_STATE_POWERED 0x03
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1639 #define USBS_STATE_DEFAULT 0x04
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1640 #define USBS_STATE_ADDRESSED 0x05
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1641 #define USBS_STATE_CONFIGURED 0x06
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1642 #define USBS_STATE_MASK 0x7F
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1643 #define USBS_STATE_SUSPENDED (1 &lt;&lt; 7)
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1644
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1645 typedef enum {
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1646 USBS_STATE_CHANGE_DETACHED = 1,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1647 USBS_STATE_CHANGE_ATTACHED = 2,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1648 USBS_STATE_CHANGE_POWERED = 3,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1649 USBS_STATE_CHANGE_RESET = 4,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1650 USBS_STATE_CHANGE_ADDRESSED = 5,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1651 USBS_STATE_CHANGE_CONFIGURED = 6,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1652 USBS_STATE_CHANGE_DECONFIGURED = 7,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1653 USBS_STATE_CHANGE_SUSPENDED = 8,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1654 USBS_STATE_CHANGE_RESUMED = 9
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1655 } usbs_state_change;
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1656 </programlisting>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1657 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1658 The USB standard defines a number of states for a given USB
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1659 peripheral. The initial state is <emphasis>detached</emphasis>, where
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1660 the peripheral is either not connected to a host at all or, from the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1661 host's perspective, the peripheral has not started up yet because the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1662 relevant pins are tristated. The peripheral then moves via
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1663 intermediate <emphasis>attached</emphasis> and
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1664 <emphasis>powered</emphasis> states to its default or
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1665 <emphasis>reset</emphasis> state, at which point the host and
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1666 peripheral can actually start exchanging data. The first message is
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1667 from host to peripheral and provides a unique 7-bit address within the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1668 local USB network, resulting in a state change to
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1669 <emphasis>addressed</emphasis>. The host then requests enumeration
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1670 data and performs other initialization. If everything succeeds the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1671 host sends a standard set-configuration control message, after which
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1672 the peripheral is <emphasis>configured</emphasis> and expected to be
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1673 up and running. Note that some USB device drivers may be unable to
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1674 distinguish between the <emphasis>detached</emphasis>,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1675 <emphasis>attached</emphasis> and <emphasis>powered</emphasis> states
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1676 but generally this is not important to higher-level code.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1677 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1678 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1679 A USB host should generate at least one token every millisecond. If a
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1680 peripheral fails to detect any USB traffic for a period of time then
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1681 typically this indicates that the host has entered a power-saving
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1682 mode, and the peripheral should do the same if possible. This
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1683 corresponds to the <emphasis>suspended</emphasis> bit. The actual
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1684 state is a combination of <emphasis>suspended</emphasis> and the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1685 previous state, for example <emphasis>configured</emphasis> and
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1686 <emphasis>suspended</emphasis> rather than just
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1687 <emphasis>suspended</emphasis>. When the peripheral subsequently
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1688 detects USB traffic it would switch back to the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1689 <emphasis>configured</emphasis> state.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1690 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1691 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1692 The USB device driver and the common USB slave package will maintain
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1693 the current state in the control endpoint's
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1694 <structfield>state</structfield> field. There should be no need for
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1695 any other code to change this field, but it can be examined whenever
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1696 appropriate. In addition whenever a state change occurs the generic
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1697 code can invoke a state change callback function. By default, no such
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1698 callback function will be installed. Some class-specific packages such
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1699 as the USB-ethernet package will install a suitable function to keep
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1700 track of whether or not the host-peripheral connection is up, that is
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1701 whether or not ethernet packets can be exchanged. Application code can
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1702 also update this field. If multiple parties want to be informed of
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1703 state changes, for example both a class-specific package and
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1704 application code, then typically the application code will install its
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1705 state change handler after the class-specific package and is
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1706 responsible for chaining into the package's handler.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1707 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1708 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1709 The state change callback function is invoked with four arguments. The
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1710 first identifies the control endpoint. The second is an arbitrary
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1711 pointer: higher-level code can fill in the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1712 <structfield>state_change_data</structfield> field to set this. The
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1713 third argument specifies the state change that has occurred, and the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1714 last argument supplies the previous state (the new state is readily
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1715 available from the control endpoint structure).
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1716 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1717 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1718 eCos does not provide any utility functions for updating or examining
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1719 the <structfield>state_change_fn</structfield> or
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1720 <structfield>state_change_data</structfield> fields. Instead, it is
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1721 expected that the fields in the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1722 <structname>usbs_control_endpoint</structname> data structure will be
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1723 manipulated directly. Any utility functions would do just this, but
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1724 at the cost of increased code and cpu overheads.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1725 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1726 </refsect2>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1727
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1728 <refsect2><title id="usbs-control-standard">Standard Control Messages</title>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1729 <programlisting width=88>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1730 typedef struct usbs_control_endpoint {
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1731 &hellip;
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1732 unsigned char control_buffer[8];
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1733 usbs_control_return (*standard_control_fn)(struct usbs_control_endpoint*, void*);
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1734 void* standard_control_data;
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1735 &hellip;
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1736 } usbs_control_endpoint;
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1737
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1738 typedef enum {
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1739 USBS_CONTROL_RETURN_HANDLED = 0,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1740 USBS_CONTROL_RETURN_UNKNOWN = 1,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1741 USBS_CONTROL_RETURN_STALL = 2
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1742 } usbs_control_return;
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1743
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1744 extern usbs_control_return usbs_handle_standard_control(struct usbs_control_endpoint*);
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1745 </programlisting>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1746 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1747 When a USB peripheral is connected to the host it must always respond
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1748 to control messages sent to endpoint 0. Control messages always
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1749 consist of an initial eight-byte header, containing fields such as a
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1750 request type. This may be followed by a further data transfer, either
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1751 from host to peripheral or from peripheral to host. The way this is
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1752 handled is described in the <link
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1753 linkend="usbs-control-buffer">Buffer Management</link> section below.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1754 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1755 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1756 The USB device driver will always accept the initial eight-byte
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1757 header, storing it in the <structfield>control_buffer</structfield>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1758 field. Then it determines the request type: standard, class, vendor,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1759 or reserved. The way in which the last three of these are processed is
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1760 described in the section <link linkend="usbs-control-other">Other
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1761 Control Messages</link>. Some
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1762 standard control messages will be handled by the device driver itself;
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1763 typically the <emphasis>set-address</emphasis> request and the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1764 <emphasis>get-status</emphasis>, <emphasis>set-feature</emphasis> and
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1765 <emphasis>clear-feature</emphasis> requests when applied to endpoints.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1766 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1767 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1768 If a standard control message cannot be handled by the device driver
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1769 itself, the driver checks the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1770 <structfield>standard_control_fn</structfield> field in the control
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1771 endpoint data structure. If higher-level code has installed a suitable
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1772 callback function then this will be invoked with two argument, the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1773 control endpoint data structure itself and the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1774 <structfield>standard_control_data</structfield> field. The latter
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1775 allows the higher level code to associate arbitrary data with the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1776 control endpoint. The callback function can return one of three
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1777 values: <emphasis>HANDLED</emphasis> to indicate that the request has
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1778 been processed; <emphasis>UNKNOWN</emphasis> if the message should be
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1779 handled by the default code; or <emphasis>STALL</emphasis> to indicate
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1780 an error condition. If higher level code has not installed a callback
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1781 function or if the callback function has returned
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1782 <emphasis>UNKNOWN</emphasis> then the device driver will invoke a
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1783 default handler, <function>usbs_handle_standard_control</function>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1784 provided by the common USB slave package.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1785 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1786 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1787 The default handler can cope with all of the standard control messages
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1788 for a simple USB peripheral. However, if the peripheral involves
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1789 multiple configurations, multiple interfaces in a configuration, or
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1790 alternate settings for an interface, then this cannot be handled by
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1791 generic code. For example, a multimedia peripheral may support various
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1792 alternate settings for a given data source with different bandwidth
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1793 requirements, and the host can select a setting that takes into
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1794 account the current load. Clearly higher-level code needs to be aware
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1795 when the host changes the current setting, so that it can adjust the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1796 rate at which data is fed to or retrieved from the host. Therefore the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1797 higher-level code needs to install its own standard control callback
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1798 and process appropriate messages, rather than leaving these to the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1799 default handler.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1800 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1801 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1802 The default handler will take care of the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1803 <emphasis>get-descriptor</emphasis> request used to obtain the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1804 enumeration data. It has support for string descriptors but ignores
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1805 language encoding issues. If language encoding is important for the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1806 peripheral then this will have to be handled by an
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1807 application-specific standard control handler.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1808 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1809 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1810 The header file <filename
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1811 class="headerfile">&lt;cyg/io/usb/usb.h&gt;</filename> defines various
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1812 constants related to control messages, for example the function codes
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1813 corresponding to the standard request types. This header file is
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1814 provided by the common USB package, not by the USB slave package,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1815 since the information is also relevant to USB hosts.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1816 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1817 </refsect2>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1818
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1819 <refsect2><title id="usbs-control-other">Other Control Messages</title>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1820 <programlisting width=88>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1821 typedef struct usbs_control_endpoint {
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1822 &hellip;
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1823 usbs_control_return (*class_control_fn)(struct usbs_control_endpoint*, void*);
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1824 void* class_control_data;
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1825 usbs_control_return (*vendor_control_fn)(struct usbs_control_endpoint*, void*);
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1826 void* vendor_control_data;
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1827 usbs_control_return (*reserved_control_fn)(struct usbs_control_endpoint*, void*);
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1828 void* reserved_control_data;
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1829 &hellip;
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1830 } usbs_control_endpoint;
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1831 </programlisting>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1832 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1833 Non-standard control messages always have to be processed by
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1834 higher-level code. This could be class-specific packages. For example,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1835 the USB-ethernet package will handle requests for getting the MAC
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1836 address and for enabling or disabling promiscuous mode. In all cases
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1837 the device driver will store the initial request in the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1838 <structfield>control_buffer</structfield> field, check for an
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1839 appropriate handler, and invoke it with details of the control
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1840 endpoint and any handler-specific data that has been installed
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1841 alongside the handler itself. The handler should return either
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1842 <literal>USBS_CONTROL_RETURN_HANDLED</literal> to report success or
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1843 <literal>USBS_CONTROL_RETURN_STALL</literal> to report failure. The
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1844 device driver will report this to the host.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1845 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1846 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1847 If there are multiple parties interested in a particular type of
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1848 control messages, it is the responsibility of application code to
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1849 install an appropriate handler and process the requests appropriately.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1850 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1851 </refsect2>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1852
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1853 <refsect2><title id="usbs-control-buffer">Buffer Management</title>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1854 <programlisting width=76>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1855 typedef struct usbs_control_endpoint {
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1856 &hellip;
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1857 unsigned char* buffer;
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1858 int buffer_size;
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1859 void (*fill_buffer_fn)(struct usbs_control_endpoint*);
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1860 void* fill_data;
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1861 int fill_index;
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1862 usbs_control_return (*complete_fn)(struct usbs_control_endpoint*, int);
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1863 &hellip;
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1864 } usbs_control_endpoint;
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1865 </programlisting>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1866 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1867 Many USB control messages involve transferring more data than just the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1868 initial eight-byte header. The header indicates the direction of the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1869 transfer, OUT for host to peripheral or IN for peripheral to host.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1870 It also specifies a length field, which is exact for an OUT transfer
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1871 or an upper bound for an IN transfer. Control message handlers can
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1872 manipulate six fields within the control endpoint data structure to
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1873 ensure that the transfer happens correctly.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1874 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1875 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1876 For an OUT transfer, the handler should examine the length field in
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1877 the header and provide a single buffer for all the data. A
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1878 class-specific protocol would typically impose an upper bound on the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1879 amount of data, allowing the buffer to be allocated statically.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1880 The handler should update the <structfield>buffer</structfield> and
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1881 <structfield>complete_fn</structfield> fields. When all the data has
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1882 been transferred the completion callback will be invoked, and its
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1883 return value determines the response sent back to the host. The USB
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1884 standard allows for a new control message to be sent before the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1885 current transfer has completed, effectively cancelling the current
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1886 operation. When this happens the completion function will also be
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1887 invoked. The second argument to the completion function specifies what
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1888 has happened, with a value of 0 indicating success and an error code
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1889 such as <literal>-EPIPE</literal> or <literal>-EIO</literal>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1890 indicating that the current transfer has been cancelled.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1891 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1892 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1893 IN transfers are a little bit more complicated. The required
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1894 information, for example the enumeration data, may not be in a single
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1895 contiguous buffer. Instead a mechanism is provided by which the buffer
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1896 can be refilled, thus allowing the transfer to move from one record to
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1897 the next. Essentially, the transfer operates as follows:
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1898 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1899 <orderedlist>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1900 <listitem>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1901 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1902 When the host requests another chunk of data (typically eight bytes),
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1903 the USB device driver will examine the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1904 <structfield>buffer_size</structfield> field. If non-zero then
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1905 <structfield>buffer</structfield> contains at least one more byte of
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1906 data, and then <structfield>buffer_size</structfield> is decremented.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1907 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1908 </listitem>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1909 <listitem>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1910 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1911 When <structfield>buffer_size</structfield> has dropped to 0, the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1912 <structfield>fill_buffer_fn</structfield> field will be examined. If
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1913 non-null it will be invoked to refill the buffer.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1914 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1915 </listitem>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1916 <listitem>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1917 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1918 The <structfield>fill_data</structfield> and
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1919 <structfield>fill_index</structfield> fields are not used by the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1920 device driver. Instead these fields are available to the refill
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1921 function to keep track of the current state of the transfer.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1922 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1923 </listitem>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1924 <listitem>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1925 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1926 When <structfield>buffer_size</structfield> is 0 and
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1927 <structfield>fill_buffer_fn</structfield> is NULL, no more data is
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1928 available and the transfer has completed.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1929 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1930 </listitem>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1931 <listitem>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1932 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1933 Optionally a completion function can be installed. This will be
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1934 invoked with 0 if the transfer completes successfully, or with an
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1935 error code if the transfer is cancelled because of another control
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1936 messsage.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1937 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1938 </listitem>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1939 </orderedlist>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1940 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1941 If the requested data is contiguous then the only fields that need
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1942 to be manipulated are <structfield>buffer</structfield> and
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1943 <structfield>buffer_size</structfield>, and optionally
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1944 <structfield>complete_fn</structfield>. If the requested data is not
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1945 contiguous then the initial control message handler should update
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1946 <structfield>fill_buffer_fn</structfield> and some or all of the other
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1947 fields, as required. An example of this is the handling of the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1948 standard <emphasis>get-descriptor</emphasis> control message by
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1949 <function>usbs_handle_standard_control</function>.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1950 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1951 </refsect2>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1952
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1953 <refsect2><title>Polling Support</title>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1954 <programlisting width=72>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1955 typedef struct usbs_control_endpoint {
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1956 void (*poll_fn)(struct usbs_control_endpoint*);
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1957 int interrupt_vector;
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1958 &hellip;
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1959 } usbs_control_endpoint;
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1960 </programlisting>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1961 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1962 In nearly all circumstances USB I/O should be interrupt-driven.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1963 However, there are special environments such as RedBoot where polled
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1964 operation may be appropriate. If the device driver can operate in
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1965 polled mode then it will provide a suitable function via the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1966 <structfield>poll_fn</structfield> field, and higher-level code can
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1967 invoke this regularly. This polling function will take care of all
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1968 endpoints associated with the device, not just the control endpoint.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1969 If the USB hardware involves a single interrupt vector then this will
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1970 be identified in the data structure as well.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1971 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1972 </refsect2>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1973
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1974 </refsect1>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1975
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1976 </refentry>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1977
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1978 <!-- }}} -->
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1979 <!-- {{{ Data Endpoints -->
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1980
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1981 <refentry id="usbs-data">
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1982 <refmeta>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1983 <refentrytitle>Data Endpoints</refentrytitle>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1984 </refmeta>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1985 <refnamediv>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1986 <refname>Data Endpoints</refname>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1987 <refpurpose>Data endpoint data structures</refpurpose>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1988 </refnamediv>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1989
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1990 <refsynopsisdiv>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1991 <synopsis>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1992 #include &lt;cyg/io/usb/usbs.h&gt;
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1993
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1994 typedef struct usbs_rx_endpoint {
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1995 void (*start_rx_fn)(struct usbs_rx_endpoint*);
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1996 void (*set_halted_fn)(struct usbs_rx_endpoint*, cyg_bool);
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1997 void (*complete_fn)(void*, int);
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1998 void* complete_data;
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
1999 unsigned char* buffer;
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2000 int buffer_size;
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2001 cyg_bool halted;
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2002 } usbs_rx_endpoint;
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2003
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2004 typedef struct usbs_tx_endpoint {
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2005 void (*start_tx_fn)(struct usbs_tx_endpoint*);
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2006 void (*set_halted_fn)(struct usbs_tx_endpoint*, cyg_bool);
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2007 void (*complete_fn)(void*, int);
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2008 void* complete_data;
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2009 const unsigned char* buffer;
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2010 int buffer_size;
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2011 cyg_bool halted;
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2012 } usbs_tx_endpoint;
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2013 </synopsis>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2014 </refsynopsisdiv>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2015
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2016 <refsect1><title>Receive and Transmit Data Structures</title>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2017 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2018 In addition to a single <structname>usbs_control_endpoint</structname>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2019 data structure per USB slave device, the USB device driver should also
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2020 provide receive and transmit data structures corresponding to the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2021 other endpoints. The names of these are determined by the device
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2022 driver. For example, the SA1110 USB device driver package provides
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2023 <literal>usbs_sa11x0_ep1</literal> for receives and
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2024 <literal>usbs_sa11x0_ep2</literal> for transmits.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2025 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2026 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2027 Unlike control endpoints, the common USB slave package does provide a
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2028 number of utility routines to manipulate data endpoints. For example
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2029 <link
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2030 linkend="usbs-start-rx"><function>usbs_start_rx_buffer</function></link>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2031 can be used to receive data from the host into a buffer. In addition
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2032 the USB device driver can provide devtab entries such as
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2033 <literal>/dev/usbs1r</literal> and <literal>/dev/usbs2w</literal>, so
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2034 higher-level code can <function>open</function> these devices and then
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2035 perform blocking <function>read</function> and
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2036 <function>write</function> operations.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2037 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2038 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2039 However, the operation of data endpoints and the various
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2040 endpoint-related functions is relatively straightforward. First
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2041 consider a <structname>usbs_rx_endpoint</structname> structure. The
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2042 device driver will provide the members
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2043 <structfield>start_rx_fn</structfield> and
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2044 <structfield>set_halted_fn</structfield>, and it will maintain the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2045 <structfield>halted</structfield> field. To receive data, higher-level
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2046 code sets the <structfield>buffer</structfield>,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2047 <structfield>buffer_size</structfield>,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2048 <structfield>complete_fn</structfield> and optionally the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2049 <structfield>complete_data</structfield> fields. Next the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2050 <structfield>start_rx_fn</structfield> member should be called. When
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2051 the transfer has finished the device driver will invoke the completion
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2052 function, using <structfield>complete_data</structfield> as the first
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2053 argument and a size field for the second argument. A negative size
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2054 indicates an error of some sort: <literal>-EGAIN</literal> indicates
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2055 that the endpoint has been halted, usually at the request of the host;
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2056 <literal>-EPIPE</literal> indicates that the connection between the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2057 host and the peripheral has been broken. Certain device drivers may
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2058 generate other error codes.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2059 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2060 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2061 If higher-level code needs to halt or unhalt an endpoint then it can
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2062 invoke the <structfield>set_halted_fn</structfield> member. When an
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2063 endpoint is halted, invoking <structfield>start_rx_fn</structfield>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2064 wit <structfield>buffer_size</structfield> set to 0 indicates that
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2065 higher-level code wants to block until the endpoint is no longer
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2066 halted; at that point the completion function will be invoked.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2067 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2068 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2069 USB device drivers are allowed to assume that higher-level protocols
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2070 ensure that host and peripheral agree on the amount of data that will
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2071 be transferred, or at least on an upper bound. Therefore there is no
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2072 need for the device driver to maintain its own buffers, and copy
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2073 operations are avoided. If the host sends more data than expected then
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2074 the resulting behaviour is undefined.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2075 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2076 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2077 Transmit endpoints work in essentially the same way as receive
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2078 endpoints. Higher-level code should set the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2079 <structfield>buffer</structfield> and
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2080 <structfield>buffer_size</structfield> fields to point at the data to
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2081 be transferred, then call <structfield>start_tx_fn</structfield>, and
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2082 the device driver will invoked the completion function when the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2083 transfer has completed.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2084 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2085 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2086 USB device drivers are not expected to perform any locking. If at any
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2087 time there are two concurrent receive operations for a given endpoint,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2088 or two concurrent transmit operations, then the resulting behaviour is
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2089 undefined. It is the responsibility of higher-level code to perform
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2090 any synchronisation that may be necessary. In practice, conflicts are
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2091 unlikely because typically a given endpoint will only be accessed
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2092 sequentially by just one part of the overall system.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2093 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2094
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2095 </refsect1>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2096
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2097 </refentry>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2098
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2099 <!-- }}} -->
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2100 <!-- {{{ Writing a USB Device Driver -->
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2101
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2102 <refentry id="usbs-writing">
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2103 <refmeta>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2104 <refentrytitle>Writing a USB Device Driver</refentrytitle>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2105 </refmeta>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2106 <refnamediv>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2107 <refname>Writing a USB Device Driver</refname>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2108 <refpurpose>USB Device Driver Porting Guide</refpurpose>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2109 </refnamediv>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2110
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2111 <refsect1><title>Introduction</title>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2112 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2113 Often the best way to write a USB device driver will be to start with
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2114 an existing one and modify it as necessary. The information given here
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2115 is intended primarily as an outline rather than as a complete guide.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2116 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2117 <note>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2118 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2119 At the time of writing only one USB device driver has been
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2120 implemented. Hence it is possible, perhaps probable, that some
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2121 portability issues have not yet been addressed. One issue
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2122 involves the different types of transfer, for example the initial
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2123 target hardware had no support for isochronous or interrupt transfers,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2124 so additional functionality may be needed to switch between transfer
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2125 types. Another issue would be hardware where a given endpoint number,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2126 say endpoint 1, could be used for either receiving or transmitting
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2127 data, but not both because a single fifo is used. Issues like these
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2128 will have to be resolved as and when additional USB device drivers are
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2129 written.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2130 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2131 </note>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2132 </refsect1>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2133
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2134 <refsect1><title>The Control Endpoint</title>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2135 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2136 A USB device driver should provide a single <link
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2137 linkend="usbs-control"><structname>usbs_control_endpoint</structname></link>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2138 data structure for every USB device. Typical peripherals will have
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2139 only one USB port so there will be just one such data structure in the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2140 entire system, but theoretically it is possible to have multiple USB
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2141 devices. These may all involve the same chip, in which case a single
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2142 device driver should support multiple device instances, or they may
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2143 involve different chips. The name or names of these data structures
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2144 are determined by the device driver, but appropriate care should be
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2145 taken to avoid name clashes.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2146 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2147 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2148 A USB device cannot be used unless the control endpoint data structure
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2149 exists. However, the presence of USB hardware in the target processor
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2150 or board does not guarantee that the application will necessarily want
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2151 to use that hardware. To avoid unwanted code or data overheads, the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2152 device driver can provide a configuration option to determine whether
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2153 or not the endpoint 0 data structure is actually provided. A default
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2154 value of <literal>CYGINT_IO_USB_SLAVE_CLIENTS</literal> ensures that
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2155 the USB driver will be enabled automatically if higher-level code does
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2156 require USB support, while leaving ultimate control to the user.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2157 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2158 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2159 The USB device driver is responsible for filling in the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2160 <structfield>start_fn</structfield>,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2161 <structfield>poll_fn</structfield> and
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2162 <structfield>interrupt_vector</structfield> fields. Usually this can
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2163 be achieved by static initialization. The driver is also largely
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2164 responsible for maintaining the <structfield>state</structfield>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2165 field. The <structfield>control_buffer</structfield> array should be
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2166 used to hold the first packet of a control message. The
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2167 <structfield>buffer</structfield> and other fields related to data
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2168 transfers will be managed <link
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2169 linkend="usbs-control-buffer">jointly</link> by higher-level code and
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2170 the device driver. The remaining fields are generally filled in by
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2171 higher-level code, although the driver should initialize them to NULL
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2172 values.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2173 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2174 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2175 Hardware permitting, the USB device should be inactive until the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2176 <structfield>start_fn</structfield> is invoked, for example by
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2177 tristating the appropriate pins. This prevents the host from
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2178 interacting with the peripheral before all other parts of the system
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2179 have initialized. It is expected that the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2180 <structfield>start_fn</structfield> will only be invoked once, shortly
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2181 after power-up.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2182 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2183 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2184 Where possible the device driver should detect state changes, such as
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2185 when the connection between host and peripheral is established, and
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2186 <link linkend="usbs-control-state">report</link> these to higher-level
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2187 code via the <structfield>state_change_fn</structfield> callback, if
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2188 any. The state change to and from configured state cannot easily be
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2189 handled by the device driver itself, instead higher-level code such as
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2190 the common USB slave package will take care of this.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2191 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2192 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2193 Once the connection between host and peripheral has been established,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2194 the peripheral must be ready to accept control messages at all times,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2195 and must respond to these within certain time constraints. For
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2196 example, the standard set-address control message must be handled
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2197 within 50ms. The USB specification provides more information on these
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2198 constraints. The device driver is responsible for receiving the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2199 initial packet of a control message. This packet will always be eight
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2200 bytes and should be stored in the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2201 <structfield>control_buffer</structfield> field. Certain standard
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2202 control messages should be detected and handled by the device driver
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2203 itself. The most important is set-address, but usually the get-status,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2204 set-feature and clear-feature requests when applied to halted
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2205 endpoints should also be handled by the driver. Other standard control
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2206 messages should first be passed on to the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2207 <structfield>standard_control_fn</structfield> callback (if any), and
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2208 finally to the default handler
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2209 <function>usbs_handle_standard_control</function> provided by the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2210 common USB slave package. Class, vendor and reserved control messages
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2211 should always be dispatched to the appropriate callback and there is
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2212 no default handler for these.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2213 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2214 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2215 Some control messages will involve further data transfer, not just the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2216 initial packet. The device driver must handle this in accordance with
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2217 the USB specification and the <link
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2218 linkend="usbs-control-buffer">buffer management strategy</link>. The
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2219 driver is also responsible for keeping track of whether or not the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2220 control operation has succeeded and generating an ACK or STALL
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2221 handshake.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2222 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2223 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2224 The polling support is optional and may not be feasible on all
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2225 hardware. It is only used in certain specialised environments such as
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2226 RedBoot. A typical implementation of the polling function would just
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2227 check whether or not an interrupt would have occurred and, if so, call
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2228 the same code that the interrupt handler would.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2229 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2230 </refsect1>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2231
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2232 <refsect1><title>Data Endpoints</title>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2233 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2234 In addition to the control endpoint data structure, a USB device
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2235 driver should also provide appropriate <link linkend="usbs-data">data
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2236 endpoint</link> data structures. Obviously this is only relevant if
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2237 the USB support generally is desired, that is if the control endpoint is
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2238 provided. In addition, higher-level code may not require all the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2239 endpoints, so it may be useful to provide configuration options that
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2240 control the presence of each endpoint. For example, the intended
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2241 application might only involve a single transmit endpoint and of
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2242 course control messages, so supporting receive endpoints might waste
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2243 memory.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2244 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2245 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2246 Conceptually, data endpoints are much simpler than the control
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2247 endpoint. The device driver has to supply two functions, one for
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2248 data transfers and another to control the halted condition. These
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2249 implement the functionality for
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2250 <link linkend="usbs-start-rx"><function>usbs_start_rx_buffer</function></link>,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2251 <link linkend="usbs-start-tx"><function>usbs_start_tx_buffer</function></link>,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2252 <link linkend="usbs-halt"><function>usbs_set_rx_endpoint_halted</function></link> and
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2253 <link linkend="usbs-halt"><function>usbs_set_tx_endpoint_halted</function></link>.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2254 The device driver is also responsible for maintaining the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2255 <structfield>halted</structfield> status.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2256 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2257 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2258 For data transfers, higher-level code will have filled in the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2259 <structfield>buffer</structfield>,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2260 <structfield>buffer_size</structfield>,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2261 <structfield>complete_fn</structfield> and
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2262 <structfield>complete_data</structfield> fields. The transfer function
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2263 should arrange for the transfer to start, allowing the host to send or
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2264 receive packets. Typically this will result in an interrupt at the end
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2265 of the transfer or after each packet. Once the entire transfer has
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2266 been completed, the driver's interrupt handling code should invoke the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2267 completion function. This can happen either in DSR context or thread
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2268 context, depending on the driver's implementation. There are a number
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2269 of special cases to consider. If the endpoint is halted when the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2270 transfer is started then the completion function can be invoked
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2271 immediately with <literal>-EAGAIN</literal>. If the transfer cannot be
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2272 completed because the connection is broken then the completion
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2273 function should be invoked with <literal>-EPIPE</literal>. If the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2274 endpoint is stalled during the transfer, either because of a standard
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2275 control message or because higher-level code calls the appropriate
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2276 <structfield>set_halted_fn</structfield>, then again the completion
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2277 function should be invoked with <literal>-EAGAIN</literal>. Finally,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2278 the <<function>usbs_start_rx_endpoint_wait</function> and
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2279 <function>usbs_start_tx_endpoint_wait</function> functions involve
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2280 calling the device driver's data transfer function with a buffer size
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2281 of 0 bytes.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2282 </para>
208
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2283 <note><para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2284 Giving a buffer size of 0 bytes a special meaning is problematical
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2285 because it prevents transfers of that size. Such transfers are allowed
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2286 by the USB protocol, consisting of just headers and acknowledgements
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2287 and an empty data phase, although rarely useful. A future modification
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2288 of the device driver specification will address this issue, although
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2289 care has to be taken that the functionality remains accessible through
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2290 devtab entries as well as via low-level accesses.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2291 </para></note>
151
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2292 </refsect1>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2293
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2294 <refsect1><title>Devtab Entries</title>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2295 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2296 For some applications or higher-level packages it may be more
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2297 convenient to use traditional open/read/write I/O calls rather than
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2298 the non-blocking USB I/O calls. To support this the device driver can
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2299 provide a devtab entry for each endpoint, for example:
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2300 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2301 <programlisting width=72>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2302 #ifdef CYGVAR_DEVS_USB_SA11X0_EP1_DEVTAB_ENTRY
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2303
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2304 static CHAR_DEVIO_TABLE(usbs_sa11x0_ep1_devtab_functions,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2305 &amp;cyg_devio_cwrite,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2306 &amp;usbs_devtab_cread,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2307 &amp;cyg_devio_bwrite,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2308 &amp;cyg_devio_bread,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2309 &amp;cyg_devio_select,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2310 &amp;cyg_devio_get_config,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2311 &amp;cyg_devio_set_config);
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2312
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2313 static CHAR_DEVTAB_ENTRY(usbs_sa11x0_ep1_devtab_entry,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2314 CYGDAT_DEVS_USB_SA11X0_DEVTAB_BASENAME "1r",
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2315 0,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2316 &amp;usbs_sa11x0_ep1_devtab_functions,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2317 &amp;usbs_sa11x0_devtab_dummy_init,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2318 0,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2319 (void*) &amp;usbs_sa11x0_ep1);
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2320 #endif
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2321 </programlisting>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2322 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2323 Again care must be taken to avoid name clashes. This can be achieved
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2324 by having a configuration option to control the base name, with a
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2325 default value of e.g. <literal>/dev/usbs</literal>, and appending an
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2326 endpoint-specific string. This gives the application developer
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2327 sufficient control to eliminate any name clashes. The common USB slave
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2328 package provides functions <function>usbs_devtab_cwrite</function> and
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2329 <function>usbs_devtab_cread</function>, which can be used in the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2330 function tables for transmit and receive endpoints respectively. The
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2331 private field <structfield>priv</structfield> of the devtab entry
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2332 should be a pointer to the underlying endpoint data structure.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2333 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2334 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2335 Because devtab entries are never accessed directly, only indirectly,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2336 they would usually be eliminated by the linker. To avoid this the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2337 devtab entries should normally be defined in a separate source file
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2338 which ends up the special library <filename>libextras.a</filename>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2339 rather than in the default library <filename>libtarget.a</filename>.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2340 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2341 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2342 Not all applications or higher-level packages will want to use the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2343 devtab entries and the blocking I/O facilities. It may be appropriate
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2344 for the device driver to provide additional configuration options that
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2345 control whether or not any or all of the devtab entries should be
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2346 provided, to avoid unnecessary memory overheads.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2347 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2348 </refsect1>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2349
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2350 <refsect1><title>Interrupt Handling</title>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2351 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2352 A typical USB device driver will need to service interrupts for all of
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2353 the endpoints and possibly for additional USB events such as entering
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2354 or leaving suspended mode. Usually these interrupts need not be
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2355 serviced directly by the ISR. Instead, they can be left to a DSR. If
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2356 the peripheral is not able to accept or send another packet just yet,
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2357 the hardware will generate a NAK and the host will just retry a little
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2358 bit later. If high throughput is required then it may be desirable to
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2359 handle the bulk transfer protocol largely at ISR level, that is take
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2360 care of each packet in the ISR and only activate the DSR once the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2361 whole transfer has completed.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2362 </para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2363 <para>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2364 Control messages may involve invoking arbitrary callback functions in
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2365 higher-level code. This should normally happen at DSR level. Doing it
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2366 at ISR level could seriously affect the system's interrupt latency and
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2367 impose unacceptable constraints on what operations can be performed by
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2368 those callbacks. If the device driver requires a thread anyway then it
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2369 may be appropriate to use this thread for invoking the callbacks, but
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2370 usually it is not worthwhile to add a new thread to the system just
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2371 for this; higher-level code is expected to write callbacks that
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2372 function sensibly at DSR level. Much the same applies to the
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2373 completion functions associated with data transfers. These should also
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2374 be invoked at DSR or thread level.
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
2375 </para>
208
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2376
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2377 </refsect1>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2378 <refsect1><title>Support for USB Testing</title>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2379 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2380 Optionally a USB device driver can provide support for the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2381 <link linkend="usbs-testing">USB test software</link>. This requires
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2382 defining a number of additional data structures, allowing the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2383 generic test code to work out just what the hardware is capable of and
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2384 hence what testing can be performed.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2385 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2386 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2387 The key data structure is
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2388 <structname>usbs_testing_endpoint</structname>, defined in <filename
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2389 class="headerfile">cyg/io/usb/usbs.h</filename>. In addition some
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2390 commonly required constants are provided by the common USB package in
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2391 <filename class="headerfile">cyg/io/usb/usb.h</filename>. One
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2392 <structname>usbs_testing_endpoint</structname> structure should be
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2393 defined for each supported endpoint. The following fields need to be
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2394 filled in:
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2395 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2396 <variablelist>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2397 <varlistentry>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2398 <term><structfield>endpoint_type</structfield></term>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2399 <listitem><para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2400 This specifies the type of endpoint and should be one of
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2401 <literal>USB_ENDPOINT_DESCRIPTOR_ATTR_CONTROL</literal>,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2402 <literal>BULK</literal>, <literal>ISOCHRONOUS</literal> or
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2403 <literal>INTERRUPT</literal>.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2404 </para></listitem>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2405 </varlistentry>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2406 <varlistentry>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2407 <term><structfield>endpoint_number</structfield></term>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2408 <listitem><para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2409 This identifies the number that should be used by the host
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2410 to address this endpoint. For a control endpoint it should
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2411 be 0. For other types of endpoints it should be between
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2412 1 and 15.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2413 </para></listitem>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2414 </varlistentry>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2415 <varlistentry>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2416 <term><structfield>endpoint_direction</structfield></term>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2417 <listitem><para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2418 For control endpoints this field is irrelevant. For other
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2419 types of endpoint it should be either
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2420 <literal>USB_ENDPOINT_DESCRIPTOR_ENDPOINT_IN</literal> or
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2421 <literal>USB_ENDPOINT_DESCRIPTOR_ENDPOINT_OUT</literal>. If a given
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2422 endpoint number can be used for traffic in both directions then
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2423 there should be two entries in the array, one for each direction.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2424 </para></listitem>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2425 </varlistentry>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2426 <varlistentry>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2427 <term><structfield>endpoint</structfield></term>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2428 <listitem><para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2429 This should be a pointer to the appropriate
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2430 <structname>usbs_control_endpoint</structname>,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2431 <structname>usbs_rx_endpoint</structname> or
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2432 <structname>usbs_tx_endpoint</structname> structure, allowing the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2433 generic testing code to perform low-level I/O.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2434 </para></listitem>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2435 </varlistentry>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2436 <varlistentry>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2437 <term><structfield>devtab_entry</structfield></term>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2438 <listitem><para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2439 If the endpoint also has an entry in the system's device table then
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2440 this field should give the corresponding string, for example
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2441 <literal>&quot;/dev/usbs1r&quot;</literal>. This allows the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2442 generic testing code to access the device via higher-level
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2443 calls like <function>open</function> and <function>read</function>.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2444 </para></listitem>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2445 </varlistentry>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2446 <varlistentry>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2447 <term><structfield>min_size</structfield></term>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2448 <listitem><para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2449 This indicates the smallest transfer size that the hardware can
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2450 support on this endpoint. Typically this will be one.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2451 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2452 <note><para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2453 Strictly speaking a minimum size of one is not quite right since it
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2454 is valid for a USB transfer to involve zero bytes, in other words a
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2455 transfer that involves just headers and acknowledgements and an
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2456 empty data phase, and that should be tested as well. However current
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2457 device drivers interpret a transfer size of 0 as special, so that
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2458 would have to be resolved first.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2459 </para></note>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2460 </listitem>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2461 </varlistentry>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2462 <varlistentry>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2463 <term><structfield>max_size</structfield></term>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2464 <listitem><para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2465 Similarly, this specifies the largest transfer size. For control
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2466 endpoints the USB protocol uses only two bytes to hold the transfer
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2467 length, so there is an upper bound of 65535 bytes. In practice
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2468 it is very unlikely that any control transfers would ever need to
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2469 be this large, and in fact such transfers would take a long time
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2470 and probably violate timing constraints. For other types of endpoint
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2471 any of the protocol, the hardware, or the device driver may impose
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2472 size limits. For example a given device driver might be unable to
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2473 cope with transfers larger than 65535 bytes. If it should be
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2474 possible to transfer arbitrary amounts of data then a value of
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2475 <literal>-1</literal> indicates no upper limit, and transfer
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2476 sizes will be limited by available memory and by the capabilities
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2477 of the host machine.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2478 </para></listitem>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2479 </varlistentry>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2480 <varlistentry>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2481 <term><structfield>max_in_padding</structfield></term>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2482 <listitem><para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2483 This field is needed on some hardware where it is impossible to
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2484 send packets of a certain size. For example the hardware may be
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2485 incapable of sending an empty bulk packet to terminate a transfer
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2486 that is an exact multiple of the 64-byte bulk packet size.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2487 Instead the driver has to do some padding and send an extra byte,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2488 and the host has to be prepared to receive this extra byte. Such a
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2489 driver should specify a value of <literal>1</literal> for the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2490 padding field. For most drivers this field should be set to
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2491 <literal>0</literal>.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2492 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2493 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2494 A better solution would be for the device driver to supply a
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2495 fragment of Tcl code that would adjust the receive buffer size
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2496 only when necessary, rather than for every transfer. Forcing
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2497 receive padding on all transfers when only certain transfers
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2498 will actually be padded reduces the accuracy of certain tests.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2499 </para></listitem>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2500 </varlistentry>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2501 <varlistentry>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2502 <term><structfield>alignment</structfield></term>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2503 <listitem><para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2504 On some hardware data transfers may need to be aligned to certain
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2505 boundaries, for example a word boundary or a cacheline boundary.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2506 Although in theory device drivers could hide such alignment
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2507 restrictions from higher-level code by having their own buffers and
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2508 performing appropriate copying, that would be expensive in terms of
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2509 both memory and cpu cycles. Instead the generic testing code will
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2510 align any buffers passed to the device driver to the specified
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2511 boundary. For example, if the driver requires that buffers be
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2512 aligned to a word boundary then it should specify an alignment
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2513 value of 4.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2514 </para></listitem>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2515 </varlistentry>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2516 </variablelist>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2517
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2518 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2519 The device driver should provide an array of these structures
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2520 <varname>usbs_testing_endpoints[]</varname>. The USB testing code
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2521 examines this array and uses the information to perform appropriate
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2522 tests. Because different USB devices support different numbers of
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2523 endpoints the number of entries in the array is not known in advance,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2524 so instead the testing code looks for a special terminator
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2525 <varname>USBS_TESTING_ENDPOINTS_TERMINATOR</varname>. An example
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2526 array, showing just the control endpoint and the terminator, might
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2527 look like this:
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2528 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2529 <programlisting width=72>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2530 usbs_testing_endpoint usbs_testing_endpoints[] = {
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2531 {
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2532 endpoint_type : USB_ENDPOINT_DESCRIPTOR_ATTR_CONTROL,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2533 endpoint_number : 0,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2534 endpoint_direction : USB_ENDPOINT_DESCRIPTOR_ENDPOINT_IN,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2535 endpoint : (void*) &amp;ep0.common,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2536 devtab_entry : (const char*) 0,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2537 min_size : 1,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2538 max_size : 0x0FFFF,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2539 max_in_padding : 0,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2540 alignment : 0
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2541 },
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2542 &hellip;,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2543 USBS_TESTING_ENDPOINTS_TERMINATOR
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2544 };
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2545 </programlisting>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2546
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2547 <note>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2548 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2549 The use of a single array <varname>usbs_testing_endpoints</varname>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2550 limits USB testing to platforms with a single USB device: if there
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2551 were multiple devices, each defining their own instance of this array,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2552 then there would a collision at link time. In practice this should not
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2553 be a major problem since typical USB peripherals only interact with a
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2554 single host machine via a single slave port. In addition, even if a
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2555 peripheral did have multiple slave ports the current USB testing code
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2556 would not support this since it would not know which port to use.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2557 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2558 </note>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2559
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2560 </refsect1>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2561
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2562 </refentry>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2563
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2564 <!-- }}} -->
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2565 <!-- {{{ USB Testing support -->
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2566
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2567 <refentry id="usbs-testing">
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2568 <refmeta>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2569 <refentrytitle>Testing</refentrytitle>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2570 </refmeta>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2571 <refnamediv>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2572 <refname>Testing</refname>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2573 <refpurpose>Testing of USB Device Drivers</refpurpose>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2574 </refnamediv>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2575
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2576 <refsect1><title>Introduction</title>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2577 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2578 The support for USB testing provided by the eCos USB common slave
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2579 package is somewhat different in nature from the kind of testing used
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2580 in many other packages. One obvious problem is that USB tests cannot
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2581 be run on just a bare target platform: instead the target platform
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2582 must be connected to a suitable USB host machine, and that host
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2583 machine must be running appropriate software for the test code to
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2584 interact with. This is very different from say a kernel test which
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2585 typically will have no external dependencies. Another important
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2586 difference between USB testing and say a C library
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2587 <function>strcmp</function> test is sensitivity to timing and to
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2588 hardware boundary conditions: although a simple test case that just
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2589 performs a small number of USB transfers is better than no testing at
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2590 all, it should also be possible to run tests for hours or days on end,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2591 under a variety of loads. In order to provide the required
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2592 functionality the basic architecture of the USB testing support is as
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2593 follows:
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2594 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2595 <orderedlist>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2596 <listitem><para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2597 There is a single target-side program
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2598 <application>usbtarget</application>. By default when this is run
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2599 on a target platform it will appear to do nothing. In fact it is
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2600 waiting to be contacted by another program
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2601 <application>usbhost</application> which will tell it what test or
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2602 tests to run. <application>usbtarget</application> provides
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2603 mechanisms for running a wide range of tests.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2604 </para></listitem>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2605 <listitem><para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2606 <application>usbtarget</application> is a generic program, but USB
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2607 testing depends to some extent on the functionality provided by the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2608 hardware. For example there is no point in testing bulk transmits
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2609 to endpoint 12 if the target hardware does not support an endpoint
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2610 12. Therefore each USB device driver should supply information about
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2611 what the hardware is actually capable of, in the form of an array of
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2612 <structname>usbs_testing_endpoint</structname> data structures.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2613 </para></listitem>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2614 <listitem><para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2615 There is a single host-side program
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2616 <application>usbhost</application>, which acts as a counterpart to
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2617 <application>usbtarget</application>. Again
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2618 <application>usbhost</application> has no built-in knowledge of
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2619 the test or tests that are supposed to run, it only provides
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2620 mechanisms for running a wide range of tests. On start-up
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2621 <application>usbhost</application> will search the USB bus for
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2622 hardware running the target-side program, specifically a USB device
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2623 that identifies itself as the product <literal>&quot;Red Hat eCos
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2624 USB test&quot;</literal>.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2625 </para></listitem>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2626 <listitem><para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2627 <application>usbhost</application> contains a Tcl interpreter, and
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2628 will execute any Tcl scripts specified on the command line
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2629 together with appropriate arguments. The Tcl interpreter has been
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2630 extended with various commands such as
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2631 <literal>usbtest::bulktest</literal>, so the script can perform
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2632 the desired test or tests.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2633 </para></listitem>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2634 <listitem><para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2635 Adding a new test simply involves writing a short Tcl script that
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2636 invokes the appropriate USB-specific commands. Running multiple
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2637 tests involves passing appropriate arguments to
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2638 <application>usbhost</application>, or alternatively writing a
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2639 single script that just invokes other scripts.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2640 </para></listitem>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2641 </orderedlist>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2642 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2643 The current implementation of <application>usbhost</application>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2644 depends heavily on functionality provided by the Linux kernel and in
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2645 particular the usbdevfs support. It uses
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2646 <filename>/proc/bus/usb/devices</filename> to find out what devices
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2647 are attached to the bus, and will then access the device by opening
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2648 <filename>/proc/bus/usb/xxx/yyy</filename> and performing
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2649 <function>ioctl</function> operations. This allows USB testing to take
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2650 place without having to write a new host-side device driver, but
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2651 getting the code working on host machines not running Linux would
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2652 obviously be problematical.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2653 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2654 </refsect1>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2655
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2656 <refsect1><title>Building and Running the Target-side Code</title>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2657 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2658 The target-side component of the USB testing software consists of a
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2659 single program <application>usbtarget</application> which contains
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2660 support for a range of different tests, under the control of host-side
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2661 software. This program is not built by default alongside other eCos
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2662 test cases since it will only operate in certain environments,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2663 specifically when the target board's connector is plugged into a Linux
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2664 host, and when the appropriate host-side software has been installed
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2665 on that host. Instead the user must enable a configuration option
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2666 <literal>CYGBLD_IO_USB_SLAVE_USBTEST</literal> to add the program to
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2667 the list of tests for the current configuration.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2668 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2669 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2670 Starting the <application>usbtarget</application> program does not
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2671 require anything unusual, so it can be run in a normal
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2672 <application>gdb</application> session just like any eCos application.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2673 After initialization the program will wait for activity from the host.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2674 Depending on the hardware, the Linux host will detect that a new USB
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2675 peripheral is present on the bus either when the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2676 <application>usbtarget</application> initialization is complete or
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2677 when the cable between target and host is connected. The host will
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2678 perform the normal USB enumeration sequence and discover that the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2679 peripheral does not match any known vendor or product id and that
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2680 there is no device driver for <literal>&quot;Red Hat eCos USB
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2681 test&quot;</literal>, so it will ignore the peripheral. When the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2682 <application>usbhost</application> program is run on the host it will
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2683 connect to the target-side software, and testing can now commence.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2684 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2685 </refsect1>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2686
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2687 <refsect1><title>Building and Running the Host-side Code</title>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2688 <note><para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2689 In theory the host-side software should be built when the package is
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2690 installed in the component repository, and removed when a package
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2691 is uninstalled. The current eCos administration tool does not provide
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2692 this functionality.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2693 </para></note>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2694 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2695 The host-side software should be built via the usual sequence of
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2696 &quot;configure/make/make install&quot;. It can only be built on a
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2697 Linux host and the <command>configure</command> script contains an
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2698 explicit test for this. Because the eCos component repository should
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2699 generally be treated as a read-only resource the configure script will
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2700 also prevent you from trying to build inside the source tree. Instead
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2701 a separate build tree is required. Hence a typical sequence for
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2702 building the host-side software would be as follows:
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2703 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2704 <screen>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2705 $ mkdir usbhost_build
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2706 $ cd usbhost_build
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2707 $ &lt;repo&gt;packages/io/usb/slave/current/host/configure <co id="path"> <co id="version"> &lt;args&gt; <co id="args">
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2708 $ make
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2709 &lt;output from make&gt;
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2710 $ su <co id="root">
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2711 $ make install
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2712 &lt;output from make install&gt;
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2713 $
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2714 </screen>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2715 <calloutlist>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2716 <callout arearefs="path">
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2717 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2718 The location of the eCos component repository should be substituted
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2719 for <literal>&lt;repo&gt;</literal>.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2720 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2721 </callout>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2722 <callout arearefs="version">
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2723 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2724 If the package has been obtained via CVS or anonymous CVS then the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2725 package version will be <filename>current</filename>, as per the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2726 example. If instead the package has been obtained as part of a full
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2727 eCos release or as a separate <filename>.epk</filename> file then the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2728 appropriate package version should be used instead of
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2729 <filename>current</filename>.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2730 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2731 </callout>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2732 <callout arearefs="args">
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2733 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2734 The <command>configure</command> script takes the usual arguments such
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2735 as <parameter>--prefix=</parameter> to specify where the executables
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2736 and support files should be installed. The only other parameter that
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2737 some users may wish to specify is the location of a suitable Tcl
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2738 installation. By default <application>usbhost</application> will use
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2739 the existing Tcl installation in <filename class="directory">/usr</filename>,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2740 as provided by your Linux distribution. An alternative Tcl
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2741 installation can be specified using the parameter
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2742 <parameter>--with-tcl=</parameter>, or alternatively using some
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2743 combination of <parameter>--with-tcl-include</parameter>,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2744 <parameter>--with-tcl-lib</parameter> and
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2745 <parameter>--with-tcl-version</parameter>.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2746 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2747 </callout>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2748 <callout arearefs="root">
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2749 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2750 One of the host-side executables that gets built,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2751 <application>usbchmod</application>, needs to be installed with suid
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2752 root privileges. Although the Linux kernel makes it possible for
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2753 applications to perform low-level USB operations such as transmitting
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2754 bulk packets, by default access to this functionality is restricted to
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2755 programs with superuser privileges. It is undesirable to run a complex
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2756 program such as <application>usbhost</application> with such
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2757 privileges, especially since the program contains a general-purpose
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2758 Tcl interpreter. Therefore when <application>usbhost</application>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2759 starts up and discovers that it does not have sufficient access to the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2760 appropriate entries in <filename class="directory">/proc/bus/usb</filename>,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2761 it spawns an instance of <application>usbchmod</application> to modify
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2762 the permissions on these entries. <application>usbchmod</application>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2763 will only do this for a USB device <literal>&quot;Red Hat eCos USB
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2764 test&quot;</literal>, so installing this program suid root should not
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2765 introduce any security problems.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2766 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2767 </callout>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2768 </calloutlist>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2769
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2770 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2771 During <command>make install</command> the following actions will take
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2772 place:
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2773 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2774 <orderedlist>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2775 <listitem>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2776 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2777 <application>usbhost</application> will be installed in <filename class="directory">/usr/local/bin</filename>,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2778 or some other <filename class="directory">bin</filename> directory if
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2779 the default location is changed at configure-time using a
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2780 <parameter>--prefix=</parameter> or similar option. It will be
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2781 installed as the executable
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2782 <application>usbhost_&lt;version&gt;</application>, for example
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2783 <application>usbhost_current</application>, thus allowing several
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2784 releases of the USB slave package to co-exist. For convenience a
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2785 symbolic link from <filename>usbhost</filename> to this executable
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2786 will be created, so users can just run <command>usbhost</command> to
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2787 access the most recently-installed version.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2788 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2789 </listitem>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2790 <listitem>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2791 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2792 <application>usbchmod</application> will be installed in
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2793 <filename class="directory">/usr/local/libexec/ecos/io_usb_slave_&lt;version&gt;</filename>.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2794 This program should only be run by <application>usbhost</application>,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2795 not invoked directly, so it is not placed in the <filename class="directory">bin</filename>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2796 directory. Again the presence of the package version in the directory
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2797 name allows multiple releases of the package to co-exist.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2798 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2799 </listitem>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2800 <listitem>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2801 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2802 A Tcl script <filename>usbhost.tcl</filename> will get installed in
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2803 the same directory as <application>usbchmod</application>. This Tcl
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2804 script is loaded automatically by the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2805 <application>usbhost</application> executable.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2806 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2807 </listitem>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2808 <listitem>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2809 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2810 A number of additional Tcl scripts, for example
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2811 <filename>list.tcl</filename> will get installed alongside
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2812 <filename>usbhost.tcl</filename>. These correspond to various test
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2813 cases provided as standard. If a given test case is specified on the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2814 command line and cannot be found relative to the current directory
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2815 then <application>usbhost</application> will search the install
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2816 directory for these test cases.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2817 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2818 <note><para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2819 Strictly speaking installing the <filename>usbhost.tcl</filename> and
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2820 other Tcl scripts below the <filename class="directory">libexec</filename>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2821 directory deviates from standard practice: they are
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2822 architecture-independent data files so should be installed below
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2823 the <filename class="directory">share</filename> subdirectory. In
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2824 practice the files are sufficiently small that there is no point in
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2825 sharing them, and keeping them below <filename class="directory">libexec</filename>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2826 simplifies the host-side software somewhat.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2827 </para></note>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2828 </listitem>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2829 </orderedlist>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2830
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2831 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2832 The <command>usbhost</command> should be run only when there is a
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2833 suitable target attached to the USB bus and running the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2834 <application>usbtarget</application> program. It will search
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2835 <filename>/proc/bus/usb/devices</filename> for an entry corresponding
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2836 to this program, invoke <application>usbchmod</application> if
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2837 necessary to change the access rights, and then interact with
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2838 <application>usbtarget</application> over the USB bus.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2839 <command>usbhost</command> should be invoked as follows:
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2840 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2841 <screen>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2842 $ usbhost [-v|--version] [-h|--help] [-V|--verbose] &lt;test&gt; [&lt;test parameters&gt;]
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2843 </screen>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2844 <orderedlist>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2845 <listitem>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2846 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2847 The <parameter>-v</parameter> or <parameter>--version</parameter>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2848 option will display version information for
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2849 <application>usbhost</application> including the version of the USB
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2850 slave package that was used to build the executable.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2851 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2852 </listitem>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2853 <listitem>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2854 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2855 The <parameter>-h</parameter> or <parameter>--help</parameter> option
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2856 will display usage information.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2857 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2858 </listitem>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2859 <listitem>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2860 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2861 The <parameter>-V</parameter> or <parameter>--verbose</parameter>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2862 option can be used to obtain more information at run-time, for example
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2863 some output for every USB transfer. This option can be repeated
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2864 multiple times to increase the amount of output.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2865 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2866 </listitem>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2867 <listitem>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2868 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2869 The first argument that does not begin with a hyphen specifies a test
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2870 that should be run, in the form of a Tcl script. For example an
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2871 argument of <parameter>list.tcl</parameter> will cause
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2872 <application>usbhost</application> to look for a script with that
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2873 name, adding a <filename>.tcl</filename> suffix if necessarary, and
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2874 run that script. <application>usbhost</application> will look in the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2875 current directory first, then in the install tree for standard test
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2876 scripts provided by the USB slave package.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2877 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2878 </listitem>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2879 <listitem>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2880 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2881 Some test scripts may want their own parameters, for example a
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2882 duration in seconds. These can be passed on the command line after
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2883 the name of the test, for example
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2884 <command>usbhost&nbsp;mytest&nbsp;60</command>.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2885 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2886 </listitem>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2887 </orderedlist>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2888 </refsect1>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2889
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2890 <refsect1><title>Writing a Test</title>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2891 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2892 Each test is defined by a Tcl script, running inside an interpreter
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2893 provided by <application>usbhost</application>. In addition to the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2894 normal Tcl functionality this interpreter provides a number of
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2895 variables and functions related to USB testing. For example there is a
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2896 variable <varname>bulk_in_endpoints</varname> that lists all the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2897 endpoints on the target that can perform bulk IN operations, and a
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2898 related array <varname>bulk_in</varname> which contains information
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2899 such as the minimum and maximum packets sizes. There is a function
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2900 <function>bulktest</function> which can be used to perform bulk tests
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2901 on a particular endpoint. A simple test script aimed at specific
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2902 hardware could ignore the information variables since it would know
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2903 exactly what USB hardware is available on the target, whereas a
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2904 general-purpose script would use the information to adapt to the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2905 hardware capabilities.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2906 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2907 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2908 To avoid namespace pollution all USB-related Tcl variables and
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2909 functions live in the <varname>usbtest::</varname> namespace.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2910 Therefore accessing requires either explicitly including the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2911 namespace any references, for example
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2912 <literal>$usbtest::bulk_in_endpoints</literal>, or by using Tcl's
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2913 <function>namespace import</function> facility.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2914 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2915 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2916 A very simple test script might look like this:
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2917 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2918 <programlisting width=72>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2919 usbtest::bulktest 1 out 4000
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2920 usbtest::bulktest 2 in 4000
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2921 if { [usbtest::start 60] } {
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2922 puts "Test successful"
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2923 } else
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2924 puts "Test failed"
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2925 foreach result $usbtest::results {
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2926 puts $result
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2927 }
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2928 }
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2929 </programlisting>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2930 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2931 This would perform a test run involving 4000 bulk transfers from the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2932 host to the target's endpoint 1, and concurrently 4000 bulk transfers
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2933 from endpoint 2. Default settings for packet sizes, contents, and
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2934 delays would be used. The actual test would not start running until
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2935 <filename>usbtest</filename> is invoked, and it is expected that the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2936 test would complete within 60 seconds. If any failures occur then they
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2937 are reported.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2938 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2939 </refsect1>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2940
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2941 <refsect1><title>Available Hardware</title>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2942 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2943 Each target-side USB device driver provides information about the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2944 actual capabilities of the hardware, for example which endpoints are
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2945 available. Strictly speaking it provides information about what is
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2946 actually supported by the device driver, which may be a subset of what
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2947 the hardware is capable of. For example, the hardware may support
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2948 isochronous transfers on a particular endpoint but if there is no
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2949 software support for this in the driver then this endpoint will not be
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2950 listed. When <application>usbhost</application> first contacts the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2951 <application>usbtarget</application> program running on the target
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2952 platform, it obtains this information and makes it available to test
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2953 scripts via Tcl variables:
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2954 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2955 <variablelist>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2956 <varlistentry>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2957 <term><varname>bulk_in_endpoints</varname></term>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2958 <listitem><para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2959 This is a simple list of the endpoints which can support bulk IN
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2960 transfers. For example if the target-side hardware supports
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2961 these transfers on endpoints 3 and 5 then the value would be
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2962 <literal>&quot;3 5&quot;</literal> Typical test scripts would
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2963 iterate over the list using something like:
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2964 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2965 <programlisting width=72>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2966 if { 0 != [llength $usbtest::bulk_in_endpoints] } {
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2967 puts"Bulk IN endpoints: $usbtest::bulk_in_endpoints"
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2968 foreach endpoint $usbtest:bulk_in_endpoints {
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2969 &hellip;
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2970 }
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2971 }
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2972 </programlisting>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2973 </listitem>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2974 </varlistentry>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2975 <varlistentry>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2976 <term><varname>bulk_in()</varname></term>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2977 <listitem><para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2978 This array holds additional information about each bulk IN endpoint.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2979 The array is indexed by two fields, the endpoint number and one of
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2980 <literal>min_size</literal>, <literal>max_size</literal>,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2981 <literal>max_in_padding</literal> and <literal>devtab</literal>:
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2982 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2983 <variablelist>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2984 <varlistentry>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2985 <term><literal>min_size</literal></term>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2986 <listitem><para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2987 This field specifies a lower bound on the size of bulk transfers,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2988 and will typically will have a value of 1.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2989 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2990 <note><para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2991 The typical minimum transfer size of a single byte is not strictly
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2992 speaking correct, since under some circumstances it can make sense
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2993 to have a transfer size of zero bytes. However current target-side
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2994 device drivers interpret a request to transfer zero bytes as a way
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2995 for higher-level code to determine whether or not an endpoint is
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2996 stalled, so it is not actually possible to perform zero-byte
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2997 transfers. This issue will be addressed at some future point.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2998 </para></note>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
2999 </listitem>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3000 </varlistentry>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3001 <varlistentry>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3002 <term><literal>max_size</literal></term>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3003 <listitem><para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3004 This field specifies an upper bound on the size of bulk transfers.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3005 Some target-side drivers may be limited to transfers of say
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3006 0x0FFFF bytes because of hardware limitations. In practice the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3007 transfer size is likely to be limited primarily to limit memory
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3008 consumption of the test code on the target hardware, and to ensure
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3009 that tests complete reasonably quickly. At the time of writing
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3010 transfers are limited to 4K.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3011 </para></listitem>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3012 </varlistentry>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3013 <varlistentry>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3014 <term><literal>max_in_padding</literal></term>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3015 <listitem><para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3016 On some hardware it may be necessary for the target-side device
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3017 driver to send more data than is actually intended. For example
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3018 the SA11x0 USB hardware cannot perform bulk transfers that are
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3019 an exact multiple of 64 bytes, instead it must pad such
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3020 transfers with an extra byte and the host must be ready to
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3021 accept and discard this byte. The
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3022 <literal>max_in_padding</literal> field indicates the amount of
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3023 padding that is required. The low-level code inside
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3024 <application>usbhost</application> will use this field
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3025 automatically, and there is no need for test scripts to adjust
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3026 packet sizes for padding. The field is provided for
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3027 informational purposes only.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3028 </para></listitem>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3029 </varlistentry>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3030 <varlistentry>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3031 <term><literal>devtab</literal></term>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3032 <listitem><para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3033 This is a string indicating whether or not the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3034 target-side USB device driver supports access to this endpoint
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3035 via entries in the device table, in other words through
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3036 conventional calls like <function>open</function> and
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3037 <function>write</function>. Some device drivers may only
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3038 support low-level USB access because typically that is what gets
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3039 used by USB class-specific packages such as USB-ethernet.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3040 An empty string indicates that no devtab entry is available,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3041 otherwise it will be something like
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3042 <literal>&quot;/dev/usbs2w&quot;</literal>.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3043 </para></listitem>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3044 </varlistentry>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3045 </variablelist>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3046 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3047 Typical test scripts would access this data using something like:
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3048 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3049 <programlisting width=72>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3050 foreach endpoint $usbtest:bulk_in_endpoints {
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3051 puts "Endpoint $endpoint: "
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3052 puts " minimum transfer size $usbtest::bulk_in($endpoint,min_size)"
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3053 puts " maximum transfer size $usbtest::bulk_in($endpoint,max_size)"
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3054 if { 0 == $usbtest::bulk_in($endpoint,max_in_padding) } {
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3055 puts " no IN padding required"
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3056 } else {
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3057 puts " $usbtest::bulk_in($endpoint,max_in_padding) bytes of IN padding required"
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3058 }
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3059 if { "" == $usbtest::bulk_in($endpoint,devtab) } {
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3060 puts " no devtab entry provided"
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3061 } else {
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3062 puts " corresponding devtab entry is $usbtest::bulk_in($endpoint,devtab)"
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3063 }
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3064 }
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3065 </programlisting>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3066 </listitem>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3067 </varlistentry>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3068 <varlistentry>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3069 <term><varname>bulk_out_endpoint</varname></term>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3070 <listitem><para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3071 This is a simple list of the endpoints which can support bulk OUT
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3072 transfers. It is analogous to
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3073 <varname>bulk_in_endpoints</varname>.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3074 </para></listitem>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3075 </varlistentry>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3076 <varlistentry>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3077 <term><varname>bulk_out()</varname></term>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3078 <listitem><para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3079 This array holds additional information about each bulk OUT
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3080 endpoint. It can be accessed in the same way as
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3081 <varname>bulk_in()</varname>, except that there is no
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3082 <literal>max_in_padding</literal> field because that field only
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3083 makes sense for IN transfers.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3084 </para></listitem>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3085 </varlistentry>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3086 <varlistentry>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3087 <term><varname>control()</varname></term>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3088 <listitem><para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3089 This array holds information about the control endpoint. It contains
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3090 two fields, <literal>min_size</literal> and
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3091 <literal>max_size</literal>. Note that there is no variable
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3092 <varname>control_endpoints</varname> because a USB target always
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3093 supports a single control endpoint <literal>0</literal>. Similarly
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3094 the <varname>control</varname> array does not use an endpoint number
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3095 as the first index because that would be redundant.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3096 </para></listitem>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3097 </varlistentry>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3098 <varlistentry>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3099 <term><varname>isochronous_in_endpoints</varname> and
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3100 <varname>isochronous_in()</varname></term>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3101 <listitem><para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3102 These variables provide the same information as
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3103 <varname>bulk_in_endpoints</varname> and <varname>bulk_in</varname>,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3104 but for endpoints that support isochronous IN transfers.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3105 </para></listitem>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3106 </varlistentry>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3107 <varlistentry>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3108 <term><varname>isochronous_out_endpoints</varname> and
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3109 <varname>isochronous_out()</varname></term>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3110 <listitem><para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3111 These variables provide the same information as
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3112 <varname>bulk_out_endpoints</varname> and <varname>bulk_out</varname>,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3113 but for endpoints that support isochronous OUT transfers.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3114 </para></listitem>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3115 </varlistentry>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3116 <varlistentry>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3117 <term><varname>interrupt_in_endpoints</varname> and
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3118 <varname>interrupt_in()</varname></term>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3119 <listitem><para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3120 These variables provide the same information as
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3121 <varname>bulk_in_endpoints</varname> and <varname>bulk_in</varname>,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3122 but for endpoints that support interrupt IN transfers.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3123 </para></listitem>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3124 </varlistentry>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3125 <varlistentry>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3126 <term><varname>interrupt_out_endpoints</varname> and
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3127 <varname>interrupt_out()</varname></term>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3128 <listitem><para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3129 These variables provide the same information as
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3130 <varname>bulk_out_endpoints</varname> and <varname>bulk_out</varname>,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3131 but for endpoints that support interrupt OUT transfers.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3132 </para></listitem>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3133 </varlistentry>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3134 </variablelist>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3135 </refsect1>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3136
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3137
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3138 <refsect1><title>Testing Bulk Transfers</title>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3139 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3140 The main function for initiating a bulk test is
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3141 <function>usbtest::bulktest</function>. This takes three compulsory
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3142 arguments, and can be given a number of additional arguments to
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3143 control the exact behaviour. The compulsory arguments are:
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3144 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3145 <variablelist>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3146 <varlistentry>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3147 <term>endpoint</term>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3148 <listitem><para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3149 This specifies the endpoint to use. It should correspond to
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3150 one of the entries in
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3151 <varname>usbtest::bulk_in_endpoints</varname> or
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3152 <varname>usbtest::bulk_out_endpoints</varname>, depending on the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3153 transfer direction.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3154 </para></listitem>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3155 </varlistentry>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3156 <varlistentry>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3157 <term>direction</term>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3158 <listitem><para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3159 This should be either <literal>in</literal> or <literal>out</literal>.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3160 </para></listitem>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3161 </varlistentry>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3162 <varlistentry>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3163 <term>number of transfers</term>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3164 <listitem><para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3165 This specifies the number of transfers that should take place. The
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3166 testing software does not currently support the concept of performing
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3167 transfers for a given period of time because synchronising this on
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3168 both the host and a wide range of targets is difficult. However it
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3169 is relatively easy to work out the approximate time a number of bulk
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3170 transfers should take place, based on a typical bandwidth of
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3171 1MB/second and assuming say a 1ms overhead per transfer.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3172 Alternatively a test script could perform a small initial run to
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3173 determine what performance can actually be expected from a given
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3174 target, and then use this information to run a much longer test.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3175 </para></listitem>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3176 </varlistentry>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3177 </variablelist>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3178 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3179 Additional arguments can be used to control the exact transfer. For
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3180 example a <parameter>txdelay+</parameter> argument can be used to
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3181 slowly increase the delay between transfers. All such arguments involve
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3182 a value which can be passed either as part of the argument itself,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3183 for example <literal>txdelay+=5</literal>, or as a subsequent
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3184 argument, <literal>txdelay+ 5</literal>. The possible arguments fall
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3185 into a number of categories: data, I/O mechanism, transmit size,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3186 receive size, transmit delay, and receive delay.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3187 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3188
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3189 <refsect2><title>Data</title>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3190 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3191 An obvious parameter to control is the actual data that gets sent.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3192 This can be controlled by the argument <parameter>data</parameter>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3193 which can take one of five values: <literal>none</literal>,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3194 <literal>bytefill</literal>, <literal>intfill</literal>,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3195 <literal>byteseq</literal> and <literal>wordseq</literal>. The default
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3196 value is <literal>none</literal>.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3197 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3198 <variablelist>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3199 <varlistentry>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3200 <term><literal>none</literal></term>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3201 <listitem><para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3202 The transmit code will not attempt to fill the buffer in any way,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3203 and the receive code will not check it. The actual data that gets
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3204 transferred will be whatever happened to be in the buffer before
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3205 the transfer started.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3206 </para></listitem>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3207 </varlistentry>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3208 <varlistentry>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3209 <term><literal>bytefill</literal></term>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3210 <listitem><para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3211 The entire buffer will be filled with a single byte, as per
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3212 <function>memset</function>.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3213 </para></listitem>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3214 </varlistentry>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3215 <varlistentry>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3216 <term><literal>intfill</literal></term>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3217 <listitem><para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3218 The buffer will be treated as an array of 32-bit integers, and will
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3219 be filled with the same integer repeated the appropriate number of
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3220 times. If the buffer size is not a multiple of four bytes then
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3221 the last few bytes will be set to 0.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3222 </para></listitem>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3223 </varlistentry>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3224 <varlistentry>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3225 <term><literal>byteseq</literal></term>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3226 <listitem><para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3227 The buffer will be filled with a sequence of bytes, generated by
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3228 a linear congruential generator. If the first byte in the buffer is
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3229 filled with the value <literal>x</literal>, the next byte will be
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3230 <literal>(m*x)+i</literal>. For example a sequence of slowly
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3231 incrementing bytes can be achieved by setting both the multiplier
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3232 and the increment to 1. Alternatively a pseudo-random number
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3233 sequence can be achieved using values 1103515245 and 12345, as
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3234 per the standard C library <function>rand</function> function.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3235 For convenience these two constants are available as Tcl
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3236 variables <varname>usbtest::MULTIPLIER</varname> and
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3237 <varname>usbtest::INCREMENT</varname>.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3238 </para></listitem>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3239 </varlistentry>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3240 <varlistentry>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3241 <term><literal>wordseq</literal></term>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3242 <listitem><para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3243 This acts like <literal>byteseq</literal>, except that the buffer is
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3244 treated as an array of 32-bit integers rather than as an array of
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3245 bytes. If the buffer is not a multiple of four bytes then the last
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3246 few bytes will be filled with zeroes.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3247 </para></listitem>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3248 </varlistentry>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3249 </variablelist>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3250 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3251 The above requires three additional parameters
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3252 <parameter>data1</parameter>, <parameter>data*</parameter> and
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3253 <parameter>data+</parameter>. <parameter>data1</parameter> specifies
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3254 the value to be used for byte or word fills, or the first number when
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3255 calculating a sequence. The default value is <literal>0</literal>.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3256 <parameter>data*</parameter> and <parameter>data+</parameter> specify
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3257 the multiplier and increment for a sequence, and have default values
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3258 of <literal>1</literal> and <literal>0</literal> respectively. For
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3259 example, to perform a bulk transfer of a pseudo-random sequence of
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3260 integers starting with 42 the following code could be used:
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3261 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3262 <programlisting width=72>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3263 bulktest 2 IN 1000 data=wordseq data1=42 \
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3264 data* $usbtest::MULTIPLIER data+ $usbtest::INCREMENT
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3265 </programlisting>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3266 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3267 The above parameters define what data gets transferred for the first
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3268 transfer, but a test can involve multiple transfers. The data format
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3269 will be the same for all transfers, but it is possible to adjust the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3270 current value, the multiplier, and the increment between each
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3271 transfer. This is achieved with parameters <parameter>data1*</parameter>,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3272 <parameter>data1+</parameter>, <parameter>data**</parameter>,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3273 <parameter>data*+</parameter>, <parameter>data+*</parameter>, and
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3274 <parameter>data++</parameter>, with default values of 1 for each
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3275 multiplier and 0 for each increment. For example, if the multiplier
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3276 for the first transfer is set to <literal>2</literal> using
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3277 <parameter>data*</parameter>, and arguments
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3278 <literal>data**&nbsp;2</literal> and <literal>data*+&nbsp;-1</literal> are also
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3279 supplied, then the multiplier for subsequent transfers will be
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3280 <literal>3</literal>, <literal>5</literal>, <literal>9</literal>,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3281 &hellip;.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3282 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3283
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3284 <note><para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3285 Currently it is not possible for a test script to send specific data,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3286 for example a specific sequence of bytes captured by a protocol analyser
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3287 that caused a problem. If the transfer was from host to target then
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3288 the target would have to know the exact sequence of bytes to expect,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3289 which means transferring data over the USB bus when that data is known
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3290 to have caused problems in the past. Similarly for target to host
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3291 transfers the target would have to know what bytes to send. A possible
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3292 future extension of the USB testing support would allow for bounce
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3293 operations, where a given message is first sent to the target and then
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3294 sent back to the host, with only the host checking that the data was
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3295 returned correctly.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3296 </para></note>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3297 </refsect2>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3298
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3299 <refsect2><title>I/O Mechanism</title>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3300 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3301 On the target side USB transfers can happen using either low-level
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3302 USB calls such as <function>usbs_start_rx_buffer</function>, or by
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3303 higher-level calls which go through the device table. By default the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3304 target-side code will use the low-level calls. If it is desired to
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3305 test the higher-level calls instead, for example because those are
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3306 what the application uses, then that can be achieved with an
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3307 argument <parameter>mechanism=devtab</parameter>.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3308 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3309 </refsect2>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3310
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3311 <refsect2><title>Transmit Size</title>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3312 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3313 The next set of arguments can be used to control the size of the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3314 transmitted buffer: <parameter>txsize1</parameter>,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3315 <parameter>txsize&gt;=</parameter>, <parameter>txsize&lt;=</parameter>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3316 <parameter>txsize*</parameter>, <parameter>txsize/</parameter>,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3317 and <parameter>txsize+</parameter>.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3318 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3319 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3320 <parameter>txsize1</parameter> determines the size of the first
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3321 transfer, and has a default value of 32 bytes. The size of the next
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3322 transfer is calculated by first multiplying by the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3323 <parameter>txsize*</parameter> value, then dividing by the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3324 <parameter>txsize/</parameter> value, and finally adding the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3325 <parameter>txsize+</parameter> value. The defaults for these are
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3326 <literal>1</literal>, <literal>1</literal>, and <literal>0</literal>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3327 respectively, which means that the transfer size will remain
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3328 unchanged. If for example the transfer size should increase by
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3329 approximately 50 per cent each time then suitable values might be
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3330 <literal>txsize*&nbsp;3</literal>, <literal>txsize/&nbsp;2</literal>,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3331 and <literal>txsize+&nbsp;1</literal>.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3332 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3333 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3334 The <parameter>txsize&gt;=</parameter> and
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3335 <parameter>txsize&lt;=</parameter> arguments can be used to impose
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3336 lower and upper bounds on the transfer. By default the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3337 <literal>min_size</literal> and <literal>max_size</literal> values
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3338 appropriate for the endpoint will be used. If at any time the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3339 current size falls outside the bounds then it will be normalized.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3340 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3341 </refsect2>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3342
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3343 <refsect2><title>Receive Size</title>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3344 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3345 The receive size, in other words the number of bytes that either host
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3346 or target will expect to receive as opposed to the number of bytes
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3347 that actually get sent, can be adjusted using a similar set of
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3348 arguments: <parameter>rxsize1</parameter>,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3349 <parameter>rxsize&gt;=</parameter>,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3350 <parameter>rxsize&lt;=</parameter>,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3351 <parameter>rxsize*</parameter>, <parameter>rxsize/</parameter> and
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3352 <parameter>rxsize+</parameter>. The current receive size will be
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3353 adjusted between transfers just like the transmit size. However when
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3354 communicating over USB it is not a good idea to attempt to receive
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3355 less data than will actually be sent: typically neither the hardware
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3356 nor the software will be able to do anything useful with the excess,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3357 so there will be problems. Therefore if at any time the calculated
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3358 receive size is less than the transmit size, the actual receive will
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3359 be for the exact number of bytes that will get transmitted. However
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3360 this will not affect the calculations for the next receive size.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3361 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3362 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3363 The default values for <parameter>rxsize1</parameter>,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3364 <parameter>rxsize*</parameter>, <parameter>rxsize/</parameter> and
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3365 <parameter>rxsize+</parameter> are <literal>0</literal>,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3366 <literal>1</literal>, <literal>1</literal> and <literal>0</literal>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3367 respectively. This means that the calculated receive size will always
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3368 be less than the transmit size, so the receive operation will be for
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3369 the exact number of bytes transmitted. For some USB protocols this
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3370 would not accurately reflect the traffic that will happen. For example
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3371 with USB-ethernet transfer sizes will vary between 16 and 1516 bytes,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3372 so the receiver will always expect up to 1516 bytes. This can be
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3373 achieved using <literal>rxsize1&nbsp;1516</literal>, leaving the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3374 other parameters at their default values.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3375 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3376 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3377 For target hardware which involves non-zero
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3378 <literal>max_in_padding</literal>, on the host side the padding will
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3379 be added automatically to the receive size if necessary.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3380 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3381 </refsect2>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3382
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3383 <refsect2><title>Transmit and Receive Delays</title>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3384 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3385 Typically during the testing there will be some minor delays between
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3386 transfers on both host and target. Some of these delays will be caused
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3387 by timeslicing, for example another process running on the host, or a
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3388 concurrent test thread running inside the target. Other delays will be
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3389 caused by the USB bus itself, for example activity from another device
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3390 on the bus. However it is desirable that test cases be allowed to
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3391 inject additional and somewhat more controlled delays into the system,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3392 for example to make sure that the target behaves correctly even if the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3393 target is not yet ready to receive data from the host.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3394 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3395 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3396 The transmit delay is controlled by six parameters:
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3397 <parameter>txdelay1</parameter>, <parameter>txdelay*</parameter>,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3398 <parameter>txdelay/</parameter>, <parameter>txdelay+</parameter>,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3399 <parameter>txdelay&gt;=</parameter> and
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3400 <parameter>txdelay&lt;=</parameter>. The default values for these are
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3401 <literal>0</literal>, <literal>1</literal>, <literal>1</literal>,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3402 <literal>0</literal>, <literal>0</literal> and
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3403 <literal>1000000000</literal> respectively, so that by default
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3404 transmits will happen as quickly as possible. Delays are measured in
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3405 nanoseconds, so a value of <literal>1000000</literal> would correspond
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3406 to a delay of 0.001 seconds or one millisecond. By default delays have
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3407 an upper bound of one second. Between transfers the transmit delay is
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3408 updated in much the same was as the transfer sizes.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3409 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3410 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3411 The receive delay is controlled by a similar set of six parameters:
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3412 <parameter>rxdelay1</parameter>, <parameter>rxdelay*</parameter>,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3413 <parameter>rxdelay/</parameter>, <parameter>rxdelay+</parameter>,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3414 <parameter>rxdelay&gt;=</parameter> and
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3415 <parameter>rxdelay&lt;=</parameter>. The default values for these are
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3416 the same as for transmit delays.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3417 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3418 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3419 The transmit delay is used on the side which sends data over the USB
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3420 bus, so for a bulk IN transfer it is the target that sends data and
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3421 hence sleeps for the specified transmit delay, while the host receives
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3422 data sleeps for the receive delay. For an OUT transfer the positions
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3423 are reversed.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3424 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3425 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3426 It should be noted that although the delays are measured in
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3427 nanoseconds, the actual delays will be much less precise and are
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3428 likely to be of the order of milliseconds. The exact details will
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3429 depend on the kernel clock speed.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3430 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3431 </refsect2>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3432
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3433 </refsect1>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3434
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3435 <refsect1><title>Other Types of Transfer</title>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3436 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3437 Support for testing other types of USB traffic such as isochronous
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3438 transfers is not yet implemented.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3439 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3440 </refsect1>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3441
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3442 <refsect1><title>Starting a Test and Collecting Results</title>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3443 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3444 A USB test script should prepare one or more transfers using
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3445 appropriate functions such as <function>usbtest::bulktest</function>.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3446 Once all the individual tests have been prepared they can be started
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3447 by a call to <function>usbtest::start</function>. This takes a single
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3448 argument, a maximum duration measured in seconds. If all transfers
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3449 have not been completed in the specified time then any remaining
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3450 transfers will be aborted.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3451 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3452 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3453 <function>usbtest::start</function> will return <literal>1</literal>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3454 if all the tests have succeeded, or <literal>0</literal> if any of
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3455 them have failed. More detailed reports will be stored in the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3456 Tcl variable <varname>usbtests::results</varname>, which will be a
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3457 list of string messages.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3458 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3459 </refsect1>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3460
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3461 <refsect1><title>Existing Test Scripts</title>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3462 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3463 A number of test scripts are provided as standard. These are located
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3464 in the <filename class="directory">host</filename> subdirectory of the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3465 common USB slave package, and will be installed as part of the process
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3466 of building the host-side software. When a script is specified on the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3467 command line <application>usbhost</application> will first search for
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3468 it in the current directory, then in the install tree. Standard
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3469 test scripts include the following:
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3470 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3471 <variablelist>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3472 <varlistentry><term><filename>list.tcl</filename></term>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3473 <listitem><para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3474 This script simply displays information about the capabilities
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3475 of the target platform, as provided by the target-side USB
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3476 device driver. It can help with tracking down problems, but its
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3477 primary purpose is to let users check that everything is working
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3478 correctly: if running <command>usbhost list.tcl</command>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3479 outputs sensible information then the user knows that the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3480 target side is running correctly and that communication between
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3481 host and target is possible.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3482 </para></listitem>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3483 </varlistentry>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3484 <varlistentry><term><filename>verbose.tcl</filename></term>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3485 <listitem><para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3486 The target-side code can provide information about what
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3487 is happening while tests are prepared and run. This facility
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3488 should not normally be used since the extra I/O involved will
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3489 significantly affect the behaviour of the system, but in some
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3490 circumstances it may prove useful. Since an eCos application
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3491 cannot easily be given command-line arguments the target-side
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3492 verbosity level cannot be controlled using
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3493 <parameter>-V</parameter> or <parameter>--verbose</parameter>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3494 options. Instead it can be controlled from inside
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3495 <application>gdb</application> by changing the integer
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3496 variable <varname>verbose</varname>. Alternatively it can
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3497 be manipulated by running the test script
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3498 <filename>verbose.tcl</filename>. This script takes a single
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3499 argument, the desired verbosity level, which should be a small
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3500 integer. For example, to disable target-side run-time logging
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3501 the command <command>usbhost&nbsp;verbose&nbsp;0</command> can
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3502 be used.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3503 </para></listitem>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3504 </varlistentry>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3505 </variablelist>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3506 </refsect1>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3507
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3508 <refsect1><title>Possible Problems</title>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3509 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3510 If all transfers succeed within the specified time then both host and
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3511 target remain in synch and further tests can be run without problem.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3512 However, if at any time a failure occurs then things get more
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3513 complicated. For example, if the current test involves a series of
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3514 bulk OUT transfers and the target detects that for one of these
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3515 transfers it received less data than was expected then the test has
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3516 failed, and the target will stop accepting data on this endpoint.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3517 However the host-side software may not have detected anything wrong
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3518 and is now blocked trying to send the next lot of data.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3519 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3520 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3521 The test code goes to considerable effort to recover from problems
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3522 such as these. On the host-side separate threads are used for
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3523 concurrent transfers, and on the target-side appropriate asynchronous
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3524 I/O mechanisms are used. In addition there is a control thread on the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3525 host that checks the state of all the main host-side threads, and the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3526 state of the target using private control messages. If it discovers
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3527 that one side has stopped sending or receiving data because of an
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3528 error and the other side is blocked as a result, it will set certain
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3529 flags and then cause one additional transfer to take place. That
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3530 additional transfer will have the effect of unblocking the other side,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3531 which then discovers that an error has occurred by checking the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3532 appropriate flags. In this way both host and target should end up back
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3533 in synch, and it is possible to move on to the next set of tests.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3534 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3535 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3536 However, the above assumes that the testing has not triggered any
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3537 serious hardware conditions. If instead the target-side hardware has
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3538 been left in some strange state so that, for example, it will no
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3539 longer raise an interrupt for traffic on a particular endpoint then
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3540 recovery is not currently possible, and the testing software will just
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3541 hang.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3542 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3543 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3544 A possible future enhancement to the testing software would allow the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3545 host-side to raise a USB reset signal whenever a failure occurs, in
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3546 the hope that this would clear any remaining problems within the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3547 target-side USB hardware.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3548 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3549
151
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
3550 </refsect1>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
3551
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
3552 </refentry>
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
3553
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
3554 <!-- }}} -->
25e238959bae Merge from eCos master repository on 2001-02-12-23:44:24-GMT
jlarmour
parents:
diff changeset
3555
208
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents: 184
diff changeset
3556 </reference>