USB Integration of Transceivers

Transcription

1 USB Integration of Transceivers Yassine Lamrani Abou Elassad Computer Science Jacobs University Bremen Campus Ring Bremen Germany Type: Guided Research Thesis Date: May 7, 2009 Supervisor: Prof. Dr. Jürgen Schönwälder Page 1

2 Preface This document should give detailed description of how the USB subsystem works along with the API and functions used in writing a usb device driver. It starts with general definitions and information about the RZ raven kit, the IEEE standard and the Zigbee protocols before moving on to the theory behind usb driver coding. It explains the background behind the Universal Serial Bus and specifies the different types of devices and their classes along with some diagrams to summarize the theory. Afterwards, this report attempts to explain and provide the base code of how to write the USB driver for the Atmel Raven board. At the end, there will be a conclusion introducing possible future work, and references to the information used in here. Page 2

3 Table of Contents: 1. Executive Summery 4 2. Introduction 5 3. USB Background 3 4. Writing a USB driver 7 5. Coding the Atmel Raven Driver Future work and Conclusion (to be added) References 19 Page 3

4 1. Executive Summery AVRs have been, and are aimed to be, used in various domains such as Home Automation, Telecommunication Applications, personal, Home, and Hospital Care. AVRs have a large following due to the free and inexpensive development tools available, including reasonably priced development boards and free development software. One of the main evaluation kits using this controller family is the AVR Raven wireless kit. This kit supports wireless development using Atmel's IEEE chipsets, for ZigBee and other wireless stacks. The Zigbee protocols are intended for use in embedded applications requiring low data rates and low power consumption, which makes the AVR boards particularly useful in many areas. The AVR boards can be used in security, safety, powertrain and entertainment systems. In the automotive field, some current usages are in BMW, Daimler-Chrysler and TRW. So far, the AVR RZRAVEN 2.4 GHz Evaluation and Starter kit is only aimed for the windows operating system which is losing popularity amongst today s computer scientists as opposed to the Linux platforms. Linux is an open source operating system with many distributions specialized for different purposes, ranging from embedded systems to support of computer architecture. Today, the growth of Linux users has become remarkably imminent. As of 2007, most cell phones or PDAs, like Nokia N810, Motorola MING series, and the Google Android are running on Linux. The ELCPS (Embedded Linux Consortium Platform Specification) [3] has been produced by the Embedded Linux Consortium, offering a guide to embedded Linux devices developers. Providing support for the AVR Raven boards in Linux will facilitate the usage of the device within embedded systems and thereby increase its usage. The goal of this Research is the USB integration of the Atmel Raven board in Linux. Page 4

5 2. Introduction: Atmel Corporation [9], founded in 1984, is a manufacturer of semiconductors where its main focus is on system-level solutions built around flash microcontrollers. Its main products are microcontrollers such as 8051 derivatives, AT91SAM and AT91CAP ARM-based micros, and its own Atmel AVR and AVR32 architectures, radio frequency (RF) devices, EEPROM and Flash memory devices, along with many other application-specific products. Atmel has been able to offer system on chip solutions to its customers and serves a range of application segments; consumer, communications, computer networking, industrial, medical, automotive, aerospace and military. Atmel has also been considered an industry leader in secure systems, and especially for the smart card market. In 1996, Atmel has introduced the AVR microcontroller which used on-chip flash memory for program storage, as opposed to One-Time Programmable ROM, EPROM, or EEPROM used by other microcontrollers at the time. The AVR [10], or "Alf and Vegard's Risc", is a Modified Harvard architecture 8-bit RISC single chip microcontroller conceived by two students at the Norwegian Institute of Technology (NTH) Alf-Egil Bogen and Vegard Wollan. The Official Atmel AVR development tools and evaluation kits consists of a small number of starter kits and debugging tools with support for most AVR devices. The RAVEN kit (figure 0.1) supports wireless development using Atmel's IEEE chipsets, for ZigBee and other wireless stacks [10]. The kit serves as a versatile and professional platform for developing and debugging a wide range of RF applications; spanning from: simple point-to-point communication through full blown sensor networks with numerous nodes running complex communication stacks. It includes two AVR Raven boards (AVRRAVEN) which contain a 2.4 GHz transceiver supporting IEEE and a freely licensed ZigBee stack. These transceivers are driven with ATmega1284p processors, which are supported by a custom segmented LCD display driven by an ATmega3290p processor. Also the kit include one USB stick (AVRRZUSBSTICK) with a 2.4 GHz transceiver for USB connection to a host computer. The USB stick uses an AT90usb1287 for connections to a USB host and to the 2.4 GHz wireless links. ZigBee is a low-cost, low-power, wireless standard [11]. It operates in the industrial, scientific and medical (ISM) radio bands and intended for use in embedded applications requiring low data rates and low power consumption. It is oriented towards defining an inexpensive, general purpose self-organizing mesh network that Page 5

