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


dce7de79e982bf65f38ef02f87bb790503540f1b
[pub/USBasp.git] / LUFA / Drivers / USB / Class / ConfigDescriptor.h
1 /*
2 LUFA Library
3 Copyright (C) Dean Camera, 2009.
4
5 dean [at] fourwalledcubicle [dot] com
6 www.fourwalledcubicle.com
7 */
8
9 /*
10 Copyright 2009 Dean Camera (dean [at] fourwalledcubicle [dot] com)
11
12 Permission to use, copy, modify, and distribute this software
13 and its documentation for any purpose and without fee is hereby
14 granted, provided that the above copyright notice appear in all
15 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 *
33 * Configuration descriptor parser API. This section of the library gives a friendly API which can be used in
34 * host applications to easily parse an attached device's configuration descriptor so that endpoint, interface
35 * and other descriptor data can be extracted and used as needed.
36 */
37
38 /** \ingroup Group_Descriptors
39 * @defgroup Group_ConfigDescriptorParser Configuration Descriptor Parser
40 *
41 * Functions, macros, variables, enums and types related to the parsing of Configuration Descriptors.
42 *
43 * @{
44 */
45
46 #ifndef __CONFIGDESCRIPTOR_H__
47 #define __CONFIGDESCRIPTOR_H__
48
49 /* Includes: */
50 #include <avr/io.h>
51
52 #include "../../../Common/Common.h"
53 #include "../HighLevel/USBMode.h"
54 #include "../LowLevel/HostChapter9.h"
55 #include "../HighLevel/StdDescriptors.h"
56
57 /* Enable C linkage for C++ Compilers: */
58 #if defined(__cplusplus)
59 extern "C" {
60 #endif
61
62 /* Public Interface - May be used in end-application: */
63 /* Macros: */
64 /** Mask for determining the type of an endpoint from an endpoint descriptor. This should then be compared
65 * with the EP_TYPE_* masks to determine the exact type of the endpoint.
66 */
67 #define EP_TYPE_MASK 0x03
68
69 /** Casts a pointer to a descriptor inside the configuration descriptor into a pointer to the given
70 * descriptor type.
71 *
72 * Usage Example:
73 * \code
74 * uint8_t* CurrDescriptor = &ConfigDescriptor[0]; // Pointing to the configuration header
75 * USB_Descriptor_Configuration_Header_t* ConfigHeaderPtr = DESCRIPTOR_PCAST(CurrDescriptor,
76 * USB_Descriptor_Configuration_Header_t);
77 *
78 * // Can now access elements of the configuration header struct using the -> indirection operator
79 * \endcode
80 */
81 #define DESCRIPTOR_PCAST(DescriptorPtr, Type) ((Type*)DescriptorPtr)
82
83 /** Casts a pointer to a descriptor inside the configuration descriptor into the given descriptor
84 * type (as an actual struct instance rather than a pointer to a struct).
85 *
86 * Usage Example:
87 * \code
88 * uint8_t* CurrDescriptor = &ConfigDescriptor[0]; // Pointing to the configuration header
89 * USB_Descriptor_Configuration_Header_t ConfigHeader = DESCRIPTOR_CAST(CurrDescriptor,
90 * USB_Descriptor_Configuration_Header_t);
91 *
92 * // Can now access elements of the configuration header struct using the . operator
93 * \endcode
94 */
95 #define DESCRIPTOR_CAST(DescriptorPtr, Type) (*DESCRIPTOR_PCAST(DescriptorPtr, Type))
96
97 /** Returns the descriptor's type, expressed as the 8-bit type value in the header of the descriptor.
98 * This value's meaning depends on the descriptor's placement in the descriptor, but standard type
99 * values can be accessed in the DescriptorTypes_t enum located in USB/HighLevel/StdDescriptors.h.
100 */
101 #if defined(USE_NONSTANDARD_DESCRIPTOR_NAMES) || defined(__DOXYGEN__)
102 #define DESCRIPTOR_TYPE(DescriptorPtr) DESCRIPTOR_CAST(DescriptorPtr, USB_Descriptor_Header_t).Type
103 #else
104 #define DESCRIPTOR_TYPE(DescriptorPtr) DESCRIPTOR_CAST(DescriptorPtr, USB_Descriptor_Header_t).bDescriptorType
105 #endif
106
107 /** Returns the descriptor's size, expressed as the 8-bit value indicating the number of bytes. */
108 #if defined(USE_NONSTANDARD_DESCRIPTOR_NAMES) || defined(__DOXYGEN__)
109 #define DESCRIPTOR_SIZE(DescriptorPtr) DESCRIPTOR_CAST(DescriptorPtr, USB_Descriptor_Header_t).Size
110 #else
111 #define DESCRIPTOR_SIZE(DescriptorPtr) DESCRIPTOR_CAST(DescriptorPtr, USB_Descriptor_Header_t).bLength
112 #endif
113
114 /** Creates a prototype for or begins a descriptor comparator routine. Descriptor comparator routines are
115 * small search routines which are passed a pointer to the current sub descriptor in the configuration
116 * descriptor, and which analyse the sub descriptor to determine whether or not it matches the routine's
117 * search parameters. Comparator routines provide a powerful way to scan through the config descriptor
118 * for certain descriptors matching unique criteria.
119 *
120 * Comparator routines are passed in a single pointer named CurrentDescriptor, and should return a value
121 * of a member of the \ref DSearch_Return_ErrorCodes_t enum.
122 */
123 #define DESCRIPTOR_COMPARATOR(name) uint8_t DCOMP_##name (void* const CurrentDescriptor)
124
125 /* Pseudo-Function Macros: */
126 #if defined(__DOXYGEN__)
127 /** Searches for the next descriptor in the given configuration descriptor using a premade comparator
128 * function. The routine updates the position and remaining configuration descriptor bytes values
129 * automatically. If a comparator routine fails a search, the descriptor pointer is retreated back
130 * so that the next descriptor search invocation will start from the descriptor which first caused the
131 * original search to fail. This behaviour allows for one comparator to be used immediately after another
132 * has failed, starting the second search from the descriptor which failed the first.
133 *
134 * \note This function is available in USB Host mode only.
135 *
136 * \param BytesRem Pointer to an int storing the remaining bytes in the configuration descriptor
137 * \param CurrConfigLoc Pointer to the current position in the configuration descriptor
138 * \param ComparatorRoutine Name of the comparator search function to use on the configuration descriptor
139 *
140 * \return Value of one of the members of the \ref DSearch_Comp_Return_ErrorCodes_t enum
141 *
142 * Usage Example:
143 * \code
144 * DESCRIPTOR_COMPARATOR(EndpointSearcher); // Comparator Prototype
145 *
146 * DESCRIPTOR_COMPARATOR(EndpointSearcher)
147 * {
148 * if (DESCRIPTOR_TYPE(CurrentDescriptor) == DTYPE_Endpoint)
149 * return DESCRIPTOR_SEARCH_Found;
150 * else
151 * return DESCRIPTOR_SEARCH_NotFound;
152 * }
153 *
154 * //...
155 * // After retrieving configuration descriptor:
156 * if (USB_Host_GetNextDescriptorComp(&BytesRemaining, &ConfigDescriptorData, EndpointSearcher) ==
157 * Descriptor_Search_Comp_Found)
158 * {
159 * // Do something with the endpoint descriptor
160 * }
161 * \endcode
162 */
163 uint8_t USB_GetNextDescriptorComp(uint16_t* BytesRem, uint8_t** CurrConfigLoc, ComparatorPtr_t ComparatorRoutine);
164 #else
165 #define USB_GetNextDescriptorComp(DSize, DPos, DSearch) USB_GetNextDescriptorComp_Prv(DSize, DPos, DCOMP_##DSearch)
166 #endif
167
168 /* Enums: */
169 /** Enum for return values of a descriptor comparator made with \ref DESCRIPTOR_COMPARATOR. */
170 enum DSearch_Return_ErrorCodes_t
171 {
172 DESCRIPTOR_SEARCH_Found = 0, /**< Current descriptor matches comparator criteria. */
173 DESCRIPTOR_SEARCH_Fail = 1, /**< No further descriptor could possibly match criteria, fail the search. */
174 DESCRIPTOR_SEARCH_NotFound = 2, /**< Current descriptor does not match comparator criteria. */
175 };
176
177 /** Enum for return values of \ref USB_GetNextDescriptorComp(). */
178 enum DSearch_Comp_Return_ErrorCodes_t
179 {
180 DESCRIPTOR_SEARCH_COMP_Found = 0, /**< Configuration descriptor now points to descriptor which matches
181 * search criteria of the given comparator function. */
182 DESCRIPTOR_SEARCH_COMP_Fail = 1, /**< Comparator function returned Descriptor_Search_Fail. */
183 DESCRIPTOR_SEARCH_COMP_EndOfDescriptor = 2, /**< End of configuration descriptor reached before match found. */
184 };
185
186 /* Function Prototypes: */
187 /** Retrieves the configuration descriptor data or size from an attached device via a standard request.
188 *
189 * \param ConfigSizePtr Pointer to a uint16_t for either storing or retrieving the configuration
190 * descriptor size
191 *
192 * \param BufferPtr Pointer to the buffer for storing the configuration descriptor data. If this is
193 * NULL, the size of the configuration descriptor will be retrieved instead and
194 * placed in the variable pointed to by ConfigSizePtr. If this is non-NULL, the number
195 * of bytes indicated by ConfigSizePtr of the configuration descriptor will be loaded
196 * into the buffer
197 */
198 uint8_t USB_GetDeviceConfigDescriptor(uint16_t* const ConfigSizePtr, void* BufferPtr)
199 ATTR_NON_NULL_PTR_ARG(1);
200
201 /** Skips to the next sub-descriptor inside the configuration descriptor of the specified type value.
202 * The bytes remaining value is automatically decremented.
203 *
204 * \param BytesRem Pointer to the number of bytes remaining of the configuration descriptor
205 * \param CurrConfigLoc Pointer to the current descriptor inside the configuration descriptor
206 * \param Type Descriptor type value to search for
207 */
208 void USB_GetNextDescriptorOfType(uint16_t* const BytesRem,
209 uint8_t** const CurrConfigLoc,
210 const uint8_t Type)
211 ATTR_NON_NULL_PTR_ARG(1, 2);
212
213 /** Skips to the next sub-descriptor inside the configuration descriptor of the specified type value,
214 * which must come before a descriptor of the second given type value. If the BeforeType type
215 * descriptor is reached first, the number of bytes remaining to process is set to zero and the
216 * function exits. The bytes remaining value is automatically decremented.
217 *
218 * \param BytesRem Pointer to the number of bytes remaining of the configuration descriptor
219 * \param CurrConfigLoc Pointer to the current descriptor inside the configuration descriptor
220 * \param Type Descriptor type value to search for
221 * \param BeforeType Descriptor type value which must not be reached before the given Type descriptor
222 */
223 void USB_GetNextDescriptorOfTypeBefore(uint16_t* const BytesRem,
224 uint8_t** const CurrConfigLoc,
225 const uint8_t Type,
226 const uint8_t BeforeType)
227 ATTR_NON_NULL_PTR_ARG(1, 2);
228
229 /** Skips to the next sub-descriptor inside the configuration descriptor of the specified type value,
230 * which must come after a descriptor of the second given type value. The bytes remaining value is
231 * automatically decremented.
232 *
233 * \param BytesRem Pointer to the number of bytes remaining of the configuration descriptor
234 * \param CurrConfigLoc Pointer to the current descriptor inside the configuration descriptor
235 * \param Type Descriptor type value to search for
236 * \param AfterType Descriptor type value which must be reached before the given Type descriptor
237 */
238 void USB_GetNextDescriptorOfTypeAfter(uint16_t* const BytesRem,
239 uint8_t** const CurrConfigLoc,
240 const uint8_t Type,
241 const uint8_t AfterType)
242 ATTR_NON_NULL_PTR_ARG(1, 2);
243
244 /* Inline Functions: */
245 /** Skips over the current sub-descriptor inside the configuration descriptor, so that the pointer then
246 points to the next sub-descriptor. The bytes remaining value is automatically decremented.
247 *
248 * \param BytesRem Pointer to the number of bytes remaining of the configuration descriptor
249 * \param CurrConfigLoc Pointer to the current descriptor inside the configuration descriptor
250 */
251 static inline void USB_GetNextDescriptor(uint16_t* const BytesRem,
252 uint8_t** const CurrConfigLoc)
253 ATTR_NON_NULL_PTR_ARG(1, 2);
254 static inline void USB_GetNextDescriptor(uint16_t* const BytesRem,
255 uint8_t** const CurrConfigLoc)
256 {
257 #if defined(USE_NONSTANDARD_DESCRIPTOR_NAMES)
258 uint16_t CurrDescriptorSize = DESCRIPTOR_CAST(*CurrConfigLoc, USB_Descriptor_Header_t).Size;
259 #else
260 uint16_t CurrDescriptorSize = DESCRIPTOR_CAST(*CurrConfigLoc, USB_Descriptor_Header_t).bLength;
261 #endif
262
263 *CurrConfigLoc += CurrDescriptorSize;
264 *BytesRem -= CurrDescriptorSize;
265 }
266
267 /* Private Interface - For use in library only: */
268 #if !defined(__DOXYGEN__)
269 /* Type Defines: */
270 typedef uint8_t (* const ComparatorPtr_t)(void* const);
271
272 /* Function Prototypes: */
273 uint8_t USB_GetNextDescriptorComp_Prv(uint16_t* BytesRem, uint8_t** CurrConfigLoc, ComparatorPtr_t ComparatorRoutine);
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