libusbdev/inc/usb_dfu.h

/* This file is the part of the LUS32 project
 *
 * Copyright ©2016 Dmitry Filimonchuk <dmitrystu[at]gmail[dot]com>
 *
 * 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_ */