6 can be widely used which would provide high reliability and larger range. Some of the application areas of Zigbee include: Home Entertainment and Control Smart lighting, advanced temperature control, safety and security, movies and music Home Awareness Water sensors, power sensors, smoke and fire detectors, smart appliances and access sensors Mobile Services m-payment, m-monitoring and control, m-security and access control, m-healthcare and tele-assist Commercial Building Energy monitoring, HVAC, lighting, access control Industrial Plant Process control, asset management, environmental management, energy management, industrial device control The IEEE is the standard defining the protocol and interconnection of devices via radio communication in a personal area network (PAN) [12]. It uses carrier sense multiple access with collision avoidance (CSMA-CA) and offers support to the star and peer to peer topologies. Lately, the IEEE standard includes two optional physical layers (PHYs) for an overall of four PHYS, thus yielding higher data rates in the lower frequency bands. In general the IEEE devices are used primarily on embedded systems, where Linux has become a major force. The aim of this project was to implement a USB driver for Linux for the AVR Raven Boards. This part of the research deals with registering the USB driver and being able to detect the AVR Raven as a networking device for latter use and development. Figure 2.1: the AVR Raven kit Page 6

7 3. USB Background: The USB or Universal Serial Bus [1] is a serial bus standard which serves as a connection between a host computer and a number of peripheral devices. It was originally intended to replace many slow and different buses, namely the serial and parallel connections with a single standardized socket. The Topology of a USB subsystem consists of a tree built out of four point-topoint links: ground, power, and two signal wires. When plugging a USB device to a computer, the USB host controller ask the device if it has any data to send. The USB device never starts sending data without first being asked by the host controller. This configuration improves plug and play capabilities by allowing host swapping. Devices can be added and removed without the need to reboot the system or being turned off while they also can be automatically configured by the host computer. Other features of USB include: Providing power to low consumption devices via the ground and power cables, The ability for a device to request a fixed bandwidth for its data transfers resulting in high reliably with respect to video and audio I/O. USB acts merely as a communication channel between the device and the host, thus no specific meaning or structure to the data it delivers is required. USB is considered to be very simple at the technological level because of its aspect of being a single-master implementation in which the host computer polls the various peripheral devices. Many USB devices can be used without the need for a manufacturer-specific driver to be installed. This is the case when the device follows the standard defined by the USB protocol specifications. More precisely, there are different types of devices. USB defines class codes used to identify these types (storage devices, keyboards, mice, network devices...) and load a driver based on the device functionality. However, there are other types of devices that don t fit into the device classes defined by the USB protocol. Each vendor decides to implement a custom protocol to talk to their device, so a custom driver usually needs to be created[1]. Figure 1.1 shows the different types of classes used to map the USB device to a specific driver. The Atmel Raven boards may be considered to be of the 02h class since they constitute a communication device similar to the other networking tools. However, the Raven boards take in special commands as input and give different outputs than that of a simple networking device (e.g. modem or network card). Therefore, the Atmel Raven boards fall under the FFH class where a vendor specific driver is needed to communicate with the device. Page 7

8 In general the Linux kernel offers support to two main types of USB drivers: drivers on a host system and drivers on a device. The USB drivers for a host system allow control over the USB devices plugged into the host computer. On the other hand, the USB drivers in a device control how the device looks to the host computer as a USB device. This type of drivers has been assigned the name USB gadget drivers to differentiate it from the USB device drivers aimed for the host system. It is assumed that a USB gadget driver is already provided for the Atmel RZ Raven boards and thus this research focuses on the USB system description and the Atmel Raven driver coding for the Linux operating system. Figure 1.2 shows how the USB drivers live between the kernel subsystems and the USB hardware controllers (USB core and USB host controller) in Linux. The USB core has a specific applications programming interface (API) to support USB devices and host controllers. Its utility resides in providing an interface for USB drivers to use to access and control the USB devices independently of the types of USB hardware controllers that are used. Figure 3.1: Description of different types of classes used to define the functionality of USB devices[13]. Page 8

