Mercurial > ecos

changeset 2970:b479691ea40f

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
* src/usbs.c, include/usbs.h: Extend usbs_control_endpoint struct and provide usbs_get_*_endpoint() functions to facilitate dynamic data endpoint configuration. Contributed by Chris Holgate. [ Bugzilla 1001024] * doc/usbs.sgml: Document the above changes. * cdl/usbs.cdl: Fix erroneous CYGPKG_IO_USB_SLAVE_TESTS display string.
author jld
date Wed, 27 Oct 2010 10:04:33 +0000
parents 7b425c007a6c
children ea354217b697
files packages/NEWS packages/io/usb/slave/current/ChangeLog packages/io/usb/slave/current/cdl/usbs.cdl packages/io/usb/slave/current/doc/usbs.sgml packages/io/usb/slave/current/include/usbs.h packages/io/usb/slave/current/src/usbs.c
diffstat 6 files changed, 92 insertions(+), 6 deletions(-) [+]
line wrap: on
line diff
--- a/packages/NEWS
+++ b/packages/NEWS
@@ -1,3 +1,5 @@
+* Support for dynamic data endpoint configuration in USB slave API by
+  Chris Holgate
 * Update to uSTL 1.4 by Simon Kallweit
 * ADC device driver for AT91 by Christophe Coutand 
 * Major update of lwIP stack to v1.3.2 by Simon Kallweit
--- a/packages/io/usb/slave/current/ChangeLog
+++ b/packages/io/usb/slave/current/ChangeLog
@@ -1,3 +1,13 @@
+2010-10-26  John Dallaway  <john@dallaway.org.uk>
+
+	* src/usbs.c, include/usbs.h: Extend usbs_control_endpoint struct and
+	provide usbs_get_*_endpoint() functions to facilitate dynamic data
+	endpoint configuration. Contributed by Chris Holgate.
+	[ Bugzilla 1001024]
+	* doc/usbs.sgml: Document the above changes.
+	* cdl/usbs.cdl: Fix erroneous CYGPKG_IO_USB_SLAVE_TESTS display
+	string.
+
 2008-08-28  Bart Veer  <bartv@ecoscentric.com>
 
 	* host/configure: regenerate after update of Tcl macro
@@ -186,7 +196,7 @@ 2000-11-21  Bart Veer  <bartv@redhat.com
 // ####GPLCOPYRIGHTBEGIN####                                                
 // -------------------------------------------                              
 // This file is part of eCos, the Embedded Configurable Operating System.   
-// Copyright (C) 1998, 1999, 2000, 2001, 2002 Free Software Foundation, Inc.
+// Copyright (C) 1998, 1999, 2000, 2001, 2002, 2010 Free Software Foundation, Inc.
 //
 // This program is free software; you can redistribute it and/or modify     
 // it under the terms of the GNU General Public License as published by     
--- a/packages/io/usb/slave/current/cdl/usbs.cdl
+++ b/packages/io/usb/slave/current/cdl/usbs.cdl
@@ -8,7 +8,7 @@
 ## ####ECOSGPLCOPYRIGHTBEGIN####                                            
 ## -------------------------------------------                              
 ## This file is part of eCos, the Embedded Configurable Operating System.   
-## Copyright (C) 1998, 1999, 2000, 2001, 2002 Free Software Foundation, Inc.
+## Copyright (C) 1998, 1999, 2000, 2001, 2002, 2010 Free Software Foundation, Inc.
 ##
 ## eCos is free software; you can redistribute it and/or modify it under    
 ## the terms of the GNU General Public License as published by the Free     
