Introduction Introduction eCos support for developing USB ethernet peripherals The eCos USB-ethernet package provides additional support for USB peripherals that involve some sort of ethernet-style network. This can be a traditional ethernet, or it can involve some other networking technology that uses ethernet frames as a unit of transfer. It provides functions to transfer ethernet frames over the USB bus, handles certain control messages from the host, and optionally it can provide a network device driver for use by the eCos TCP/IP stack. The package comes with an example host-side device driver. The USB-ethernet package is not tied to any specific hardware. It requires the presence of USB hardware and a suitable device driver, but not all USB peripherals involve ethernet communications. Hence the configuration system cannot load the package automatically for specific targets, in the way that a USB device driver or an ethernet driver can be loaded automatically. Instead, the package has to be added explicitly. When using the command line tools this will involve an operation like the following: $ ecosconfig add usbs_eth Typically, this will automatically cause the USB device driver to become active. Loading the USB-ethernet package automatically provides functionality for initialization, data transfer, and the handling of control messages and state changes. If the current configuration includes the eCos TCP/IP stack then the network device driver support will be enabled as well by default, allowing the stack to exchange ethernet frames over the USB bus. There is a USB standard for a class of communication devices including ethernet. The package does not implement this standard, due to limitations in the hardware for which the package was first developed. Instead, the package uses its own protocol between USB host device driver and the peripheral. The USB-ethernet package can be used several different scenarios. In a simple scenario, the peripheral serves only to connect the USB host to a suitable network: After initialization, and once the USB connection between host and peripheral has been established, higher-level code needs to detect packets that are intended for the host, and to forward these. This can be achieved by the low-level usbs_eth_start_tx function. Similarly, higher-level code needs to detect packets coming from the host, using usbs_eth_start_rx, and to forward these using the real network. As far as the host is concerned it is connected directly to the network. In this scenario there is no confusion about addresses: there is a single MAC address for the host/peripheral combination, corresponding to the connection to the real network, and it is this address which should be supplied during initialization. In a more complicated scenario, there is a TCP/IP stack running inside the peripheral. This involves the USB-ethernet package providing a service both to the host and to the eCos TCP/IP stack. It achieves the latter by acting as an eCos network device. Typically, the TCP/IP stack will be configured to act as a network bridge. The USB peripheral needs to examine the packets arriving over the real network. Some of these packets will be intended for the host, while others will be intended for the peripheral itself. To distinguish between these two scenarios, two distinct MAC addresses are needed: one for the host, and one for the peripheral. Similarly, packets sent by the host may have to be forwarded via the real network, or they may be intended for the TCP/IP stack inside the peripheral. Packets generated inside the peripheral's TCP/IP stack may need to be sent via the real network or over the USB bus. The network bridge software will have to take care of all these possibilities. Unusually for a network bridge, one of the network segments being bridged will only ever have one machine attached. There are other possible usage scenarios. For example, the peripheral might not be attached to a real network at all. Instead it could be the USB host that acts as a network bridge, allowing a TCP/IP stack inside the peripheral to communicate with the outside world. The various details will depend on the exact type of peripheral being developed. Initializing the USB-ethernet Package usbs_eth_init Initializing the USB-ethernet Package #include <cyg/io/usb/usbs_eth.h> void usbs_eth_init usbs_eth* usbeth usbs_control_endpoint* ep0 usbs_rx_endpoint* ep1 usbs_tx_endpoint* ep2 unsigned char* mac_address The USB-ethernet package is not tied to any specific hardware. It requires certain functionality: there must be USB-slave hardware supported by a device driver; there must also be two endpoints for bulk transfers between host and peripheral, one for each direction; there must also be a control endpoint, although of course that is implicit with any USB hardware. However, USB-slave hardware may well provide more endpoints than the minimum required for ethernet support. Some of those endpoints might be used by other packages, while other endpoints might be used directly by the application, or might not be needed for the peripheral being built. There is also the possibility of a USB peripheral that supports multiple configurations, with the ethernet support active in only some of those configurations. The USB-ethernet package has no knowledge about any of this, so it relies on higher-level code to tell it which endpoints should be used and other information. This is the purpose of the usbs_eth_init function. The first argument identifies the specific usbs_eth data structure that is affected. It is expected that the vast majority of affected applications will only provide a single USB-ethernet device to a single host, and the package automatically provides a suitable data structure usbs_eth0 to support this. If multiple usbs_eth structures are needed for some reason then these need to be instantiated by other code, and each one needs to be initialised by a call to usbs_eth_init(). The next three arguments identify the endpoints that should be used for USB communications: a control endpoint, a receive endpoint for ethernet packets coming from the host to the peripheral, and a transmit endpoint for ethernet packets going in the other direction. Obviously all three endpoints should be provided by the same USB hardware. The USB-ethernet package assumes that it has sole access to the receive and transmit endpoints, subject to the use of usbs_eth_disable and usbs_eth_enable control functions. The package also assumes that no other code is interested in USB state changes or class control messages: it installs handlers usbs_eth_state_change_handler and usbs_eth_class_control_handler in the control endpoint. If any other code does need to handle USB state changes or class control messages then replacement handlers should be installed after the call to usbs_eth_init, and those replacements should invoke the USB-ethernet ones when appropriate. The final argument to usbs_eth_init specifies the MAC address (or Ethernet Station Address) that should be provided to the host-side device driver. Since the USB-ethernet package does not interact directly with a real ethernet device it cannot obtain the MAC address from any hardware. Instead, it must be supplied by higher-level code. The details depend on the scenario in which the USB-ethernet package is being used. The call to usbs_eth_init should normally happen after the enumeration data has been provided but before the underlying USB device driver has been started. If the USB device were to be started first then a connection between host and peripheral could be established immediately, and the host-side device driver would attempt to contact the USB-ethernet package for information such as the MAC address. int main(int argc, char** argv) { unsigned char host_MAC[6] = { 0x40, 0x5d, 0x90, 0xa9, 0xbc, 0x02 }; usbs_sa11x0_ep0.enumeration_data = &usb_enum_data; … usbs_eth_init(&usbs_eth0, &usbs_sa11x0_ep0, &usbs_sa11x0_ep1, &usbs_sa11x0_ep2, host_MAC); … usbs_start(&usbs_sa11x0_ep0); … } USB-ethernet Data Transfers USB-ethernet Data Transfers Exchanging ethernet packets with the USB host #include <cyg/io/usb/usbs_eth.h> void usbs_eth_start_rx usbs_eth* usbseth unsigned char* buffer void (*)(usbs_eth*, void*, int) complete_fn void* complete_data void usbs_eth_start_tx usbs_eth* usbseth unsigned char* buffer void (*)(usbs_eth*, void*, int) complete_fn void* complete_data The USB-ethernet package provides two main modes of operation. In the first mode it provides a network device driver for use by a TCP/IP stack running inside the USB peripheral. All incoming ethernet packets should be passed up the TCP/IP stack, and only the stack will generate outgoing packets. Apart from initialization and possibly certain control operations, higher-level code will not interact with the USB-ethernet package directly. In the second mode there is no TCP/IP stack running inside the USB peripheral. For example, a simple USB-ethernet converter has an ethernet chip and a USB port: ethernet packets received by the ethernet chip need to be forwarded to the USB host, and ethernet packets sent by the USB host need to be sent out of the ethernet chip. usbs_eth_start_rx and usbs_eth_start_tx allow for this lower-level access to the USB-ethernet package. The two modes of operation are mutually exclusive. If the network device driver mode is enabled then application code should communicate at the TCP/IP level, and not by using the lower-level functions. Instead, it is the network device driver that will make use of these functions, and it assumes that it has exclusive access. The package does not perform any locking. The transmit and receive functions work in much the same way. The first argument identifies the usbs_eth structure that should be used. For the majority of applications this will be usbs_eth0. The second argument specifies the location of the ethernet packet; outgoing for usbs_eth_start_tx and incoming for usbs_eth_start_rx. This buffer should correspond to the protocol: Outgoing packets can consist of up to 1516 bytes, consisting of a two-byte header specific to USB-ethernet followed by a standard ethernet frame (a header with 6-byte destination address, 6-byte source address and a further two bytes, followed by a payload of up to 1500 bytes). The two-byte USB-ethernet header consists simply of the size of the ethernet frame, i.e. the size of the rest of the packet not including the USB-ethernet header, with the least significant byte first. For incoming packets the supplied buffer should usually be at least 1516 bytes. There may be special circumstances in which a smaller buffer might be safe; for example, if the host-side device driver is modified to support only smaller packets. Once the packet has been received the buffer will contain a two-byte header specific to USB-ethernet, followed by a normal ethernet frame. The header gives the size of the ethernet frame, excluding the header, with the least significant byte first. Both usbs_eth_start_tx and usbs_eth_start_rx are asynchronous: the transfer is started and, some time later, a completion function will be invoked. The third and fourth arguments to both usbs_eth_start_tx and usbs_eth_start_rx supply the completion function and an argument to that function respectively. The completion function will be invoked with three arguments: a pointer to the usbs_eth data structure, usually usbs_eth0; the supplied completion data ; and a return code field. A negative value indicates that an error occurred, for example -EPIPE if the connection between USB host and peripheral has been broken, or -EAGAIN if an endpoint has been halted. A positive value indicates the total size of the transfer, which should correspond to the size in the USB-ethernet header plus an additional two bytes for the header itself. If the data transfer is succesful then the completion function will typically be invoked in DSR context rather than in thread context, although this depends on the implementation of the underlying USB device driver. Therefore the completion function is restricted in what it can do; in particular, it must not make any calls that will or may block such as locking a mutex or allocating memory. The kernel documentation should be consulted for more details of DSR's and interrupt handling generally. Note that if the transfer finishes quickly then the completion function may be invoked before usbs_eth_start_rx or usbs_eth_start_tx returns. This is especially likely to happen if the current thread is descheduled after starting the data transfer but before returning from these functions. For transmit operations, it is possible for usbs_eth_start_tx to invoke the completion function immediately. If there is no current connection between host and target then the transmit will fail immediately with -EPIPE. In addition the USB-ethernet package will check the destination MAC address and make sure that the ethernet frame really is intended for the host: either it must be for the address specified in the initialization call usbs_eth_init, or it must be a broadcast packet, or the host must have enabled promiscuous mode. USB-ethernet State Handling USB-ethernet State Handling Maintaining the USB-ethernet connection with the host #include <cyg/io/usb/usbs_eth.h> usbs_control_return usbs_eth_class_control_handler usbs_control_endpoint* ep0 void* callback_data void usbs_eth_state_change_handler usbs_control_endpoint* ep0 void* callback_data usbs_state_change change int old_state void usbs_eth_disable usbs_eth* usbseth> void usbs_eth_enable usbs_eth* usbseth> When the USB-ethernet package is initialized by a call to usbs_eth_init it installs usbs_eth_state_change_handler 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 usbs_eth_enable and usbs_eth_disable 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 usbs_eth_init. This alternative handler will either chain into usbs_eth_state_change_handler when appropriate, or else it will invoke usbs_eth_enable and usbs_eth_disable directly. For further details of state change handlers and control endpoints generally, see the documentation for the common USB-slave package. Similarly, usbs_eth_init will install usbs_eth_class_control_handler in the control endpoint data structure as the appropriate handler for class-specific USB control messages. This code will handle the ethernet-specific control messages , 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. As an alternative to chaining the state change handler, higher-level code can instead call usbs_eth_disable and usbs_eth_enable 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 usbs_eth_enable is to restart receive operations and to allow transmits. The main effect of usbs_eth_disable is to block further transmits: any current receive operations need to be aborted at the USB level, for example by halting the appropriate endpoint. Network Device for the eCos TCP/IP Stack Network Device USB-ethernet support for the eCos TCP/IP Stack If the USB peripheral involves running the eCos TCP/IP stack and that stack needs to use USB-ethernet as a transport layer (or as one of the transports), then the USB-ethernet package can provide a suitable network device driver. It is still necessary for higher-level code to perform appropriate initialization by calling usbs_eth_init, but after that it will be the TCP/IP stack rather than application code that transmits or receives ethernet frames. Not all peripherals involving the USB-ethernet package will require a TCP/IP stack. Hence the provision of the network device is controlled by a configuration option CYGPKG_USBS_ETHDRV. By default this will be enabled if the TCP/IP package CYGPKG_NET is loaded, and disabled otherwise. There are a number of other configuration options related to the network device. CYGFUN_USBS_ETHDRV_STATISTICS determines whether or not the package will maintain statistics, mainly intended for SNMP: by default this will be enabled if the SNMP support package CYGPKG_SNMPAGENT is loaded, and disabled otherwise. The name of the ethernet device is controlled by CYGDATA_USBS_ETHDRV_NAME, and has a default value of either eth0 or eth1 depending on whether or not there is another network device driver present in the configuration. Usually eCos network device drivers default to using DHCP for obtaining necessary information such as IP addresses. This is not appropriate for USB-ethernet devices. On the host-side the USB-ethernet network device will not exist until the USB peripheral has been plugged in and communication has been established. Therefore any DHCP daemon on the host would not be listening on that network device at the point that eCos requests its IP and other information. A related issue is that the use of DHCP would imply the presence of a DHCP daemon on every affected host machine, as opposed to a single daemon (plus backups) for the network as a whole. For these reasons the USB-ethernet package precludes the use of DHCP as a way of setting the IP address, instead requiring alternatives such as manual configuration. Example Host-side Device Driver Example Host-side Device Driver Provide host-side support for the eCos USB-ethernet package The USB-ethernet package is supplied with a single host-side device driver. This driver has been developed against the Linux kernel 2.2.16-22, as shipped with Red Hat 7. The driver is provided as is and should not be considered production quality: for example it only checks for a bogus vendor id 0x4242 rather than an official vendor id supplied by the USB Implementers Forum. Also, if the peripheral involves multiple configurations or multiple interfaces, it will fail to detect this. However, the driver can be used for simple testing and as the basis of a full device driver. Details of the protocol used between host and peripheral can be found in the Communication Protocol section. The host-side device driver can be found in the host subdirectory of the USB-ethernet package, specifically the file ecos_usbeth.c, and comes with a Makefile. Both files may need to be modified for specific applications. For example, the vendor id table ecos_usbeth_implementations may need to be updated for the specific USB peripheral being built. The Makefile assumes that the Linux kernel sources reside in /usr/src/linux, and that the kernel has already been configured and built. Assuming this is the case, the device driver can be built simply by invoking make with no additional arguments. This will result in a dynamically loadable kernel module, ecos_usbeth.o, in the current directory. As normal for Linux kernel builds, the generated files such as ecos_usbeth.o live in the same directory as the source tree. This is very different from eCos where the source tree (or component repository) is kept separate from any builds. There may be problems if the component repository is kept read-only or if it is put under source code control. Any such problems can be avoided by making a copy of the host subdirectory and building that copy. Loading the kernel module into the current system requires root privileges. If the generic USB support is also a loadable module and has not been loaded already, this must happen first: # insmod usb-uhci Using /lib/modules/2.2.16-22/usb/usb-uhci.o Depending on the host hardware, the uhci or usb-ohci modules may be more appropriate. Loading the generic USB module will typically result in a number of messages to the logfile /var/log/messages, giving details of the specific host-side hardware that has been detected plus any hubs. The next step is to load the USB-ethernet module: # insmod ecos_usbeth.o This should result in a number of additional diagnostics in the logfile: Apr 1 18:01:08 grumpy kernel: eCos USB-ethernet device driver Apr 1 18:01:08 grumpy kernel: usb.c: registered new driver ecos_usbeth If a suitable USB peripheral is now connected the host will detect this, assign an address in the local USB network, obtain enumeration data, and find a suitable device driver. Assuming the peripheral and device driver agree on the supported vendor ids, the ecos_usbeth.o module will be selected and this will be reported in the system log: Apr 1 18:04:12 grumpy kernel: usb.c: USB new device connect, assigned device number 3 Apr 1 18:04:12 grumpy kernel: eCos-based USB ethernet peripheral active at eth1 What can happen next depends very much on the software that is running on top of the USB-ethernet package inside the peripheral. For example, if there is a TCP/IP stack then it should be possible to bring up a network connection between host and peripheral using ifconfig. Communication Protocol Communication Protocol Protocol used between the host-side device driver and the eCos USB-ethernet package There is a USB standard for the protocol to be used between the host and a class of communication devices, including ethernet. However, the eCos USB-ethernet package does not implement this protocol: the target hardware for which the package was first developed had certain limitations, and could not implement the standard. Instead, the package implements a simple new protocol. A USB-ethernet peripheral involves bulk transfers on two endpoints: one endpoint will be used for packets from host to peripheral and the other will be used for the opposite direction. Transfers in both directions are variable length, with a lower limit of 16 bytes and an upper limit of 1516 bytes. The first two bytes of each transfer constitute a header specific to USB-ethernet. The next 14 bytes form the normal header for an ethernet frame: destination MAC address, source MAC address, and a protocol field. The remaining data, up to 1500 bytes, are the payload. The first two bytes give the size of the ethernet frame, least significant byte first, with a value between 14 and 1514. For example an ARP request from host to peripheral involves an ethernet frame of 42 bytes (0x002A), with the usual 14-byte header and a 28-byte payload. The destination is the broadcast address 0xFFFFFFFFFFFF. The source depends on the MAC address specified for the host in the call to usbs_eth_init, e.g. 0x405D90A9BC02. The remaining data is as specified by the appropriate IETF RFC's. The actual bulk USB transfer involves the following sequence of 44 bytes: 2a 00 ff ff ff ff ff ff 40 5d 90 a9 bc 02 08 06 00 01 08 00 06 04 00 01 40 5d 90 a9 bc 02 0a 00 00 01 00 00 00 00 00 00 0a 00 00 02 In addition there are two control messages. These will be sent by the host to endpoint 0, the control endpoint, and by default they will be handled by usbs_eth_class_control_handler. If class-specific control messages are intercepted by other code then it is the responsibility of that code to invoke the USB-ethernet handler when appropriate. The first control message can be used by the host to obtain a MAC address: #define ECOS_USBETH_CONTROL_GET_MAC_ADDRESS 0x01 The control message's type field should specify IN as the direction. The request field should be 0x01. The length fields should specify a size of 6 bytes. The remaining fields of the control message will be ignored by the USB-ethernet package. The response consists of the 6-byte MAC address supplied by the initialization call usbs_eth_init. The second control message can be used by the host to enable or disable promiscuous mode. #define ECOS_USBETH_CONTROL_SET_PROMISCUOUS_MODE 0x02 This control message involves no further data so the length field should be set to 0. The value field should be non-zero to enable promiscuous mode, zero to disable it. The request field should be 0x02. The remaining fields in the control message will be ignored. It is the responsibility of the host-side device driver to keep track of whether or not promiscuous mode is currently enabled. It will be disabled when the peripheral changes to Configured state, typically at the point where the host-side device driver has been activated.