9 Figure 3.2: overview of USB drivers [1]. The interaction between the USB core and the USB driver is made through the USB descriptors: Endpoints, Interfaces, and configurations. Endpoints Endpoints [2] are the means for the most basic form of USB communication. An endpoint is a logical entity on the device, and can be considered as unidirectional pipes, carrying data either from the device to the host computer (IN endpoint) or from the host computer to the device (OUT endpoint). We can differentiate between four different types of endpoints, namely: Control endpoints: a simple endpoint type, used to configure the device, retrieve information about it and send commands to it. This kind of endpoint is common amongst all devices which then use it to configure themselves at insertion time. Moreover, it is guaranteed that the USB protocol will always reserve enough bandwidth for the corresponding data transfer. Interrupt endpoints: guarantee reserved bandwidth for data transfer whenever the host asks the device for data. It is commonly used by devices that constantly require guaranteed response time such as keyboards and mice. Bulk endpoints: these use all the bandwidth left over promising no data loss, however, offering no guarantee on bandwidth or latency. Mostly used for printers and network devices. Page 9

10 Isochronous endpoints: used when large amounts of data are needed to be transferred rapidly, such as the case of audio and video devices, with a tradeoff between speed and guaranteed data transfer. The type and address of the endpoint and the maximum packet size in bytes the endpoint can handle at once is given by the _u8 bmattributes, bendpointaddress, and wmaxpacketsize fields under the usb_endpoint_descriptor structure [1] in the kernel. This structure contains all of the USB-specific data which is written in the exact format that the device specifies. Interfaces A device might provide several applications (e.g., a webcam with integrated microphone). In this case, an interface is assigned to each high-level function and one driver is needed for every interface [2]. In general, Endpoints are bundled up into Interfaces. These USB interfaces are described in the kernel with the struct usb_interface structure which is passed by the USB core to USB drivers. The USB driver is then in charge for controlling this interface. We note the following important fields inside this structure to be [1]: struct usb_host_interface *altsetting : An array of interface structures containing all of the alternate settings that may be selected for this interface. unsigned num_altsetting: The number of alternate settings pointed to by the altsetting pointer. struct usb_host_interface *cur_altsetting: A pointer into the array altsetting, denoting the currently active setting for this interface. int minor: If the USB driver bound to this interface uses the USB major number, this variable contains the minor number assigned by the USB core to the interface. Alternate settings describe the different choices for parameters of the interface. They can be used to control individual endpoints in different ways, such as to reserve different amounts of USB bandwidth for the device. Configurations USB interfaces are bundled up into Configurations. The USB device can have many configurations and changing the state of the device implies switching the configuration of the device. USB configurations are described with the structure struct usb_host_config. Finally, configurations are bundled up into a USB device described with the struct usb_device structure. Figure 1.3 shows how a USB device consists of Page 10

11 configurations, interfaces, and endpoints and how the USB drivers bind to USB interfaces rather than the entire USB device. Figure 3.3: overview of a USB Device (USB webcam)[2]. Atmel RZ Raven USB basics: Endpoint type: Bulk Interfaces: Communications, CDC Control. Configurations: Active, Standby Note that the same interfaces describes the 02h class from the device classes table in figure 1.1. However, the Atmel RZ Raven board falls under the FFh class since no matching driver is registered for Atmel vendor ID and Product ID of the RZ raven board. The purpose of this research is then to identify the approach used to write the USB driver for the Atmel RZ raven board and creating a USB driver able to identify it as a networking device and establish a simple communication with it. Page 11