@@ -123,7 +123,7 @@ cdl_package CYGPKG_IO_USB_SLAVE {
     }
     
     cdl_option CYGPKG_IO_USB_SLAVE_TESTS {
-	display   "Kernel tests"
+	display   "USB slave tests"
 	flavor    data
 	no_define
 	default_value { "" }
--- a/packages/io/usb/slave/current/doc/usbs.sgml
+++ b/packages/io/usb/slave/current/doc/usbs.sgml
@@ -11,7 +11,7 @@
 <!-- =============================================================== -->
 <!-- ####ECOSDOCCOPYRIGHTBEGIN####                                       -->
 <!-- ===============================================================     -->
-<!-- Copyright (C) 2001, 2002 Free Software Foundation, Inc.             -->
+<!-- Copyright (C) 2001, 2002, 2010 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              -->
@@ -26,6 +26,7 @@
 <!--                                                                 -->
 <!-- Author(s):   bartv                                              -->
 <!-- Contact(s):  bartv                                              -->
+<!-- Contributor: jld                                                -->
 <!-- Date:        2001/01/03                                         -->
 <!-- Version:     0.01                                               -->
 <!--                                                                 -->
@@ -1952,6 +1953,28 @@ be identified in the data structure as w
 </para>
 </refsect2>
 
+<refsect2><title>Dynamic Data Endpoint Support</title>
+<programlisting width=72>
+typedef struct usbs_control_endpoint {
+    struct usbs_rx_endpoint* (*get_rxep_fn)(struct usbs_control_endpoint*, cyg_uint8);
+    struct usbs_tx_endpoint* (*get_txep_fn)(struct usbs_control_endpoint*, cyg_uint8);
+    &hellip;
+} usbs_control_endpoint;
+</programlisting>
+<para>
+USB slave hardware may support multiple USB configurations via
+configurable data endpoints. If the device driver can support such
+operation, it will provide a pair of functions via the
+<structfield>get_rxep_fn</structfield> and
+<structfield>get_txep_fn</structfield> fields which enable retrieval
+of the receive and transmit data endpoint structures using the logical
+endpoint IDs specified in a USB class descriptor. Access to these
+functions from higher-level code is provided by the
+<function>usbs_get_rx_endpoint</function> and
+<function>usbs_get_tx_endpoint</function> functions.
+</para>
+</refsect2>
+
 </refsect1>
 
 </refentry>
--- a/packages/io/usb/slave/current/include/usbs.h
+++ b/packages/io/usb/slave/current/include/usbs.h
@@ -10,7 +10,7 @@
 // ####ECOSGPLCOPYRIGHTBEGIN####                                            
 // -------------------------------------------                              
 // This file is part of eCos, the Embedded Configurable Operating System.   
-// Copyright (C) 1998, 1999, 2000, 2001, 2002 Free Software Foundation, Inc.
+// Copyright (C) 1998, 1999, 2000, 2001, 2002, 2010 Free Software Foundation, Inc.
 //
 // eCos is free software; you can redistribute it and/or modify it under    
 // the terms of the GNU General Public License as published by the Free     
@@ -171,6 +171,10 @@ typedef enum {
     USBS_CONTROL_RETURN_STALL   = 2
 } usbs_control_return;
 
+// Forward type definitions - see below for structure detail.
+struct usbs_rx_endpoint;
+struct usbs_tx_endpoint;
+
 typedef struct usbs_control_endpoint {
     // The state is maintained by the USB code and should not be
     // modified by anything higher up.
@@ -274,6 +278,27 @@ typedef struct usbs_control_endpoint {
     void*               fill_data;
     int                 fill_index;
     usbs_control_return (*complete_fn)(struct usbs_control_endpoint*, int);
+
+    // The following two functions provide a common API for accessing
+    // USB data endpoints.  This avoids class drivers needing to know 
+    // about the physical configuration of endpoints for each underlying
+    // USB slave device driver.  The functions are used to map the 
+    // logical endpoint ID (as specified in the USB class descriptors) to 
+    // the appropriate endpoint data structure (as used by the eCos USB 
+    // slave API calls).  Individual USB slave drivers are free to implement
+    // this mapping in the most appropriate manner for the underlying
+    // hardware.  This may be via CDL compile time options or preferably 
+    // by scanning the supplied class driver descriptors at runtime.
+    // The latter method allows eCos to support multiple USB configurations
+    // in a single USB device.  For this reason, these functions will only
+    // yield a valid endpoint mapping while the USB device is in its
+    // configured state.  In all other states they will return a null
+    // pointer.  These functions should also return a null pointer if the 
+    // requested endpoint ID is not valid for the currently selected 
+    // configuration.
+    struct usbs_rx_endpoint* (*get_rxep_fn)(struct usbs_control_endpoint*, cyg_uint8);
+    struct usbs_tx_endpoint* (*get_txep_fn)(struct usbs_control_endpoint*, cyg_uint8);
+    
 } usbs_control_endpoint;
 
 // Data endpoints are a little bit simpler, but not much. From the
@@ -341,6 +366,10 @@ extern void     usbs_set_rx_endpoint_hal
 extern void     usbs_set_tx_endpoint_halted(usbs_tx_endpoint*, cyg_bool);
 extern void     usbs_start_rx_endpoint_wait(usbs_rx_endpoint*, void (*)(void*, int), void*);
 extern void     usbs_start_tx_endpoint_wait(usbs_tx_endpoint*, void (*)(void*, int), void*);
+
+// Utility function to access USB data endpoints by logical endpoint ID.
+extern usbs_rx_endpoint* usbs_get_rx_endpoint(usbs_control_endpoint*, cyg_uint8);
+extern usbs_tx_endpoint* usbs_get_tx_endpoint(usbs_control_endpoint*, cyg_uint8);
     
 // Functions that can go into devtab entries. These should not be
 // called directly, they are intended only for use by USB device
--- a/packages/io/usb/slave/current/src/usbs.c
+++ b/packages/io/usb/slave/current/src/usbs.c
@@ -8,7 +8,7 @@
 // ####ECOSGPLCOPYRIGHTBEGIN####                                            
 // -------------------------------------------                              
 // This file is part of eCos, the Embedded Configurable Operating System.   
-// Copyright (C) 1998, 1999, 2000, 2001, 2002 Free Software Foundation, Inc.
+// Copyright (C) 1998, 1999, 2000, 2001, 2002, 2010 Free Software Foundation, Inc.
 //
 // eCos is free software; you can redistribute it and/or modify it under    
 // the terms of the GNU General Public License as published by the Free     
@@ -195,6 +195,28 @@ usbs_devtab_set_config(cyg_io_handle_t h
 // USB-specific functions that are useful for applications/packages which
 // do not want to use the devtab interface. These may get called in DSR
 // context.
+ 
+usbs_rx_endpoint* 
+usbs_get_rx_endpoint(usbs_control_endpoint* control_endpoint, 
+                                       cyg_uint8 endpoint_id)
+{
+    CYG_CHECK_DATA_PTR(control_endpoint, "A valid control endpoint must be supplied");
+    CYG_CHECK_FUNC_PTR(control_endpoint->get_rxep_fn, "Dynamic endpoint access not supported");
+    if (control_endpoint->state != USBS_STATE_CONFIGURED) 
+        return NULL;
+    return (*control_endpoint->get_rxep_fn)(control_endpoint, endpoint_id);
+}
+
+usbs_tx_endpoint* 
+usbs_get_tx_endpoint(usbs_control_endpoint* control_endpoint, 
+                                       cyg_uint8 endpoint_id)
+{
+    CYG_CHECK_DATA_PTR(control_endpoint, "A valid control endpoint must be supplied");
+    CYG_CHECK_FUNC_PTR(control_endpoint->get_txep_fn, "Dynamic endpoint access not supported");
+    if (control_endpoint->state != USBS_STATE_CONFIGURED) 
+        return NULL;
+    return (*control_endpoint->get_txep_fn)(control_endpoint, endpoint_id);
+}
 
 void
 usbs_start_rx(usbs_rx_endpoint* endpoint)