RNDIS.h 10.8 KB
 Dean Camera committed May 08, 2010 1 2 /* LUFA Library  Dean Camera committed Jan 01, 2011 3  Copyright (C) Dean Camera, 2011.  4   Dean Camera committed May 08, 2010 5  dean [at] fourwalledcubicle [dot] com  Dean Camera committed Oct 28, 2010 6  www.lufa-lib.org  Dean Camera committed May 08, 2010 7 8 9 */ /*  Dean Camera committed Jan 01, 2011 10  Copyright 2011 Dean Camera (dean [at] fourwalledcubicle [dot] com)  Dean Camera committed May 08, 2010 11   12  Permission to use, copy, modify, distribute, and sell this  Dean Camera committed May 08, 2010 13  software and its documentation for any purpose is hereby granted  14  without fee, provided that the above copyright notice appear in  Dean Camera committed May 08, 2010 15  all copies and that both that the copyright notice and this  16 17 18  permission notice and warranty disclaimer appear in supporting documentation, and that the name of the author not be used in advertising or publicity pertaining to distribution of the  Dean Camera committed May 08, 2010 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35  software without specific, written prior permission. The author disclaim all warranties with regard to this software, including all implied warranties of merchantability and fitness. In no event shall the author be liable for any special, indirect or consequential damages or any damages whatsoever resulting from loss of use, data or profits, whether in an action of contract, negligence or other tortious action, arising out of or in connection with the use or performance of this software. */ /** \file * \brief Device mode driver for the library USB RNDIS Class driver. * * Device mode driver for the library USB RNDIS Class driver. *  Dean Camera committed Oct 24, 2010 36 37  * \note This file should not be included directly. It is automatically included as needed by the USB module driver * dispatch header located in LUFA/Drivers/USB.h.  Dean Camera committed May 08, 2010 38 39 40  */ /** \ingroup Group_USBClassRNDIS  Dean Camera committed Feb 19, 2011 41  * \defgroup Group_USBClassRNDISDevice RNDIS Class Device Mode Driver  Dean Camera committed May 08, 2010 42 43 44  * * \section Sec_Dependencies Module Source Dependencies * The following files must be built with any user project that uses this module:  Dean Camera committed Jul 19, 2010 45  * - LUFA/Drivers/USB/Class/Device/RNDIS.c (Makefile source module name: LUFA_SRC_USBCLASS)  Dean Camera committed May 08, 2010 46  *  Dean Camera committed Dec 26, 2010 47  * \section Sec_ModDescription Module Description  Dean Camera committed May 08, 2010 48 49 50 51 52 53 54 55 56 57 58  * Device Mode USB Class driver framework interface, for the RNDIS USB Class driver. * * @{ */ #ifndef _RNDIS_CLASS_DEVICE_H_ #define _RNDIS_CLASS_DEVICE_H_ /* Includes: */ #include "../../USB.h" #include "../Common/RNDIS.h"  59   Dean Camera committed May 08, 2010 60 61 62 63 64 65 66  /* Enable C linkage for C++ Compilers: */ #if defined(__cplusplus) extern "C" { #endif /* Preprocessor Checks: */ #if !defined(__INCLUDE_FROM_RNDIS_DRIVER)  Dean Camera committed Oct 24, 2010 67  #error Do not include this file directly. Include LUFA/Drivers/USB.h instead.  Dean Camera committed May 08, 2010 68  #endif  69   Dean Camera committed May 08, 2010 70  /* Public Interface - May be used in end-application: */  71  /* Type Defines: */  Dean Camera committed May 08, 2010 72 73 74 75  /** \brief RNDIS Class Device Mode Configuration and State Structure. * * Class state structure. An instance of this structure should be made for each RNDIS interface * within the user application, and passed to each of the RNDIS class driver functions as the  Dean Camera committed Jan 08, 2011 76  * \c RNDISInterfaceInfo parameter. This stores each RNDIS interface's configuration and state information.  Dean Camera committed May 08, 2010 77 78 79 80 81  */ typedef struct { const struct {  Dean Camera committed Jun 17, 2010 82  uint8_t ControlInterfaceNumber; /**< Interface number of the CDC control interface within the device. */  Dean Camera committed May 08, 2010 83   Dean Camera committed Jun 17, 2010 84 85 86  uint8_t DataINEndpointNumber; /**< Endpoint number of the CDC interface's IN data endpoint. */ uint16_t DataINEndpointSize; /**< Size in bytes of the CDC interface's IN data endpoint. */ bool DataINEndpointDoubleBank; /**< Indicates if the RNDIS interface's IN data endpoint should use double banking. */  Dean Camera committed May 08, 2010 87   Dean Camera committed Jun 17, 2010 88 89 90  uint8_t DataOUTEndpointNumber; /**< Endpoint number of the CDC interface's OUT data endpoint. */ uint16_t DataOUTEndpointSize; /**< Size in bytes of the CDC interface's OUT data endpoint. */ bool DataOUTEndpointDoubleBank; /**< Indicates if the RNDIS interface's OUT data endpoint should use double banking. */  Dean Camera committed May 08, 2010 91   Dean Camera committed Jun 17, 2010 92 93 94  uint8_t NotificationEndpointNumber; /**< Endpoint number of the CDC interface's IN notification endpoint, if used. */ uint16_t NotificationEndpointSize; /**< Size in bytes of the CDC interface's IN notification endpoint, if used. */ bool NotificationEndpointDoubleBank; /**< Indicates if the RNDIS interface's notification endpoint should use double banking. */  95   Dean Camera committed Jun 17, 2010 96 97 98  char* AdapterVendorDescription; /**< String description of the adapter vendor. */ MAC_Address_t AdapterMACAddress; /**< MAC address of the adapter. */ } Config; /**< Config data for the USB class interface within the device. All elements in this section.  Dean Camera committed May 08, 2010 99 100 101 102 103  * must be set or the interface will fail to enumerate and operate correctly. */ struct { uint8_t RNDISMessageBuffer[RNDIS_MESSAGE_BUFFER_SIZE]; /**< Buffer to hold RNDIS messages to and from the host,  Dean Camera committed Jun 17, 2010 104  * managed by the class driver.  Dean Camera committed May 08, 2010 105  */  Dean Camera committed Jun 17, 2010 106  bool ResponseReady; /**< Internal flag indicating if a RNDIS message is waiting to be returned to the host. */  Dean Camera committed Oct 12, 2010 107  uint8_t CurrRNDISState; /**< Current RNDIS state of the adapter, a value from the \ref RNDIS_States_t enum. */  Dean Camera committed Jun 17, 2010 108  uint32_t CurrPacketFilter; /**< Current packet filter mode, used internally by the class driver. */  Dean Camera committed May 08, 2010 109 110 111 112  } State; /**< State data for the USB class interface within the device. All elements in this section * are reset to their defaults when the interface is enumerated. */ } USB_ClassInfo_RNDIS_Device_t;  113   Dean Camera committed May 08, 2010 114 115 116 117 118  /* Function Prototypes: */ /** Configures the endpoints of a given RNDIS interface, ready for use. This should be linked to the library * \ref EVENT_USB_Device_ConfigurationChanged() event so that the endpoints are configured when the configuration * containing the given HID interface is selected. *  Dean Camera committed Sep 30, 2010 119 120 121 122  * \note The endpoint index numbers as given in the interface's configuration structure must not overlap with any other * interface, or endpoint bank corruption will occur. Gaps in the allocated endpoint numbers or non-sequential indexes * within a single interface is allowed, but no two interfaces of any type have have interleaved endpoint indexes. *  Dean Camera committed Jun 17, 2010 123  * \param[in,out] RNDISInterfaceInfo Pointer to a structure containing a RNDIS Class configuration and state.  Dean Camera committed May 08, 2010 124  *  Dean Camera committed Jan 08, 2011 125  * \return Boolean \c true if the endpoints were successfully configured, \c false otherwise.  Dean Camera committed May 08, 2010 126 127 128 129  */ bool RNDIS_Device_ConfigureEndpoints(USB_ClassInfo_RNDIS_Device_t* const RNDISInterfaceInfo) ATTR_NON_NULL_PTR_ARG(1); /** Processes incoming control requests from the host, that are directed to the given RNDIS class interface. This should be  Dean Camera committed Nov 05, 2010 130  * linked to the library \ref EVENT_USB_Device_ControlRequest() event.  Dean Camera committed May 08, 2010 131  *  Dean Camera committed Jun 17, 2010 132  * \param[in,out] RNDISInterfaceInfo Pointer to a structure containing a RNDIS Class configuration and state.  133  */  Dean Camera committed May 08, 2010 134  void RNDIS_Device_ProcessControlRequest(USB_ClassInfo_RNDIS_Device_t* const RNDISInterfaceInfo) ATTR_NON_NULL_PTR_ARG(1);  135   Dean Camera committed May 08, 2010 136 137 138  /** General management task for a given HID class interface, required for the correct operation of the interface. This should * be called frequently in the main program loop, before the master USB management task \ref USB_USBTask(). *  Dean Camera committed Jun 17, 2010 139  * \param[in,out] RNDISInterfaceInfo Pointer to a structure containing a RNDIS Class configuration and state.  Dean Camera committed May 08, 2010 140 141  */ void RNDIS_Device_USBTask(USB_ClassInfo_RNDIS_Device_t* const RNDISInterfaceInfo) ATTR_NON_NULL_PTR_ARG(1);  142   Dean Camera committed May 18, 2011 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184  /** Determines if a packet is currently waiting for the device to read in and process. * * \pre This function must only be called when the Device state machine is in the \ref DEVICE_STATE_Configured state or the * call will fail. * * \param[in,out] RNDISInterfaceInfo Pointer to a structure containing an RNDIS Class configuration and state. * * \return Boolean \c true if a packet is waiting to be read in by the host, \c false otherwise. */ bool RNDIS_Device_IsPacketReceived(USB_ClassInfo_RNDIS_Device_t* const RNDISInterfaceInfo); /** Retrieves the next pending packet from the device, discarding the remainder of the RNDIS packet header to leave * only the packet contents for processing by the device in the nominated buffer. * * \pre This function must only be called when the Device state machine is in the \ref DEVICE_STATE_Configured state or the * call will fail. * * \param[in,out] RNDISInterfaceInfo Pointer to a structure containing an RNDIS Class configuration and state. * \param[out] Buffer Pointer to a buffer where the packer data is to be written to. * \param[out] PacketLength Pointer to where the length in bytes of the read packet is to be stored. * * \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum. */ uint8_t RNDIS_Device_ReadPacket(USB_ClassInfo_RNDIS_Device_t* const RNDISInterfaceInfo, void* Buffer, uint16_t* const PacketLength); /** Sends the given packet to the attached RNDIS device, after adding a RNDIS packet message header. * * \pre This function must only be called when the Device state machine is in the \ref DEVICE_STATE_Configured state or the * call will fail. * * \param[in,out] RNDISInterfaceInfo Pointer to a structure containing an RNDIS Class configuration and state. * \param[in] Buffer Pointer to a buffer where the packer data is to be read from. * \param[in] PacketLength Length in bytes of the packet to send. * * \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum. */ uint8_t RNDIS_Device_SendPacket(USB_ClassInfo_RNDIS_Device_t* const RNDISInterfaceInfo, void* Buffer, const uint16_t PacketLength);  Dean Camera committed May 08, 2010 185 186 187  /* Private Interface - For use in library only: */ #if !defined(__DOXYGEN__) /* Function Prototypes: */  Dean Camera committed Oct 24, 2010 188  #if defined(__INCLUDE_FROM_RNDIS_DEVICE_C)  Dean Camera committed May 08, 2010 189 190  static void RNDIS_Device_ProcessRNDISControlMessage(USB_ClassInfo_RNDIS_Device_t* const RNDISInterfaceInfo) ATTR_NON_NULL_PTR_ARG(1);  191  static bool RNDIS_Device_ProcessNDISQuery(USB_ClassInfo_RNDIS_Device_t* const RNDISInterfaceInfo,  Dean Camera committed Jul 21, 2010 192 193 194 195 196  const uint32_t OId, void* const QueryData, const uint16_t QuerySize, void* ResponseData, uint16_t* const ResponseSize) ATTR_NON_NULL_PTR_ARG(1)  Dean Camera committed May 08, 2010 197  ATTR_NON_NULL_PTR_ARG(5) ATTR_NON_NULL_PTR_ARG(6);  Dean Camera committed Jul 21, 2010 198 199 200 201  static bool RNDIS_Device_ProcessNDISSet(USB_ClassInfo_RNDIS_Device_t* const RNDISInterfaceInfo, const uint32_t OId, const void* SetData, const uint16_t SetSize) ATTR_NON_NULL_PTR_ARG(1)  Dean Camera committed May 08, 2010 202 203  ATTR_NON_NULL_PTR_ARG(3); #endif  204   Dean Camera committed May 08, 2010 205  #endif  206   Dean Camera committed May 08, 2010 207 208 209 210  /* Disable C linkage for C++ Compilers: */ #if defined(__cplusplus) } #endif  211   Dean Camera committed May 08, 2010 212 213 214 #endif /** @} */  215