12 4. Writing a USB driver: The approach behind writing a USB driver is based on the driver registering the USB device it is meant for with the USB subsystem and using the vendor and device identification later to detect the USB device at plug in time[1]. The driver also defines which functions to call when the device it supports is inserted or removed from the system The list of devices that the USB driver supports is written under the struct usb_device_id structure. The USB core uses this list to decide which driver to assign a device while the hotplug scripts use this same list to decide which driver to automatically load for a specific device at plug in time. The important fields (related to our driver code) defining the struct usb_device_id structure to note are [1]: u16 idvendor: The USB vendor ID for the device. This number is assigned by the USB forum to its members and cannot be made up by anyone else. u16 idproduct: The USB product ID for the device. u8 binterfaceclass u8 binterfacesubclass u8 binterfaceprotocol These define the class, subclass, and protocol of the individual interface, respectively. Two important macros that are used to initialize this structure are [1]: USB_DEVICE(vendor, product): This Creates a struct usb_device_id that can be used to match only the specified vendor and product ID values of a USB device to its driver. USB_I TERFACE_I FO(class, subclass, protocol): This Creates a struct usb_device_id that can be used to match a specific class of USB interfaces identifying the functionalities of a USB device. Since Raven boards need a specific driver, we will be using the USB_DEVICE(vendor, product) macro. To Define the struct usb_device_id table for a USB device driver defining a device with provided vendor and product identification, [1] we would write: Page 12

13 /* table of devices that work with this driver */ static struct usb_device_id skel_table [ ] = { { USB_DEVICE(USB_SKEL_VE DOR_ID, USB_SKEL_PRODUCT_ID) }, { } /* Terminating entry */ }; MODULE_DEVICE_TABLE (usb, skel_table); /* this macro allows user-space tools to figure out what devices this driver can control */ Registering a USB driver is nothing else other than describing the USB driver to the USB core [1]. This is done via the struct usb_driver structure which contains the usb_device_id table defined earlier along with other function callbacks and variables that describe the driver. The most important function and variables are as follows [1]: struct module *owner: Pointer to the module owner of the driver. const char *name: Pointer to the name of the driver. The name is usually set to the same name of the module of the driver to ensure its uniqueness amongst all USB drivers in the kernel. It shows up in sysfs under /sys/bus/usb/drivers/ when the driver is in the kernel. const struct usb_device_id *id_table: Pointer to the struct usb_device_id table. int (*probe) (struct usb_interface *intf, const struct usb_device_id *id): Pointer to the probe function in the USB driver. This function is called by the USB core when it thinks it has a struct usb_interface that this driver can handle. A pointer to the struct usb_device_id that the USB core used to make this decision is also passed to this function. If the USB driver claims the struct usb_interface that is passed to it, it should initialize the device properly and return 0. If the driver does not want to claim the device, or an error occurs, it should return a negative error value. void (*disconnect) (struct usb_interface *intf): Pointer to the disconnect function in the USB driver. This function is called by the USB core at deregistration: when the struct usb_interface has been removed from the system or when the driver is being unloaded from the USB core. Page 13

14 Creating the struct usb_driver structure [3] is made as follows: static struct usb_driver skel_driver = {.owner = THIS_MODULE,.name = "skeleton",.id_table = skel_table,.probe = skel_probe,.disconnect = skel_disconnect, }; The registration of the struct usb_driver with the USB core is made via the usb_register_driver call with a pointer to the struct usb_driver as argument. The deregistration is made via a call to usb_deregister_driver with the same struct usb_driver argument [3]. Both the two calls are done within the module initialization code for the USB driver: /*registering driver*/ static int init usb_skel_init(void) { int result; /* register this driver with the USB subsystem */ result = usb_register(&skel_driver); if (result) err("usb_register failed. Error number %d", result); return result; } /*deregistring driver*/ static void exit usb_skel_exit(void) { /* deregister this driver with the USB subsystem */ usb_deregister(&skel_driver); } Page 14

15 5. Coding the Atmel Raven Driver The base code skeleton of the Raven board USB driver is as follows: struct RZraven_device { /* local structure used to save data about the Atmel Raven board */ }; static void write_bulk_callback(struct urb *urb){ /* function called when the USB request block (urb) call succeeds */ } static void RZraven_disconnect(struct usb_device *udev, void *clientdata){ /* function called when the Raven USB stick is disconnected */ } static void *RZraven_probe(struct usb_device *udev, unsigned int ifnum, const struct usb_device_id *id){ /* function called when the Raven USB stick is connected. Also this is where the urb transmition is made. */ } static struct usb_device_id RZraven_id_table [] = { /* this list contains information about the Atmel Raven product Vendor ID to match against when the Raven USB stick is connected*/ }; static struct usb_driver RZraven_usb_driver = { /* structure used to register the callbacks. */ }; int RZraven_init(void){ /* function called at module load time*/ } void RZraven_exit(void){ /*function called at module unload time */ } module_init(rzraven_init); module_exit(rzraven_exit); Page 15

