/* This file is the part of the LUS32 project * * Copyright ©2016 Dmitry Filimonchuk * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * http://www.apache.org/licenses/LICENSE-2.0 * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ #ifndef _USB_DFU_H_ #define _USB_DFU_H_ #if defined(__cplusplus) extern "C" { #endif /** \addtogroup USB_MODULE_DFU USB DFU class * \brief This module contains USB Device Firmware Upgrade class definitions. * \details This module based on * + [USB Device Firmware Upgrade Specification, Revision 1.1](http://www.usb.org/developers/docs/devclass_docs/DFU_1.1.pdf) * @{ */ /**\name USB DFU class subclass and protocol definitions * @{ */ #define USB_CLASS_DFU 0xFE /**< USB DFU class is an application-specified class */ #define USB_DFU_SUBCLASS_DFU 0x01 /**< USB DFU subclass code */ #define USB_DFU_PROTO_RUNTIME 0x01 /**< USB DFU runtime-mode protocol */ #define USB_DFU_PROTO_DFU 0x02 /**< USB DFU DFU-mode protocol */ /** @{ */ /**\name USB DFU descriptor types */ #define USB_DTYPE_DFU_FUNCTIONAL 0x21 /**< USB DFU functional descriptor type */ /**\name USB DFU class-specific requests * @{ */ #define USB_DFU_DETACH 0x00 /**< Initiates a detach-attach sequence on the bus when it sees this request. */ #define USB_DFU_DNLOAD 0x01 /**< Initiates firmware image downloading */ #define USB_DFU_UPLOAD 0x02 /**< This request is employed by the host to solicit firmware from the device.*/ #define USB_DFU_GETSTATUS 0x03 /**< The host employs this request to facilitate synchronization with the device. \see usb_dfu_status */ #define USB_DFU_CLRSTATAUS 0x04 /**< This request resets DFU machine state to DFU_IDLE*/ #define USB_DFU_GETSTATE 0x05 /**< This request solicits a report about the state of the device. */ #define USB_DFU_ABORT 0x06 /**< This request enables the host to exit from certain states and return to the DFU_IDLE state*/ /** @} */ /**\anchor USB_DFU_CAPAB * \name USB DFU capabilities * @{ */ #define USB_DFU_ATTR_WILL_DETACH 0x08 /**< Device will perform a bus detach-attach sequence when it receives a DFU_DETACH request. */ #define USB_DFU_ATTR_MANIF_TOL 0x04 /**< Device is able to communicate via USB after Manifestation phase. */ #define USB_DFU_ATTR_CAN_UPLOAD 0x02 /**< Upload capable. */ #define USB_DFU_ATTR_CAN_DNLOAD 0x01 /**< Download capable. */ /** @} */ /**\name USB DFU status codes * @{ */ #define USB_DFU_STATUS_OK 0x00 /**< No error condition is present. */ #define USB_DFU_STATUS_ERR_TARGET 0x01 /**< File is not targeted for use by this device. */ #define USB_DFU_STATUS_ERR_FILE 0x02 /**< File is for this device but fails some vendor specific verification test. */ #define USB_DFU_STATUS_ERR_WRITE 0x03 /**< Device is unable to write memory. */ #define USB_DFU_STATUS_ERR_ERASE 0x04 /**< Memory erase function failed. */ #define USB_DFU_STATUS_ERR_CHECK_ERASED 0x05 /**< Memory erase check failed. */ #define USB_DFU_STATUS_ERR_PROG 0x06 /**< Program memory function failed. */ #define USB_DFU_STATUS_ERR_VERIFY 0x07 /**< Programmed memory failed verification. */ #define USB_DFU_STATUS_ERR_ADDRESS 0x08 /**< Cannot program memory due to received address that is out of range. */ #define USB_DFU_STATUS_ERR_NOTDONE 0x09 /**< Received DFU_DNLOAD with wLength = 0, but device does not think it has all of the data yet. */ #define USB_DFU_STATUS_ERR_FIRMWARE 0x0A /**< Device's firmware is corrupt. It cannot return to run-time (non-DFU) operations. */ #define USB_DFU_STATUS_ERR_VENDOR 0x0B /**< iString indicates a vendor-specific error. */ #define USB_DFU_STATUS_ERR_USBR 0x0C /**< Device detected unexpected USB reset signaling. */ #define USB_DFU_STATUS_ERR_POR 0x0D /**< Device detected unexpected power on reset. */ #define USB_DFU_STATUS_ERR_UNKNOWN 0x0E /**< Something went wrong, but the device does not know what it was. */ #define USB_DFU_STATUS_ERR_STALLEDPKT 0x0F /**< Device stalled an unexpected request. */ /** @} */ /**\name USB DFU state codes * @{ */ #define USB_DFU_STATE_APP_IDLE 0x00 /**< Device is running its normal application. */ #define USB_DFU_STATE_APP_DETACH 0x01 /**< Device is running its normal application, has received the DFU_DETACH request, and is waiting for a USB reset. */ #define USB_DFU_STATE_DFU_IDLE 0x02 /**< Device is operating in the DFU mode and is waiting for requests. */ #define USB_DFU_STATE_DFU_DNLOADSYNC 0x03 /**< Device has received a block and is waiting for the host to solicit the status via DFU_GETSTATUS. */ #define USB_DFU_STATE_DFU_DNBUSY 0x04 /**< Device is programming a control-write block into its nonvolatile memories. */ #define USB_DFU_STATE_DFU_DNLOADIDLE 0x05 /**< Device is processing a download operation. Expecting DFU_DNLOAD requests. */ #define USB_DFU_STATE_DFU_MANIFESTSYNC 0x06 /**< Device has received the final block of firmware from the host * and is waiting for receipt of DFU_GETSTATUS to begin the Manifestation * phase; or device has completed the Manifestation phase and is waiting * for receipt of DFU_GETSTATUS. (Devices that can enter this state * after the Manifestation phase set bmAttributes bit bitManifestationTolerant to 1.) */ #define USB_DFU_STATE_DFU_MANIFEST 0x07 /**< Device is in the Manifestation phase. (Not all devices will be able to respond to DFU_GETSTATUS when in this state.) */ #define USB_DFU_STATE_DFU_MANIFESTWR 0x08 /**< Device has programmed its memories and is waiting for a USB reset or a * power on reset. (Devices that must enter this state clear bitManifestationTolerant to 0.) */ #define USB_DFU_STATE_DFU_UPLOADIDLE 0x09 /**< The device is processing an upload operation. Expecting DFU_UPLOAD requests. */ #define USB_DFU_STATE_DFU_ERROR 0x0A /**< An error has occurred. Awaiting the DFU_CLRSTATUS request. */ /** @} */ /** \brief USB DFU functional descriptor */ struct usb_dfu_func_desc { uint8_t bLength; /**< Descriptor length in bytes. */ uint8_t bDescriptorType; /**< Descriptor type, set it to \ref USB_DTYPE_DFU_FUNCTIONAL */ uint8_t bmAttributes; /**< Bitmap field of the \ref USB_DFU_CAPAB "USB DFU capabilities"*/ uint16_t wDetachTimeout; /**< USB DFU detach timeout in ms */ uint16_t wTransferSize; /**< USB DFU maximum transfer block size in bytes */ uint16_t bcdDFUVersion; /**< USB DFU version \ref VERSION_BCD utility macro */ }__attribute__((packed)); /** \brief Payload packet to response in DFU_GETSTATUS request */ struct usb_dfu_status { uint8_t bStatus; /**< An indication of the status resulting from the execution of the most recent request.*/ uint8_t bPollTimeout; uint16_t wPollTimeout; /**< Minimum time, (ms), that the host should wait before sending a subsequent \ref USB_DFU_GETSTATUS "DFU_GETSTATUS" request. */ uint8_t bState; /**< An indication of the state that the device is going to enter immediately following transmission of this response. */ uint8_t iString; /**< Index of the status \ref usb_string_descriptor "string descriptor". */ }; /** @} */ #if defined(__cplusplus) } #endif #endif /* _USB_DFU_H_ */