USBLibAPIGuide  1.00.00.01
usbdfu.h
Go to the documentation of this file.
1 //*****************************************************************************
2 //
3 // usbdfu.h - Definitions related to the USB Device Firmware Upgrade class.
4 //
5 // Copyright (c) 2008-2017 Texas Instruments Incorporated. All rights reserved.
6 // Software License Agreement
7 //
8 // Texas Instruments (TI) is supplying this software for use solely and
9 // exclusively on TI's microcontroller products. The software is owned by
10 // TI and/or its suppliers, and is protected under applicable copyright
11 // laws. You may not combine this software with "viral" open-source
12 // software in order to form a larger program.
13 //
14 // THIS SOFTWARE IS PROVIDED "AS IS" AND WITH ALL FAULTS.
15 // NO WARRANTIES, WHETHER EXPRESS, IMPLIED OR STATUTORY, INCLUDING, BUT
16 // NOT LIMITED TO, IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
17 // A PARTICULAR PURPOSE APPLY TO THIS SOFTWARE. TI SHALL NOT, UNDER ANY
18 // CIRCUMSTANCES, BE LIABLE FOR SPECIAL, INCIDENTAL, OR CONSEQUENTIAL
19 // DAMAGES, FOR ANY REASON WHATSOEVER.
20 //
21 //*****************************************************************************
22 
23 #ifndef __USBDFU_H__
24 #define __USBDFU_H__
25 
26 //*****************************************************************************
27 //
28 // DFU attributes as published in the functional descriptor.
29 //
30 //*****************************************************************************
31 #define DFU_ATTR_WILL_DETACH 0x08
32 #define DFU_ATTR_MANIFEST_TOLERANT \
33  0x04
34 #define DFU_ATTR_CAN_UPLOAD 0x02
35 #define DFU_ATTR_CAN_DOWNLOAD 0x01
36 
37 //*****************************************************************************
38 //
39 // The states that the DFU device can be in. These values are reported to
40 // the host in response to a USBD_DFU_REQUEST_GETSTATE request.
41 //
42 //*****************************************************************************
43 typedef enum
44 {
56 }
57 tDFUState;
58 
59 //*****************************************************************************
60 //
61 // The current error status of the DFU device. These values are reported to
62 // the host in response to a USBD_DFU_REQUEST_GETSTATUS request.
63 //
64 //*****************************************************************************
65 typedef enum
66 {
83 }
85 
86 //*****************************************************************************
87 //
88 // The descriptor type for the DFU functional descriptor.
89 //
90 //*****************************************************************************
91 #define USB_DFU_FUNC_DESCRIPTOR_TYPE \
92  0x21
93 
94 //*****************************************************************************
95 //
96 // The subclass identifier for DFU as reported to the host in the
97 // bInterfaceSubClass field of the DFU interface descriptor.
98 //
99 //*****************************************************************************
100 #define USB_DFU_SUBCLASS 0x01
101 
102 //*****************************************************************************
103 //
104 // The protocol identifier for DFU as reported to the host in the
105 // bInterfaceProtocol field of the DFU interface descriptor.
106 //
107 //*****************************************************************************
108 #define USB_DFU_PROTOCOL 0x02
109 #define USB_DFU_RUNTIME_PROTOCOL \
110  0x01
111 
112 //*****************************************************************************
113 //
114 // DFU class-specific request identifiers.
115 //
116 //*****************************************************************************
117 #define USBD_DFU_REQUEST_DETACH 0
118 #define USBD_DFU_REQUEST_DNLOAD 1
119 #define USBD_DFU_REQUEST_UPLOAD 2
120 #define USBD_DFU_REQUEST_GETSTATUS \
121  3
122 #define USBD_DFU_REQUEST_CLRSTATUS \
123  4
124 #define USBD_DFU_REQUEST_GETSTATE \
125  5
126 #define USBD_DFU_REQUEST_ABORT 6
127 
128 //*****************************************************************************
129 //
130 // Request 1KB blocks from the host. This value is published in the USB
131 // functional descriptor.
132 //
133 //*****************************************************************************
134 #define DFU_TRANSFER_SIZE 1024
135 
136 //*****************************************************************************
137 //
138 // USBLib-specific request identifier. This is used to determine whether
139 // the target device supports our DFU command protocol. It is expected that
140 // a device not supporting our extensions will stall this request. This
141 // request is only supported while the DFU device is in eDFUStateIdle.
142 //
143 // An IN request containing the following parameters will result in the device
144 // sending back a tDFUQueryMsp432eProtocol structure indicating that
145 // USBLib extensions are supported. The actual values in wValue and wIndex
146 // have no meaning other than to act as markers in the unlikely event that
147 // another DFU device also chooses to use request ID 0x42 for some other
148 // purpose.
149 //
150 // wValue - 0x23(REQUEST_MSP432E_VALUE)
151 // wIndex - Interface number
152 // wLength - sizeof(tDFUQueryMsp432eProtocol)
153 //
154 //*****************************************************************************
155 #define USBD_DFU_REQUEST_MSP432E 0x42
156 #define REQUEST_MSP432E_VALUE 0x23
157 
158 #define DFU_PROTOCOL_MSP432E_MARKER \
159  0x4C4D
160 #define DFU_PROTOCOL_MSP432E_VERSION_1 \
161  0x0001
162 
163 #ifdef __ICCARM__
164 #pragma pack(1)
165 #endif
166 
167 //*****************************************************************************
168 //
169 // The structure sent to the host when a valid USBD_DFU_REQUEST_MSP432E is
170 // received while the DFU device is in idle state.
171 //
172 //*****************************************************************************
173 typedef struct
174 {
175  //
176  // The protocol marker(DFU_PROTOCOL_MSP432E_MARKER)
177  //
178  uint16_t ui16Marker;
179 
180  //
181  // The protocol version(DFU_PROTOCOL_MSP432E_VERSION_1)
182  //
183  uint16_t ui16Version;
184 }
185 PACKED tDFUQueryMsp432eProtocol;
186 
187 //*****************************************************************************
188 //
189 // Structure sent to the host in response to USBD_DFU_REQUEST_GETSTATUS.
190 //
191 //*****************************************************************************
192 typedef struct
193 {
194  uint8_t bStatus;
195  uint8_t bwPollTimeout[3];
196  uint8_t bState;
197  uint8_t iString;
198 }
199 PACKED tDFUGetStatusResponse;
200 
201 //*****************************************************************************
202 //
203 // Firmware Download Commands
204 //
205 // The data passed on a USBD_DFU_REQUEST_DNLOAD request is comprised of a
206 // header which instructs the boot loader how to interpret the block and
207 // block-specific data. The following definitions relate to the download
208 // block headers.
209 //
210 //*****************************************************************************
211 
212 //*****************************************************************************
213 //
214 // Supported command identifiers
215 //
216 //*****************************************************************************
217 #define DFU_CMD_PROG 0x01
218 #define DFU_CMD_READ 0x02
219 #define DFU_CMD_CHECK 0x03
220 #define DFU_CMD_ERASE 0x04
221 #define DFU_CMD_INFO 0x05
222 #define DFU_CMD_BIN 0x06
223 #define DFU_CMD_RESET 0x07
224 
225 //*****************************************************************************
226 //
227 // Generic download command header.
228 //
229 //*****************************************************************************
230 typedef struct
231 {
232  //
233  // Command identifier.
234  //
235  uint8_t ui8Command;
236 
237  //
238  // Command-specific data elements.
239  //
240  uint8_t pui8Data[7];
241 }
242 PACKED tDFUDownloadHeader;
243 
244 //*****************************************************************************
245 //
246 // Header for the DFU_CMD_PROG command.
247 //
248 // This command is used to program a section of the flash with the binary data
249 // which immediately follows the header. The start address of the data is
250 // expressed as a 1KB block number so 0 would represent the bottom of flash
251 // (which, incidentally, the USB boot loader will not let you program) and 0x10
252 // would represent address 16KB or 16384 (0x4000). The ui32Length field
253 // contains the total number of bytes of data in the following programming
254 // operation. The DFU device will not look for any command header on following
255 // USBD_DFU_REQUEST_DNLOAD requests until the operation is completed or
256 // aborted.
257 //
258 // By using this protocol, the DFU_CMD_PROG command header may be used as a
259 // simple header on the binary files to be sent to the DFU device for
260 // programming. If we enforce the requirement that the DFU_CMD_PROG header is
261 // applied to each USBD_DFU_REQUEST_DNLOAD (one per block), this means that the
262 // host-side DFU application must be aware of the underlying protocol and
263 // insert these headers dynamically during programming operations. This could
264 // be handled by post processing the binary to insert the headers at the
265 // appropriate points but this would then tie the binary structure to the
266 // chosen transfer size and break the operation if the transfer size were to
267 // change in the future.
268 //
269 //*****************************************************************************
270 typedef struct
271 {
272  //
273  // DFU_CMD_PROG
274  //
275  uint8_t ui8Command;
276 
277  //
278  // Reserved - set to 0x00.
279  //
280  uint8_t ui8Reserved;
281 
282  //
283  // Block start address / 1024
284  //
285  uint16_t ui16StartAddr;
286 
287  //
288  // Total length, in bytes, of following data for the complete download
289  // operation.
290  //
291  uint32_t ui32Length;
292 }
293 PACKED tDFUDownloadProgHeader;
294 
295 //*****************************************************************************
296 //
297 // Header for the DFU_CMD_READ and DFU_CMD_CHECK commands.
298 //
299 // This command may be used to set the address range whose content will be
300 // returned on subsequent USBD_DFU_REQUEST_UPLOAD requests from the host.
301 //
302 // To read back a the contents of a region of flash, the host should send
303 // USBD_DFU_REQUEST_DNLOAD with ui8Command DFU_CMD_READ, ui16StartAddr set to
304 // the 1KB block start address and ui32Length set to the number of bytes to
305 // read. The host should then send one or more USBD_DFU_REQUEST_UPLOAD
306 // requests to receive the current flash contents from the configured
307 // addresses. Data returned will include an 8 byte DFU_CMD_PROG prefix
308 // structure unless the prefix has been disabled by sending a DFU_CMD_BIN
309 // command with the bBinary parameter set to 1.
310 //
311 // To check that a region of flash is erased, the DFU_CMD_CHECK command should
312 // be sent with ui16StartAddr and ui32Length set to describe the region to
313 // check. The host should then send a USBD_DFU_REQUEST_GETSTATUS. If the
314 // erase check was successful, the returned bStatus value will be STATUS_OK,
315 // otherwise it will be STATUS_ERR_CHECK_ERASED. Note that ui32Length passed
316 // must be a multiple of 4. If this is not the case, the value will be
317 // truncated before the check is performed.
318 //
319 //*****************************************************************************
320 typedef struct
321 {
322  //
323  // DFU_CMD_READ or DFU_CMD_CHECK
324  //
325  uint8_t ui8Command;
326 
327  //
328  // Reserved - write to 0
329  //
330  uint8_t ui8Reserved;
331 
332  //
333  // Block start address / 1024
334  //
335  uint16_t ui16StartAddr;
336 
337  //
338  // The number of bytes of data to read back or check.
339  //
340  uint32_t ui32Length;
341 }
342 PACKED tDFUDownloadReadCheckHeader;
343 
344 //*****************************************************************************
345 //
346 // Header for the DFU_CMD_ERASE command.
347 //
348 // This command may be used to erase a number of flash blocks. The address of
349 // the first block to be erased is passed in ui16StartAddr with ui16NumBlocks
350 // containing the number of blocks to be erased from this address. The block
351 // size of the device may be determined using the DFU_CMD_INFO command.
352 //
353 //*****************************************************************************
354 typedef struct
355 {
356  //
357  // DFU_CMD_ERASE
358  //
359  uint8_t ui8Command;
360 
361  //
362  // Reserved - set to 0.
363  //
364  uint8_t ui8Reserved;
365 
366  //
367  // Block start address / 1024
368  //
369  uint16_t ui16StartAddr;
370 
371  //
372  // The number of blocks to erase.
373  //
374  uint16_t ui16NumBlocks;
375 
376  //
377  // Reserved - set to 0.
378  //
379  uint8_t pui8Reserved2[2];
380 }
381 PACKED tDFUDownloadEraseHeader;
382 
383 //*****************************************************************************
384 //
385 // Header for the DFU_CMD_INFO command.
386 //
387 // This command may be used to query information about the connected device.
388 // After sending the command, the information is returned on the next
389 // USBD_DFU_REQUEST_UPLOAD request.
390 //
391 //*****************************************************************************
392 typedef struct
393 {
394  //
395  // DFU_CMD_INFO
396  //
397  uint8_t ui8Command;
398 
399  //
400  // Reserved - set to 0.
401  //
402  uint8_t pui8Reserved[7];
403 }
404 PACKED tDFUDownloadInfoHeader;
405 
406 //*****************************************************************************
407 //
408 // Header for the DFU_CMD_BIN command.
409 //
410 // This command may be used to set the format of uploaded data. By default,
411 // images read using USBD_DFU_REQUEST_UPLOAD are formatted with the appropriate
412 // header to allow the same image to be flashed back to the device and have it
413 // located at the address from which it originated. This is a requirement of
414 // the DFU class specification (section 6.2 "the uploaded image must be
415 // usable in a subsequent download") but may not be helpful in some cases where
416 // the application wishes to receive only the binary image from flash. To
417 // instruct the DFU device to omit the position and size header, send this
418 // command with the bBinary field set to \b true prior to issuing a
419 // USBD_DFU_REQUEST_UPLOAD for image data. The format choice remains in effect
420 // until the command is sent once again with bBinary set to \b false.
421 //
422 // Note that the format choice affects only image data sent and not responses
423 // read via USBD_DFU_REQUEST_UPLOAD following USBLib-specific commands such
424 // as DFU_CMD_INFO.
425 //
426 //*****************************************************************************
427 typedef struct
428 {
429  //
430  // DFU_CMD_BIN
431  //
432  uint8_t ui8Command;
433 
434  //
435  // Set to true to omit image header or false to include it (the default).
436  //
437  uint8_t ui8Binary;
438 
439  //
440  // Reserved - set to 0.
441  //
442  uint8_t pui8Reserved[6];
443 }
444 PACKED tDFUDownloadBinHeader;
445 
446 //*****************************************************************************
447 //
448 // The DFU_CMD_RESET command uses a tDFUDownloadHeader structure since
449 // only the ui8Command field is important. This command causes an immediate
450 // reset of the the target board.
451 //
452 //*****************************************************************************
453 
454 //*****************************************************************************
455 //
460 //
461 //*****************************************************************************
462 typedef struct
463 {
464  //
466  //
468 
469  //
472  //
474 
475  //
478  //
479  uint32_t ui32PartInfo;
480 
481  //
483  //
484  uint32_t ui32ClassInfo;
485 
486  //
488  //
489  uint32_t ui32FlashTop;
490 
491  //
493  //
495 }
496 PACKED tDFUDeviceInfo;
497 
498 #ifdef __ICCARM__
499 #pragma pack()
500 #endif
501 
502 #endif // __USBDFU_H__
Definition: usbdfu.h:48
Definition: usbdfu.h:82
Definition: usbdfu.h:54
tDFUStatus
Definition: usbdfu.h:65
Definition: usbdfu.h:80
Definition: usbdfu.h:47
uint32_t ui32PartInfo
Definition: usbdfu.h:479
tDFUState
Definition: usbdfu.h:43
uint32_t ui32ClassInfo
Information on the part class and revision as read from SYSCTL DID0.
Definition: usbdfu.h:484
Definition: usbdfu.h:45
uint8_t ui8Binary
Definition: usbdfu.h:437
Definition: usbdfu.h:49
uint16_t ui16Version
Definition: usbdfu.h:183
Definition: usbdfu.h:52
uint8_t bState
Definition: usbdfu.h:196
Definition: usbdfu.h:76
Definition: usbdfu.h:81
uint16_t ui16Marker
Definition: usbdfu.h:178
Definition: usbdfu.h:79
Definition: usbdfu.h:74
Definition: usbdfu.h:77
uint8_t ui8Reserved
Definition: usbdfu.h:280
Definition: usbdfu.h:50
Definition: usbdfu.h:68
uint16_t ui16NumFlashBlocks
Definition: usbdfu.h:473
Definition: usbdfu.h:78
Definition: usbdfu.h:69
uint16_t ui16StartAddr
Definition: usbdfu.h:285
Definition: usbdfu.h:75
Definition: usbdfu.h:67
uint16_t ui16NumBlocks
Definition: usbdfu.h:374
Definition: usbdfu.h:53
uint32_t ui32Length
Definition: usbdfu.h:291
uint8_t iString
Definition: usbdfu.h:197
uint32_t ui32AppStartAddr
Lowest address the boot loader can write or erase.
Definition: usbdfu.h:494
Definition: usbdfu.h:73
uint32_t ui32FlashTop
Address 1 byte above the highest location the boot loader can access.
Definition: usbdfu.h:489
Definition: usbdfu.h:72
Definition: usbdfu.h:46
uint8_t bStatus
Definition: usbdfu.h:194
Definition: usbdfu.h:71
uint16_t ui16FlashBlockSize
The size of a flash block in bytes.
Definition: usbdfu.h:467
Definition: usbdfu.h:55
Definition: usbdfu.h:51
uint8_t ui8Command
Definition: usbdfu.h:235
Definition: usbdfu.h:70
USB_CDC_GET/SET_LINE_CODING request-specific data.
Definition: usbaudio.h:288
© Copyright 1995-2020, Texas Instruments Incorporated. All rights reserved.
Trademarks | Privacy policy | Terms of use | Terms of sale