URL https://opencores.org/ocsvn/openrisc/openrisc/trunk

Subversion Repositories openrisc

[/] [openrisc/] [trunk/] [rtos/] [ecos-3.0/] [packages/] [io/] [usb/] [eth/] [slave/] [current/] [doc/] [usbseth-control.html] - Blame information for rev 786

Details | Compare with Previous | View Log


<!-- Copyright (C) 2001 Free Software Foundation, Inc.                                -->
<!-- This material may be distributed only subject to the terms      -->
<!-- and conditions set forth in the Open Publication License, v1.0  -->
<!-- or later (the latest version is presently available at          -->
<!-- http://www.opencontent.org/openpub/).                           -->
<!-- Distribution of substantively modified versions of this         -->
<!-- document is prohibited without the explicit permission of the   -->
<!-- copyright holder.                                               -->
<!-- Distribution of the work or derivative of the work in any       -->
<!-- standard (paper) book form is prohibited unless prior           -->
<!-- permission is obtained from the copyright holder.               -->
<HTML
><HEAD
><TITLE
>USB-ethernet State Handling</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.64
"><LINK
REL="HOME"
TITLE="eCos Support for Developing USB-ethernet Peripherals"
HREF="io-usb-slave-eth.html"><LINK
REL="PREVIOUS"
TITLE="USB-ethernet Data Transfers"
HREF="usbseth-data.html"><LINK
REL="NEXT"
TITLE="Network Device for the eCos TCP/IP Stack"
HREF="usbseth-netdev.html"></HEAD
><BODY
CLASS="REFENTRY"
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#0000FF"
VLINK="#840084"
ALINK="#0000FF"
><DIV
CLASS="NAVHEADER"
><TABLE
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="3"
ALIGN="center"
>eCos Support for Developing USB-ethernet Peripherals</TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="bottom"
><A
HREF="usbseth-data.html"
>Prev</A
></TD
><TD
WIDTH="80%"
ALIGN="center"
VALIGN="bottom"
></TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="bottom"
><A
HREF="usbseth-netdev.html"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><H1
><A
NAME="USBSETH-CONTROL"
>USB-ethernet State Handling</A
></H1
><DIV
CLASS="REFNAMEDIV"
><A
NAME="AEN163"
></A
><H2
>Name</H2
>USB-ethernet State Handling&nbsp;--&nbsp;Maintaining the USB-ethernet connection with the host</DIV
><DIV
CLASS="REFSYNOPSISDIV"
><A
NAME="AEN166"
></A
><H2
>Synopsis</H2
><DIV
CLASS="FUNCSYNOPSIS"
><A
NAME="AEN167"
></A
><P
></P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="FUNCSYNOPSISINFO"
>#include &lt;cyg/io/usb/usbs_eth.h&gt;</PRE
></TD
></TR
></TABLE
><P
><CODE
><CODE
CLASS="FUNCDEF"
>usbs_control_return usbs_eth_class_control_handler</CODE
>(usbs_control_endpoint* ep0, void* callback_data);</CODE
></P
><P
><CODE
><CODE
CLASS="FUNCDEF"
>void usbs_eth_state_change_handler</CODE
>(usbs_control_endpoint* ep0, void* callback_data, usbs_state_change change, int old_state);</CODE
></P
><P
><CODE
><CODE
CLASS="FUNCDEF"
>void usbs_eth_disable</CODE
>(usbs_eth* usbseth&#62;);</CODE
></P
><P
><CODE
><CODE
CLASS="FUNCDEF"
>void usbs_eth_enable</CODE
>(usbs_eth* usbseth&#62;);</CODE
></P
><P
></P
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN197"
></A
><H2
>Description</H2
><P
>When the USB-ethernet package is initialized by a call to <A
HREF="usbseth-init.html"
><TT
CLASS="FUNCTION"
>usbs_eth_init</TT
></A
> it
installs <TT
CLASS="FUNCTION"
>usbs_eth_state_change_handler</TT
> to handle
USB state changes. This allows the package to detect when the
connection between the host and the peripheral is established or
broken, resulting in internal calls to
<TT
CLASS="FUNCTION"
>usbs_eth_enable</TT
> and
<TT
CLASS="FUNCTION"
>usbs_eth_disable</TT
> respectively. This is
appropriate if no other code needs to access the USB device. However,
if there is other code, either other USB-related packages or the
application itself, that needs to perform I/O over the USB bus, then
typically the USB-ethernet package should not have exclusive access to
state change events. Instead, the assumption is that higher-level
code, typically provided by the application, will install an
alternative state change handler in the control endpoint data
structure after the call to <TT
CLASS="FUNCTION"
>usbs_eth_init</TT
>. This
alternative handler will either chain into
<TT
CLASS="FUNCTION"
>usbs_eth_state_change_handler</TT
> when appropriate,
or else it will invoke <TT
CLASS="FUNCTION"
>usbs_eth_enable</TT
> and
<TT
CLASS="FUNCTION"
>usbs_eth_disable</TT
> directly. For further details of
state change handlers and control endpoints generally, see the
documentation for the common USB-slave package.</P
><P
>Similarly, <TT
CLASS="FUNCTION"
>usbs_eth_init</TT
> will install
<TT
CLASS="FUNCTION"
>usbs_eth_class_control_handler</TT
> in the control
endpoint data structure as the appropriate handler for class-specific
USB control messages. This code will handle the ethernet-specific
<A
HREF="usbseth-protocol.html"
>control messages </A
>, for example
requests by the host to enable or disable promiscuous mode or to
obtain the MAC address. If the USB device is not shared with any other
code then this is both necessary and sufficient. However, if other code
is involved and if that code also needs to process certain control
messages, higher-level code should install its own handler and chain
to the USB-ethernet one when appropriate. It should be noted that the
request code is encoded in just a single byte, so there is a real
possibility that exactly the same number will be used by different
protocols for different requests. Any such problems will have to be
identified and resolved by application developers, and may involve
modifying the source code for the USB-ethernet package.</P
><P
>As an alternative to chaining the state change handler, higher-level
code can instead call <TT
CLASS="FUNCTION"
>usbs_eth_disable</TT
> and
<TT
CLASS="FUNCTION"
>usbs_eth_enable</TT
> directly. These functions may
also be called if the USB-ethernet package should become inactive for
reasons not related directly to events on the USB bus. The main effect
of <TT
CLASS="FUNCTION"
>usbs_eth_enable</TT
> is to restart receive
operations and to allow transmits. The main effect of
<TT
CLASS="FUNCTION"
>usbs_eth_disable</TT
> is to block further transmits:
any current receive operations need to be aborted at the USB level,
for example by halting the appropriate endpoint.</P
></DIV
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="usbseth-data.html"
>Prev</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="io-usb-slave-eth.html"
>Home</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="usbseth-netdev.html"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>USB-ethernet Data Transfers</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
>&nbsp;</TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>Network Device for the eCos TCP/IP Stack</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>

Line No.	Rev	Author	Line
1	786	skrzyp	`<!-- Copyright (C) 2001 Free Software Foundation, Inc. -->`
2			`<!-- This material may be distributed only subject to the terms -->`
3			`<!-- and conditions set forth in the Open Publication License, v1.0 -->`
4			`<!-- or later (the latest version is presently available at -->`
5			`<!-- http://www.opencontent.org/openpub/). -->`
6			`<!-- Distribution of substantively modified versions of this -->`
7			`<!-- document is prohibited without the explicit permission of the -->`
8			`<!-- copyright holder. -->`
9			`<!-- Distribution of the work or derivative of the work in any -->`
10			`<!-- standard (paper) book form is prohibited unless prior -->`
11			`<!-- permission is obtained from the copyright holder. -->`
12			`<HTML`
13			`><HEAD`
14			`><TITLE`
15			`>USB-ethernet State Handling</TITLE`
16			`><META`
17			`NAME="GENERATOR"`
18			`CONTENT="Modular DocBook HTML Stylesheet Version 1.64`
19			`"><LINK`
20			`REL="HOME"`
21			`TITLE="eCos Support for Developing USB-ethernet Peripherals"`
22			`HREF="io-usb-slave-eth.html"><LINK`
23			`REL="PREVIOUS"`
24			`TITLE="USB-ethernet Data Transfers"`
25			`HREF="usbseth-data.html"><LINK`
26			`REL="NEXT"`
27			`TITLE="Network Device for the eCos TCP/IP Stack"`
28			`HREF="usbseth-netdev.html"></HEAD`
29			`><BODY`
30			`CLASS="REFENTRY"`
31			`BGCOLOR="#FFFFFF"`
32			`TEXT="#000000"`
33			`LINK="#0000FF"`
34			`VLINK="#840084"`
35			`ALINK="#0000FF"`
36			`><DIV`
37			`CLASS="NAVHEADER"`
38			`><TABLE`
39			`WIDTH="100%"`
40			`BORDER="0"`
41			`CELLPADDING="0"`
42			`CELLSPACING="0"`
43			`><TR`
44			`><TH`
45			`COLSPAN="3"`
46			`ALIGN="center"`
47			`>eCos Support for Developing USB-ethernet Peripherals</TH`
48			`></TR`
49			`><TR`
50			`><TD`
51			`WIDTH="10%"`
52			`ALIGN="left"`
53			`VALIGN="bottom"`
54			`><A`
55			`HREF="usbseth-data.html"`
56			`>Prev</A`
57			`></TD`
58			`><TD`
59			`WIDTH="80%"`
60			`ALIGN="center"`
61			`VALIGN="bottom"`
62			`></TD`
63			`><TD`
64			`WIDTH="10%"`
65			`ALIGN="right"`
66			`VALIGN="bottom"`
67			`><A`
68			`HREF="usbseth-netdev.html"`
69			`>Next</A`
70			`></TD`
71			`></TR`
72			`></TABLE`
73			`><HR`
74			`ALIGN="LEFT"`
75			`WIDTH="100%"></DIV`
76			`><H1`
77			`><A`
78			`NAME="USBSETH-CONTROL"`
79			`>USB-ethernet State Handling</A`
80			`></H1`
81			`><DIV`
82			`CLASS="REFNAMEDIV"`
83			`><A`
84			`NAME="AEN163"`
85			`></A`
86			`><H2`
87			`>Name</H2`
88			`>USB-ethernet State Handling -- Maintaining the USB-ethernet connection with the host</DIV`
89			`><DIV`
90			`CLASS="REFSYNOPSISDIV"`
91			`><A`
92			`NAME="AEN166"`
93			`></A`
94			`><H2`
95			`>Synopsis</H2`
96			`><DIV`
97			`CLASS="FUNCSYNOPSIS"`
98			`><A`
99			`NAME="AEN167"`
100			`></A`
101			`><P`
102			`></P`
103			`><TABLE`
104			`BORDER="0"`
105			`BGCOLOR="#E0E0E0"`
106			`WIDTH="100%"`
107			`><TR`
108			`><TD`
109			`><PRE`
110			`CLASS="FUNCSYNOPSISINFO"`
111			`>#include <cyg/io/usb/usbs_eth.h></PRE`
112			`></TD`
113			`></TR`
114			`></TABLE`
115			`><P`
116			`><CODE`
117			`><CODE`
118			`CLASS="FUNCDEF"`
119			`>usbs_control_return usbs_eth_class_control_handler</CODE`
120			`>(usbs_control_endpoint* ep0, void* callback_data);</CODE`
121			`></P`
122			`><P`
123			`><CODE`
124			`><CODE`
125			`CLASS="FUNCDEF"`
126			`>void usbs_eth_state_change_handler</CODE`
127			`>(usbs_control_endpoint* ep0, void* callback_data, usbs_state_change change, int old_state);</CODE`
128			`></P`
129			`><P`
130			`><CODE`
131			`><CODE`
132			`CLASS="FUNCDEF"`
133			`>void usbs_eth_disable</CODE`
134			`>(usbs_eth* usbseth>);</CODE`
135			`></P`
136			`><P`
137			`><CODE`
138			`><CODE`
139			`CLASS="FUNCDEF"`
140			`>void usbs_eth_enable</CODE`
141			`>(usbs_eth* usbseth>);</CODE`
142			`></P`
143			`><P`
144			`></P`
145			`></DIV`
146			`></DIV`
147			`><DIV`
148			`CLASS="REFSECT1"`
149			`><A`
150			`NAME="AEN197"`
151			`></A`
152			`><H2`
153			`>Description</H2`
154			`><P`
155			`>When the USB-ethernet package is initialized by a call to <A`
156			`HREF="usbseth-init.html"`
157			`><TT`
158			`CLASS="FUNCTION"`
159			`>usbs_eth_init</TT`
160			`></A`
161			`> it`
162			`installs <TT`
163			`CLASS="FUNCTION"`
164			`>usbs_eth_state_change_handler</TT`
165			`> to handle`
166			`USB state changes. This allows the package to detect when the`
167			`connection between the host and the peripheral is established or`
168			`broken, resulting in internal calls to`
169			`<TT`
170			`CLASS="FUNCTION"`
171			`>usbs_eth_enable</TT`
172			`> and`
173			`<TT`
174			`CLASS="FUNCTION"`
175			`>usbs_eth_disable</TT`
176			`> respectively. This is`
177			`appropriate if no other code needs to access the USB device. However,`
178			`if there is other code, either other USB-related packages or the`
179			`application itself, that needs to perform I/O over the USB bus, then`
180			`typically the USB-ethernet package should not have exclusive access to`
181			`state change events. Instead, the assumption is that higher-level`
182			`code, typically provided by the application, will install an`
183			`alternative state change handler in the control endpoint data`
184			`structure after the call to <TT`
185			`CLASS="FUNCTION"`
186			`>usbs_eth_init</TT`
187			`>. This`
188			`alternative handler will either chain into`
189			`<TT`
190			`CLASS="FUNCTION"`
191			`>usbs_eth_state_change_handler</TT`
192			`> when appropriate,`
193			`or else it will invoke <TT`
194			`CLASS="FUNCTION"`
195			`>usbs_eth_enable</TT`
196			`> and`
197			`<TT`
198			`CLASS="FUNCTION"`
199			`>usbs_eth_disable</TT`
200			`> directly. For further details of`
201			`state change handlers and control endpoints generally, see the`
202			`documentation for the common USB-slave package.</P`
203			`><P`
204			`>Similarly, <TT`
205			`CLASS="FUNCTION"`
206			`>usbs_eth_init</TT`
207			`> will install`
208			`<TT`
209			`CLASS="FUNCTION"`
210			`>usbs_eth_class_control_handler</TT`
211			`> in the control`
212			`endpoint data structure as the appropriate handler for class-specific`
213			`USB control messages. This code will handle the ethernet-specific`
214			`<A`
215			`HREF="usbseth-protocol.html"`
216			`>control messages </A`
217			`>, for example`
218			`requests by the host to enable or disable promiscuous mode or to`
219			`obtain the MAC address. If the USB device is not shared with any other`
220			`code then this is both necessary and sufficient. However, if other code`
221			`is involved and if that code also needs to process certain control`
222			`messages, higher-level code should install its own handler and chain`
223			`to the USB-ethernet one when appropriate. It should be noted that the`
224			`request code is encoded in just a single byte, so there is a real`
225			`possibility that exactly the same number will be used by different`
226			`protocols for different requests. Any such problems will have to be`
227			`identified and resolved by application developers, and may involve`
228			`modifying the source code for the USB-ethernet package.</P`
229			`><P`
230			`>As an alternative to chaining the state change handler, higher-level`
231			`code can instead call <TT`
232			`CLASS="FUNCTION"`
233			`>usbs_eth_disable</TT`
234			`> and`
235			`<TT`
236			`CLASS="FUNCTION"`
237			`>usbs_eth_enable</TT`
238			`> directly. These functions may`
239			`also be called if the USB-ethernet package should become inactive for`
240			`reasons not related directly to events on the USB bus. The main effect`
241			`of <TT`
242			`CLASS="FUNCTION"`
243			`>usbs_eth_enable</TT`
244			`> is to restart receive`
245			`operations and to allow transmits. The main effect of`
246			`<TT`
247			`CLASS="FUNCTION"`
248			`>usbs_eth_disable</TT`
249			`> is to block further transmits:`
250			`any current receive operations need to be aborted at the USB level,`
251			`for example by halting the appropriate endpoint.</P`
252			`></DIV`
253			`><DIV`
254			`CLASS="NAVFOOTER"`
255			`><HR`
256			`ALIGN="LEFT"`
257			`WIDTH="100%"><TABLE`
258			`WIDTH="100%"`
259			`BORDER="0"`
260			`CELLPADDING="0"`
261			`CELLSPACING="0"`
262			`><TR`
263			`><TD`
264			`WIDTH="33%"`
265			`ALIGN="left"`
266			`VALIGN="top"`
267			`><A`
268			`HREF="usbseth-data.html"`
269			`>Prev</A`
270			`></TD`
271			`><TD`
272			`WIDTH="34%"`
273			`ALIGN="center"`
274			`VALIGN="top"`
275			`><A`
276			`HREF="io-usb-slave-eth.html"`
277			`>Home</A`
278			`></TD`
279			`><TD`
280			`WIDTH="33%"`
281			`ALIGN="right"`
282			`VALIGN="top"`
283			`><A`
284			`HREF="usbseth-netdev.html"`
285			`>Next</A`
286			`></TD`
287			`></TR`
288			`><TR`
289			`><TD`
290			`WIDTH="33%"`
291			`ALIGN="left"`
292			`VALIGN="top"`
293			`>USB-ethernet Data Transfers</TD`
294			`><TD`
295			`WIDTH="34%"`
296			`ALIGN="center"`
297			`VALIGN="top"`
298			`> </TD`
299			`><TD`
300			`WIDTH="33%"`
301			`ALIGN="right"`
302			`VALIGN="top"`
303			`>Network Device for the eCos TCP/IP Stack</TD`
304			`></TR`
305			`></TABLE`
306			`></DIV`
307			`></BODY`
308			`></HTML`
309			`>`

Browse

Tools

Subversion Repositories openrisc

[/] [openrisc/] [trunk/] [rtos/] [ecos-3.0/] [packages/] [io/] [usb/] [eth/] [slave/] [current/] [doc/] [usbseth-control.html] - Blame information for rev 786