projects / pub / USBasp.git / blob
? search:


c7dba7165c7ddc565c1f09b275a82f11f0fee409
[pub/USBasp.git] / LUFA / Drivers / USB / Class / Host / RNDIS.h
1 /*
2 LUFA Library
3 Copyright (C) Dean Camera, 2010.
4
5 dean [at] fourwalledcubicle [dot] com
6 www.fourwalledcubicle.com
7 */
8
9 /*
10 Copyright 2010 Dean Camera (dean [at] fourwalledcubicle [dot] com)
11
12 Permission to use, copy, modify, distribute, and sell this
13 software and its documentation for any purpose is hereby granted
14 without fee, provided that the above copyright notice appear in
15 all copies and that both that the copyright notice and this
16 permission notice and warranty disclaimer appear in supporting
17 documentation, and that the name of the author not be used in
18 advertising or publicity pertaining to distribution of the
19 software without specific, written prior permission.
20
21 The author disclaim all warranties with regard to this
22 software, including all implied warranties of merchantability
23 and fitness. In no event shall the author be liable for any
24 special, indirect or consequential damages or any damages
25 whatsoever resulting from loss of use, data or profits, whether
26 in an action of contract, negligence or other tortious action,
27 arising out of or in connection with the use or performance of
28 this software.
29 */
30
31 /** \file
32 * \brief Host mode driver for the library USB RNDIS Class driver.
33 *
34 * Host mode driver for the library USB RNDIS Class driver.
35 *
36 * \note This file should not be included directly. It is automatically included as needed by the class driver
37 * dispatch header located in LUFA/Drivers/USB/Class/RNDIS.h.
38 */
39
40 /** \ingroup Group_USBClassRNDIS
41 * @defgroup Group_USBClassRNDISHost RNDIS Class Host Mode Driver
42 *
43 * \section Sec_Dependencies Module Source Dependencies
44 * The following files must be built with any user project that uses this module:
45 * - LUFA/Drivers/USB/Class/Host/RNDIS.c
46 *
47 * \section Module Description
48 * Host Mode USB Class driver framework interface, for the Microsoft RNDIS Ethernet
49 * USB Class driver.
50 *
51 * @{
52 */
53
54 #ifndef __RNDIS_CLASS_HOST_H__
55 #define __RNDIS_CLASS_HOST_H__
56
57 /* Includes: */
58 #include "../../USB.h"
59 #include "../Common/RNDIS.h"
60
61 #include <stdio.h>
62 #include <string.h>
63
64 /* Enable C linkage for C++ Compilers: */
65 #if defined(__cplusplus)
66 extern "C" {
67 #endif
68
69 /* Preprocessor Checks: */
70 #if !defined(__INCLUDE_FROM_RNDIS_DRIVER)
71 #error Do not include this file directly. Include LUFA/Drivers/Class/RNDIS.h instead.
72 #endif
73
74 /* Public Interface - May be used in end-application: */
75 /* Type Defines: */
76 /** \brief RNDIS Class Host Mode Configuration and State Structure.
77 *
78 * Class state structure. An instance of this structure should be made within the user application,
79 * and passed to each of the RNDIS class driver functions as the RNDISInterfaceInfo parameter. This
80 * stores each RNDIS interface's configuration and state information.
81 */
82 typedef struct
83 {
84 const struct
85 {
86 uint8_t DataINPipeNumber; /**< Pipe number of the RNDIS interface's IN data pipe */
87 bool DataINPipeDoubleBank; /** Indicates if the RNDIS interface's IN data pipe should use double banking */
88
89 uint8_t DataOUTPipeNumber; /**< Pipe number of the RNDIS interface's OUT data pipe */
90 bool DataOUTPipeDoubleBank; /** Indicates if the RNDIS interface's OUT data pipe should use double banking */
91
92 uint8_t NotificationPipeNumber; /**< Pipe number of the RNDIS interface's IN notification endpoint, if used */
93 bool NotificationPipeDoubleBank; /** Indicates if the RNDIS interface's notification pipe should use double banking */
94
95 uint32_t HostMaxPacketSize; /**< Maximum size of a packet which can be buffered by the host */
96 } Config; /**< Config data for the USB class interface within the device. All elements in this section
97 * <b>must</b> be set or the interface will fail to enumerate and operate correctly.
98 */
99 struct
100 {
101 bool IsActive; /**< Indicates if the current interface instance is connected to an attached device, valid
102 * after \ref RNDIS_Host_ConfigurePipes() is called and the Host state machine is in the
103 * Configured state
104 */
105 uint8_t ControlInterfaceNumber; /**< Interface index of the RNDIS control interface within the attached device */
106
107 uint16_t DataINPipeSize; /**< Size in bytes of the RNDIS interface's IN data pipe */
108 uint16_t DataOUTPipeSize; /**< Size in bytes of the RNDIS interface's OUT data pipe */
109 uint16_t NotificationPipeSize; /**< Size in bytes of the RNDIS interface's IN notification pipe, if used */
110
111 uint32_t DeviceMaxPacketSize; /**< Maximum size of a packet which can be buffered by the attached RNDIS device */
112
113 uint32_t RequestID; /**< Request ID counter to give a unique ID for each command/response pair */
114 } State; /**< State data for the USB class interface within the device. All elements in this section
115 * <b>may</b> be set to initial values, but may also be ignored to default to sane values when
116 * the interface is enumerated.
117 */
118 } USB_ClassInfo_RNDIS_Host_t;
119
120 /* Enums: */
121 /** Enum for the possible error codes returned by the \ref RNDIS_Host_ConfigurePipes() function. */
122 enum RNDISHost_EnumerationFailure_ErrorCodes_t
123 {
124 RNDIS_ENUMERROR_NoError = 0, /**< Configuration Descriptor was processed successfully */
125 RNDIS_ENUMERROR_InvalidConfigDescriptor = 1, /**< The device returned an invalid Configuration Descriptor */
126 RNDIS_ENUMERROR_NoRNDISInterfaceFound = 2, /**< A compatible RNDIS interface was not found in the device's Configuration Descriptor */
127 RNDIS_ENUMERROR_EndpointsNotFound = 3, /**< Compatible RNDIS endpoints were not found in the device's RNDIS interface */
128 };
129
130 /* Macros: */
131 /** Additional error code for RNDIS functions when a device returns a logical command failure */
132 #define RNDIS_COMMAND_FAILED 0xC0
133
134 /* Function Prototypes: */
135 /** Host interface configuration routine, to configure a given RNDIS host interface instance using the Configuration
136 * Descriptor read from an attached USB device. This function automatically updates the given RNDIS Host instance's
137 * state values and configures the pipes required to communicate with the interface if it is found within the device.
138 * This should be called once after the stack has enumerated the attached device, while the host state machine is in
139 * the Addressed state.
140 *
141 * \param[in,out] RNDISInterfaceInfo Pointer to a structure containing an RNDIS Class host configuration and state
142 * \param[in] ConfigDescriptorSize Length of the attached device's Configuration Descriptor
143 * \param[in] DeviceConfigDescriptor Pointer to a buffer containing the attached device's Configuration Descriptor
144 *
145 * \return A value from the \ref RNDISHost_EnumerationFailure_ErrorCodes_t enum
146 */
147 uint8_t RNDIS_Host_ConfigurePipes(USB_ClassInfo_RNDIS_Host_t* const RNDISInterfaceInfo, uint16_t ConfigDescriptorSize,
148 void* DeviceConfigDescriptor) ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(3);
149
150 /** Sends a RNDIS KEEPALIVE command to the device, to ensure that it does not enter standby mode after periods
151 * of long inactivity.
152 *
153 * \param[in,out] RNDISInterfaceInfo Pointer to a structure containing an RNDIS Class host configuration and state
154 *
155 * \return A value from the USB_Host_SendControlErrorCodes_t enum or RNDIS_COMMAND_FAILED if the device returned a
156 * logical command failure
157 */
158 uint8_t RNDIS_Host_SendKeepAlive(USB_ClassInfo_RNDIS_Host_t* const RNDISInterfaceInfo) ATTR_NON_NULL_PTR_ARG(1);
159
160 /** Initializes the attached RNDIS device's RNDIS interface. This should be called after the device's pipes have been
161 * configured via the call to \ref RNDIS_Host_ConfigurePipes().
162 *
163 * \param[in,out] RNDISInterfaceInfo Pointer to a structure containing an RNDIS Class host configuration and state
164 *
165 * \return A value from the USB_Host_SendControlErrorCodes_t enum or RNDIS_COMMAND_FAILED if the device returned a
166 * logical command failure
167 */
168 uint8_t RNDIS_Host_InitializeDevice(USB_ClassInfo_RNDIS_Host_t* const RNDISInterfaceInfo) ATTR_NON_NULL_PTR_ARG(1);
169
170 /** Sets a given RNDIS property of an attached RNDIS device.
171 *
172 * \param[in,out] RNDISInterfaceInfo Pointer to a structure containing an RNDIS Class host configuration and state
173 * \param[in] Oid OID number of the parameter to set
174 * \param[in] Buffer Pointer to where the property data is to be sourced from
175 * \param[in] Length Length in bytes of the property data to sent to the device
176 *
177 * \return A value from the USB_Host_SendControlErrorCodes_t enum or RNDIS_COMMAND_FAILED if the device returned a
178 * logical command failure
179 */
180 uint8_t RNDIS_Host_SetRNDISProperty(USB_ClassInfo_RNDIS_Host_t* const RNDISInterfaceInfo, uint32_t Oid, void* Buffer,
181 uint16_t Length) ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(3);
182
183 /** Gets a given RNDIS property of an attached RNDIS device.
184 *
185 * \param[in,out] RNDISInterfaceInfo Pointer to a structure containing an RNDIS Class host configuration and state
186 * \param[in] Oid OID number of the parameter to get
187 * \param[in] Buffer Pointer to where the property data is to be written to
188 * \param[in] MaxLength Length in bytes of the destination buffer size
189 *
190 * \return A value from the USB_Host_SendControlErrorCodes_t enum or RNDIS_COMMAND_FAILED if the device returned a
191 * logical command failure
192 */
193 uint8_t RNDIS_Host_QueryRNDISProperty(USB_ClassInfo_RNDIS_Host_t* const RNDISInterfaceInfo, uint32_t Oid, void* Buffer,
194 uint16_t MaxLength) ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(3);
195
196 /** Determines if a packet is currently waiting for the host to read in and process.
197 *
198 * \note This function must only be called when the Host state machine is in the HOST_STATE_Configured state or the
199 * call will fail.
200 *
201 * \param[in,out] RNDISInterfaceInfo Pointer to a structure containing an RNDIS Class host configuration and state
202 *
203 * \return Boolean true if a packet is waiting to be read in by the host, false otherwise
204 */
205
206 bool RNDIS_Host_IsPacketReceived(USB_ClassInfo_RNDIS_Host_t* const RNDISInterfaceInfo);
207
208 /** Retrieves the next pending packet from the device, discarding the remainder of the RNDIS packet header to leave
209 * only the packet contents for processing by the host in the nominated buffer.
210 *
211 * \note This function must only be called when the Host state machine is in the HOST_STATE_Configured state or the
212 * call will fail.
213 *
214 * \param[in,out] RNDISInterfaceInfo Pointer to a structure containing an RNDIS Class host configuration and state
215 * \param[out] Buffer Pointer to a buffer where the packer data is to be written to
216 * \param[out] PacketLength Pointer to where the length in bytes of the read packet is to be stored
217 *
218 * \return A value from the Pipe_Stream_RW_ErrorCodes_t enum
219 */
220 uint8_t RNDIS_Host_ReadPacket(USB_ClassInfo_RNDIS_Host_t* const RNDISInterfaceInfo, void* Buffer, uint16_t* PacketLength)
221 ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(2) ATTR_NON_NULL_PTR_ARG(3);
222
223 /** Sends the given packet to the attached RNDIS device, after adding a RNDIS packet message header.
224 *
225 * \note This function must only be called when the Host state machine is in the HOST_STATE_Configured state or the
226 * call will fail.
227 *
228 * \param[in,out] RNDISInterfaceInfo Pointer to a structure containing an RNDIS Class host configuration and state
229 * \param[in] Buffer Pointer to a buffer where the packer data is to be read from
230 * \param[in] PacketLength Length in bytes of the packet to send
231 *
232 * \return A value from the Pipe_Stream_RW_ErrorCodes_t enum
233 */
234 uint8_t RNDIS_Host_SendPacket(USB_ClassInfo_RNDIS_Host_t* const RNDISInterfaceInfo, void* Buffer, uint16_t PacketLength)
235 ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(2);
236
237 /* Inline Functions: */
238 /** General management task for a given RNDIS host class interface, required for the correct operation of the interface. This should
239 * be called frequently in the main program loop, before the master USB management task \ref USB_USBTask().
240 *
241 * \param[in,out] RNDISInterfaceInfo Pointer to a structure containing an RNDIS Class host configuration and state
242 */
243 static inline void RNDIS_Host_USBTask(USB_ClassInfo_RNDIS_Host_t* const RNDISInterfaceInfo);
244 static inline void RNDIS_Host_USBTask(USB_ClassInfo_RNDIS_Host_t* const RNDISInterfaceInfo)
245 {
246 (void)RNDISInterfaceInfo;
247 }
248
249 /* Private Interface - For use in library only: */
250 #if !defined(__DOXYGEN__)
251 /* Macros: */
252 #define RNDIS_CONTROL_CLASS 0x02
253 #define RNDIS_CONTROL_SUBCLASS 0x02
254 #define RNDIS_CONTROL_PROTOCOL 0xFF
255 #define RNDIS_DATA_CLASS 0x0A
256 #define RNDIS_DATA_SUBCLASS 0x00
257 #define RNDIS_DATA_PROTOCOL 0x00
258
259 #define RNDIS_FOUND_DATAPIPE_IN (1 << 0)
260 #define RNDIS_FOUND_DATAPIPE_OUT (1 << 1)
261 #define RNDIS_FOUND_NOTIFICATION_IN (1 << 2)
262
263 /* Function Prototypes: */
264 #if defined(__INCLUDE_FROM_RNDIS_CLASS_HOST_C)
265 static uint8_t RNDIS_SendEncapsulatedCommand(USB_ClassInfo_RNDIS_Host_t* const RNDISInterfaceInfo,
266 void* Buffer, uint16_t Length) ATTR_NON_NULL_PTR_ARG(1);
267 static uint8_t RNDIS_GetEncapsulatedResponse(USB_ClassInfo_RNDIS_Host_t* const RNDISInterfaceInfo,
268 void* Buffer, uint16_t Length) ATTR_NON_NULL_PTR_ARG(1);
269
270 static uint8_t DCOMP_RNDIS_Host_NextRNDISControlInterface(void* const CurrentDescriptor) ATTR_NON_NULL_PTR_ARG(1);
271 static uint8_t DCOMP_RNDIS_Host_NextRNDISDataInterface(void* const CurrentDescriptor) ATTR_NON_NULL_PTR_ARG(1);
272 static uint8_t DCOMP_RNDIS_Host_NextRNDISInterfaceEndpoint(void* const CurrentDescriptor);
273 #endif
274 #endif
275
276 /* Disable C linkage for C++ Compilers: */
277 #if defined(__cplusplus)
278 }
279 #endif
280
281 #endif
282
283 /** @} */
USB isp AVR programmer