Richard Collins / USBHostControllerDriver

UsbHost.h@2:33e7ce63dd6d, 2012-09-19 (annotated)

Committer:
RichardUK
Date:
Wed Sep 19 16:44:32 2012 +0000
Revision:
2:33e7ce63dd6d
Parent:
1:4461071ed964 
Testing lib update to another project.

Who changed what in which revision?

UserRevisionLine numberNew contents of line
RichardUK 0:63d45df56584 1 /**
RichardUK 0:63d45df56584 2 A host controller driver from the mBed device.
RichardUK 0:63d45df56584 3 Copyright (C) 2012 Richard e Collins - richard.collins@linux.com
RichardUK 0:63d45df56584 4
RichardUK 0:63d45df56584 5 This program is free software: you can redistribute it and/or modify
RichardUK 0:63d45df56584 6 it under the terms of the GNU General Public License as published by
RichardUK 0:63d45df56584 7 the Free Software Foundation, either version 3 of the License, or
RichardUK 0:63d45df56584 8 (at your option) any later version.
RichardUK 0:63d45df56584 9
RichardUK 0:63d45df56584 10 This program is distributed in the hope that it will be useful,
RichardUK 0:63d45df56584 11 but WITHOUT ANY WARRANTY; without even the implied warranty of
RichardUK 0:63d45df56584 12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
RichardUK 0:63d45df56584 13 GNU General Public License for more details.
RichardUK 0:63d45df56584 14
RichardUK 0:63d45df56584 15 You should have received a copy of the GNU General Public License
RichardUK 0:63d45df56584 16 along with this program. If not, see <http://www.gnu.org/licenses/>.
RichardUK 0:63d45df56584 17
RichardUK 0:63d45df56584 18 I have written this lib for two reasons, 1 so that I have code that I know works and 2 because I wanted to learn USB.
RichardUK 0:63d45df56584 19 The first release is unfinished due to the lack of time to test all the transfer types. As and when I find time
RichardUK 0:63d45df56584 20 to implement the other parts I will update the lib. I hope this should be finished by June 2012. I 'hope' ;)
RichardUK 0:63d45df56584 21
RichardUK 0:63d45df56584 22 Some of the comments and enums / structs taken from the libusb project. libusb.org
RichardUK 0:63d45df56584 23
RichardUK 0:63d45df56584 24 Also borrowed some bits from http://www.beyondlogic.org/usbnutshell A very good read.
RichardUK 0:63d45df56584 25
RichardUK 0:63d45df56584 26 Another good read. http://www.usbmadesimple.co.uk/ums_4.htm (took some comments from here too)
RichardUK 0:63d45df56584 27
RichardUK 0:63d45df56584 28 I also used the code in USBHost as a reference although it is a little unstructured and has some bad coding habbits in to so I would recommend advoiding that code.
RichardUK 0:63d45df56584 29 */
RichardUK 0:63d45df56584 30
RichardUK 0:63d45df56584 31
RichardUK 0:63d45df56584 32 #ifndef __USBHOST_H__
RichardUK 0:63d45df56584 33 #define __USBHOST_H__
RichardUK 0:63d45df56584 34
RichardUK 0:63d45df56584 35 #include "UsbHostController.h"
RichardUK 0:63d45df56584 36 #include "UsbEnums.h"
RichardUK 0:63d45df56584 37 #include "UsbStructures.h"
RichardUK 0:63d45df56584 38
RichardUK 0:63d45df56584 39 namespace USB
RichardUK 0:63d45df56584 40 {
RichardUK 0:63d45df56584 41
RichardUK 0:63d45df56584 42
RichardUK 0:63d45df56584 43
RichardUK 0:63d45df56584 44 #define MAX_DEVICES 4
RichardUK 0:63d45df56584 45 #define DEFAULT_TIMEOUT 500
RichardUK 0:63d45df56584 46
RichardUK 0:63d45df56584 47 //Some forward definitions of types. Done so we don't have to include all the headers. Helps to stop include spaghetti.
RichardUK 0:63d45df56584 48 struct HostController;
RichardUK 0:63d45df56584 49 struct Device;
RichardUK 0:63d45df56584 50 struct DeviceDescriptor;
RichardUK 1:4461071ed964 51 struct TransferCallback;
RichardUK 0:63d45df56584 52
RichardUK 0:63d45df56584 53 struct Host : HostControllerMessages
RichardUK 0:63d45df56584 54 {
RichardUK 0:63d45df56584 55
RichardUK 0:63d45df56584 56 Host();
RichardUK 0:63d45df56584 57 ~Host();
RichardUK 0:63d45df56584 58
RichardUK 0:63d45df56584 59 /**
RichardUK 0:63d45df56584 60 * Polls the driver so it can get some if it's non interupt work done.
RichardUK 0:63d45df56584 61 */
RichardUK 0:63d45df56584 62 virtual void Update();
RichardUK 0:63d45df56584 63
RichardUK 0:63d45df56584 64 /**
RichardUK 0:63d45df56584 65 * Fetches the device description, this is the basic structure returned by the device.
RichardUK 0:63d45df56584 66 */
RichardUK 0:63d45df56584 67 int getDeviceDescriptor(int deviceID,DeviceDescription &description);
RichardUK 0:63d45df56584 68
RichardUK 0:63d45df56584 69 /**
RichardUK 0:63d45df56584 70 * The memory pointer returned is a block of memory for the configurtaion and it's interfaces and their endpoints as one block.
RichardUK 0:63d45df56584 71 */
RichardUK 0:63d45df56584 72 const uint8_t* getConfigurationDescriptor(int deviceID,int index);
RichardUK 0:63d45df56584 73
RichardUK 0:63d45df56584 74 /**
RichardUK 0:63d45df56584 75 * Fetches the string at the passed index.
RichardUK 0:63d45df56584 76 */
RichardUK 0:63d45df56584 77 const char* getStringDescriptor(int deviceID,int index);
RichardUK 0:63d45df56584 78
RichardUK 0:63d45df56584 79 /**
RichardUK 0:63d45df56584 80 * Sets the configuration to be used.
RichardUK 0:63d45df56584 81 */
RichardUK 0:63d45df56584 82 int setConfiguration(int deviceID,int configuration);
RichardUK 0:63d45df56584 83
RichardUK 0:63d45df56584 84 /**
RichardUK 0:63d45df56584 85 * Perform a USB control transfer.
RichardUK 0:63d45df56584 86 * The direction of the transfer is inferred from the requestType field of the setup packet.
RichardUK 0:63d45df56584 87 * Function is blocking, will return with result or fail on error or timeout.
RichardUK 0:63d45df56584 88 *
RichardUK 0:63d45df56584 89 * TODO: Code needs error codes and error checking such as is the data size larger than the EP allows (ok don't need to check as the device will respond with multiple packets)
RichardUK 0:63d45df56584 90 *
RichardUK 0:63d45df56584 91 * @param device a handle for the device to communicate with
RichardUK 0:63d45df56584 92 * @param requestType the request type field for the setup packet
RichardUK 0:63d45df56584 93 * @param bRequest the request field for the setup packet
RichardUK 0:63d45df56584 94 * @param value the value field for the setup packet
RichardUK 0:63d45df56584 95 * @param index the index field for the setup packet
RichardUK 0:63d45df56584 96 * @param data a suitably-sized data buffer for either input or output (depending on direction bits within requestType)
RichardUK 0:63d45df56584 97 * @param length the length field for the setup packet. The data buffer should be at least this size.
RichardUK 0:63d45df56584 98 * @param timeout timeout (in millseconds) that this function should wait before giving up due to no response being received. For an unlimited timeout, use value 0. (currently does nothing)
RichardUK 0:63d45df56584 99 */
RichardUK 0:63d45df56584 100 int ControlTransfer(int deviceID,uint8_t requestType, uint8_t request, uint16_t value, uint16_t index,const uint8_t *data, uint16_t length, uint32_t timeout);
RichardUK 0:63d45df56584 101
RichardUK 0:63d45df56584 102 /**
RichardUK 0:63d45df56584 103 * Perform a USB bulk transfer.
RichardUK 0:63d45df56584 104 * The direction of the transfer is inferred from the direction bits of the endpoint address.
RichardUK 0:63d45df56584 105 * For bulk reads, the length field indicates the maximum length of data you are expecting to receive. If less data arrives than expected, this function will return that data, so be sure to check the transferred output parameter.
RichardUK 0:63d45df56584 106 * You should also check the transferred parameter for bulk writes. Not all of the data may have been written.
RichardUK 0:63d45df56584 107 * Also check transferred when dealing with a timeout error code. libusb may have to split your transfer into a number of chunks to satisfy underlying O/S requirements, meaning that the timeout may expire after the first few chunks have completed. libusb is careful not to lose any data that may have been transferred; do not assume that timeout conditions indicate a complete lack of I/O.
RichardUK 0:63d45df56584 108 *
RichardUK 0:63d45df56584 109 * @param device A handle for the device to communicate with
RichardUK 0:63d45df56584 110 * @param endpoint The address of a valid endpoint to communicate with
RichardUK 0:63d45df56584 111 * @param data A suitably-sized data buffer for either input or output (depending on endpoint)
RichardUK 0:63d45df56584 112 * @param length For bulk writes, the number of bytes from data to be sent. for bulk reads, the maximum number of bytes to receive into the data buffer.
RichardUK 0:63d45df56584 113 * @param callbackID If set then when the transfer is complete the callback will be called with this ID and the information about the transfer.
RichardUK 0:63d45df56584 114 */
RichardUK 1:4461071ed964 115 int BulkTransfer(int device,uint8_t endpoint,const uint8_t* data,int length,TransferCallback* callback = NULL);
RichardUK 0:63d45df56584 116
RichardUK 0:63d45df56584 117 /**
RichardUK 0:63d45df56584 118 * When a usb device is connected this is called.
RichardUK 0:63d45df56584 119 */
RichardUK 0:63d45df56584 120 virtual void onConnected(int deviceID,const DeviceDescription& description) = 0;
RichardUK 0:63d45df56584 121
RichardUK 0:63d45df56584 122 /**
RichardUK 0:63d45df56584 123 * Called when a device disconnects from the system.
RichardUK 0:63d45df56584 124 */
RichardUK 0:63d45df56584 125 virtual void onDisconnected(int deviceID) = 0;
RichardUK 0:63d45df56584 126
RichardUK 0:63d45df56584 127 protected:
RichardUK 0:63d45df56584 128
RichardUK 0:63d45df56584 129 virtual void AddDevice(int hub,int port,int hubPortStatus);
RichardUK 0:63d45df56584 130 virtual void TransferDone(TransferDescriptor *transfer);
RichardUK 0:63d45df56584 131
RichardUK 0:63d45df56584 132 private:
RichardUK 0:63d45df56584 133 HostController* driver;
RichardUK 0:63d45df56584 134 Device *devices[MAX_DEVICES];
RichardUK 0:63d45df56584 135
RichardUK 0:63d45df56584 136 /**
RichardUK 0:63d45df56584 137 * The way the hardware and the spec is designed there is only one device in setup mode.
RichardUK 0:63d45df56584 138 * This device will be the only one to respond to requests.
RichardUK 0:63d45df56584 139 * To keep the code simple, that is not having a different code path for device zero
RichardUK 0:63d45df56584 140 * I use this struct for the init phase.
RichardUK 0:63d45df56584 141 */
RichardUK 0:63d45df56584 142 Device* deviceZero;
RichardUK 0:63d45df56584 143
RichardUK 0:63d45df56584 144 /**
RichardUK 0:63d45df56584 145 * Allocates the device from the memory pool on the driver and put it in our array.
RichardUK 0:63d45df56584 146 * Because the array size is fixed (for speed and memory) this function may return NULL
RichardUK 0:63d45df56584 147 * when more than MAX_DEVICES is connected.
RichardUK 0:63d45df56584 148 */
RichardUK 0:63d45df56584 149 Device* AllocateDevice(int endpointZeroMaxPacketSize,int hubPortStatus);
RichardUK 0:63d45df56584 150
RichardUK 0:63d45df56584 151 void SendControlTransferData(Device* device,int dataToggle);
RichardUK 0:63d45df56584 152 void SendControlTransferAcknowledge(Device* device,int dataToggle);
RichardUK 0:63d45df56584 153
RichardUK 0:63d45df56584 154 /**
RichardUK 0:63d45df56584 155 * ID is one based, array is zero based. Device zero is the host controller and a reserved ID as per the host controller spec.
RichardUK 0:63d45df56584 156 * Returns the device or NULL if the ID is invalid or device is now disconnected. (device pointer will be NULL when disconnected)
RichardUK 0:63d45df56584 157 * If deviceID is zero then a pointer to the 'deviceZero' object is returned.
RichardUK 0:63d45df56584 158 */
RichardUK 0:63d45df56584 159 Device* getDevice(int deviceID);
RichardUK 0:63d45df56584 160
RichardUK 0:63d45df56584 161
RichardUK 0:63d45df56584 162 };//class Controller
RichardUK 0:63d45df56584 163
RichardUK 0:63d45df56584 164 };//namespace USB
RichardUK 0:63d45df56584 165
RichardUK 0:63d45df56584 166 #endif