16 The general control flow of the driver is illustrated by the following sequence diagram: Figure 5.1: self explanatory sequence diagram describing the control flow of the USB driver starting from the plug-in time of the device to the unplug time. Page 16

17 The driver code is provided as annex with the full explanation. After successfully installing the Raven driver (raven2021) the user should be able to see that the raven board was detected. [6] The output of dmesg should resemble: usb 5-2: new full speed USB device using uhci_hcd and address 29 usb 5-2: configuration #1 chosen from 1 choice rndis_host 5-2:1.0: dev can't take 1338 byte packets (max 1338), adjusting MTU to 1280 usb0: register 'rndis_host' at usb-0000:00:1d.3-2, RNDIS device, 02:12:13:14:15:16 cdc_acm 5-2:1.2: ttyacm0: USB ACM device usb 5-2: New USB device found, idvendor=03eb, idproduct=2021 usb 5-2: New USB device strings: Mfr=1, Product=2, SerialNumber=3 usb 5-2: Product: RZRAVEN USB DEMO usb 5-2: Manufacturer: Atmel usb 5-2: SerialNumber: The code is only meant to detect the Raven board and be able to read any messages it spits out and also write to it via the IN and OUT bulk endpoints. Further development include defining the commands for interacting with the Raven board and the debug bits (e.g. via reverse engineering). As an example, the following are some of the at76_debug bits for the Atmel 76c50x WLAN driver [5]: #define DBG_PROGRESS 0x /* authentication/accociation */ #define DBG_BSS_TABLE 0x /* show BSS table after scans */ #define DBG_IOCTL 0x /* ioctl calls / settings */. The commands and debug bits can then be used to extend the probe() function and build on the base code provided to complete the USB driver for the Raven board Page 17

18 6. Future work and conclusion: The provided code is not complete yet. However, it constitutes a perfect skeleton for further work. It will be made public, and future developers may use it as base to their code. This was the insinuated intention behind this research since it tackles more the aspects of general USB driver coding than the actual networking details of the AVR Raven boards. Furthermore, this document also introduces the hardware in question and defines two of the main related standards to it: the IEEE and Zigbee. We should note that it is often hard to collect information about a certain subject of rare or abstract resources. Even though, the Linux USB driver coding subject is rather popular, most articles provide too much abstraction with little examples or examples with little abstraction. This document comes as a mediator between the two cases. It is also oriented towards the specific driver coding for the Raven board. Future implementers will surely be able to relate to this work. Devices supporting the IEEE standard are becoming more and more popular (e.g. the Nanoloc TRX transceiver). This research should allow me to further investigate the usage of such devices and implement a Linux USB driver for them accordingly. Such knowledge will prove to be very important when trying to integrate the computer science industry. I should be able to work on it more intensively during the upcoming summer vacation while keeping it as an open source. It may be possible to find other interested parties, and the coding could be done in parallel with other implementers. Current developments regarding the utilization of Raven boards under Linux is available under Contiki. Further reading about this can be found in here: [14]. In any case, there doesn t seem to be any open current basis to the USB driver implementation for the Raven boards like the other vendor specific drivers. This could be the start. And not too long from now, we should be able to have the complete code for download and compiling. Page 18

19 7. References: [1] Jonathan Corbet; Alessandro and Rubini; and Greg Kroah-Hartman (2005). Linux Device Drivers, O Reilly Media (3rd_edition). [2] Michael Opdenacker (2007). Linux USB drivers, Free Electrons. Available at: [3] Matthias Vallentin (2007). Writing a Linux kernel driver for an unknown USB device. Available at: [4] Greg Kroah-Hartman (2001). How to Write a Linux USB Device Drive. Available at: [5] Linux driver for Atmel AT76C503/AT76C505 based USB WLAN adapters. Available at: [6] RZRAVEN USB Stick (Jackdaw). Available at: [7] Detlef Fliegl (2000). Programming Guide for Linux USB Device Drivers, Available at: [8] ATAVRRZRAVEN 2.4 GHz Evaluation and Starter Kit Available at: [9] Wikipedia (2009). Atmel. Available at: [10] Wikipedia (2009). Atmel AVR. Available at: [11] Wikipedia (2009). Zigbee. Available at: [12] Wikipedia (2009). IEEE Available at: [13] Wikipedia (2009). USB. Available at: [14] Rahul Jain (2009). Linux Integration of Networks. Page 19