X-Git-Url: http://git.linex4red.de/pub/USBasp.git/blobdiff_plain/559ca2ba046e47faa54f0845339f0385a5cfbb26..be9d0a5aa97c84cc8723f69f2b88576965e386aa:/LUFA/Drivers/USB/Class/Host/MassStorage.h diff --git a/LUFA/Drivers/USB/Class/Host/MassStorage.h b/LUFA/Drivers/USB/Class/Host/MassStorage.h index 1678aefee..8abe5734a 100644 --- a/LUFA/Drivers/USB/Class/Host/MassStorage.h +++ b/LUFA/Drivers/USB/Class/Host/MassStorage.h @@ -47,7 +47,6 @@ /* Includes: */ #include "../../USB.h" #include "../Common/MassStorage.h" - #include "../Common/SCSICodes.h" /* Enable C linkage for C++ Compilers: */ #if defined(__cplusplus) @@ -56,7 +55,8 @@ /* Public Interface - May be used in end-application: */ /* Macros: */ - #define MS_ERROR_LOGICAL_CMD_FAILED 0xC0 + /** Error code for some Mass Storage Host functions, indicating a logical (and not hardware) error */ + #define MS_ERROR_LOGICAL_CMD_FAILED 0x80 /* Type Defines: */ /** Class state structure. An instance of this structure should be made within the user application, @@ -74,10 +74,10 @@ */ struct { - bool Active; /**< Indicates if the current interface instance is connected to an attached device, valid - * after \ref HID_Host_ConfigurePipes() is called and the Host state machine is in the - * Configured state - */ + bool IsActive; /**< Indicates if the current interface instance is connected to an attached device, valid + * after \ref HID_Host_ConfigurePipes() is called and the Host state machine is in the + * Configured state + */ uint8_t InterfaceNumber; /**< Interface index of the HID interface within the attached device */ uint16_t DataINPipeSize; /**< Size in bytes of the MS interface's IN data pipe */ @@ -97,7 +97,7 @@ */ typedef struct { - uint8_t ReponseCode; + uint8_t ResponseCode; uint8_t SegmentNumber; @@ -164,13 +164,13 @@ } SCSI_Capacity_t; /* Enums: */ - enum + enum MSHost_EnumerationFailure_ErrorCodes_t { MS_ENUMERROR_NoError = 0, /**< Configuration Descriptor was processed successfully */ MS_ENUMERROR_InvalidConfigDescriptor = 1, /**< The device returned an invalid Configuration Descriptor */ MS_ENUMERROR_NoMSInterfaceFound = 2, /**< A compatible Mass Storage interface was not found in the device's Configuration Descriptor */ MS_ENUMERROR_EndpointsNotFound = 3, /**< Compatible Mass Storage endpoints were not found in the device's interfaces */ - } MSHost_EnumerationFailure_ErrorCodes_t; + }; /* Function Prototypes: */ /** General management task for a given Mass Storage host class interface, required for the correct operation of @@ -179,7 +179,7 @@ * * \param[in,out] MSInterfaceInfo Pointer to a structure containing an MS Class host configuration and state */ - void MS_Host_USBTask(USB_ClassInfo_MS_Host_t* MSInterfaceInfo) ATTR_NON_NULL_PTR_ARG(1); + void MS_Host_USBTask(USB_ClassInfo_MS_Host_t* const MSInterfaceInfo) ATTR_NON_NULL_PTR_ARG(1); /** Host interface configuration routine, to configure a given Mass Storage host interface instance using the * Configuration Descriptor read from an attached USB device. This function automatically updates the given Mass @@ -188,10 +188,12 @@ * the host state machine is in the Addressed state. * * \param[in,out] MSInterfaceInfo Pointer to a structure containing an MS Class host configuration and state - * \param[in] ConfigDescriptorLength Length of the attached device's Configuration Descriptor + * \param[in] ConfigDescriptorSize Length of the attached device's Configuration Descriptor * \param[in] DeviceConfigDescriptor Pointer to a buffer containing the attached device's Configuration Descriptor + * + * \return A value from the \ref MSHost_EnumerationFailure_ErrorCodes_t enum */ - uint8_t MS_Host_ConfigurePipes(USB_ClassInfo_MS_Host_t* MSInterfaceInfo, uint16_t ConfigDescriptorLength, + uint8_t MS_Host_ConfigurePipes(USB_ClassInfo_MS_Host_t* const MSInterfaceInfo, uint16_t ConfigDescriptorSize, uint8_t* DeviceConfigDescriptor) ATTR_NON_NULL_PTR_ARG(1, 3); /** Sends a MASS STORAGE RESET control request to the attached device, resetting the Mass Storage Interface @@ -201,7 +203,7 @@ * * \return A value from the \ref USB_Host_SendControlErrorCodes_t enum */ - uint8_t MS_Host_ResetMSInterface(USB_ClassInfo_MS_Host_t* MSInterfaceInfo) ATTR_NON_NULL_PTR_ARG(1); + uint8_t MS_Host_ResetMSInterface(USB_ClassInfo_MS_Host_t* const MSInterfaceInfo) ATTR_NON_NULL_PTR_ARG(1); /** Sends a GET MAX LUN control request to the attached device, retrieving the index of the highest LUN (Logical * UNit, a logical drive) in the device. This value can then be used in the other functions of the Mass Storage @@ -212,7 +214,7 @@ * * \return A value from the \ref USB_Host_SendControlErrorCodes_t enum */ - uint8_t MS_Host_GetMaxLUN(USB_ClassInfo_MS_Host_t* MSInterfaceInfo, uint8_t* MaxLUNIndex) ATTR_NON_NULL_PTR_ARG(1, 2); + uint8_t MS_Host_GetMaxLUN(USB_ClassInfo_MS_Host_t* const MSInterfaceInfo, uint8_t* const MaxLUNIndex) ATTR_NON_NULL_PTR_ARG(1, 2); /** Retrieves the Mass Storage device's inquiry data for the specified LUN, indicating the device characteristics and * properties. @@ -223,25 +225,82 @@ * * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum or MS_ERROR_LOGICAL_CMD_FAILED */ - uint8_t MS_Host_GetInquiryData(USB_ClassInfo_MS_Host_t* MSInterfaceInfo, uint8_t LUNIndex, - SCSI_Inquiry_Response_t* InquiryData) ATTR_NON_NULL_PTR_ARG(1, 3); + uint8_t MS_Host_GetInquiryData(USB_ClassInfo_MS_Host_t* const MSInterfaceInfo, const uint8_t LUNIndex, + SCSI_Inquiry_Response_t* const InquiryData) ATTR_NON_NULL_PTR_ARG(1, 3); - uint8_t MS_Host_TestUnitReady(USB_ClassInfo_MS_Host_t* MSInterfaceInfo, uint8_t LUNIndex) ATTR_NON_NULL_PTR_ARG(1); + /** Sends a TEST UNIT READY command to the device, to determine if it is ready to accept other SCSI commands. + * + * \param[in,out] MSInterfaceInfo Pointer to a structure containing a MS Class host configuration and state + * \param[in] LUNIndex LUN index within the device the command is being issued to + * + * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum or MS_ERROR_LOGICAL_CMD_FAILED if not ready + */ + uint8_t MS_Host_TestUnitReady(USB_ClassInfo_MS_Host_t* const MSInterfaceInfo, const uint8_t LUNIndex) ATTR_NON_NULL_PTR_ARG(1); - uint8_t MS_Host_ReadDeviceCapacity(USB_ClassInfo_MS_Host_t* MSInterfaceInfo, uint8_t LUNIndex, - SCSI_Capacity_t* DeviceCapacity) ATTR_NON_NULL_PTR_ARG(1, 3); + /** Retrieves the total capacity of the attached USB Mass Storage device, in blocks, and block size. + * + * \param[in,out] MSInterfaceInfo Pointer to a structure containing a MS Class host configuration and state + * \param[in] LUNIndex LUN index within the device the command is being issued to + * \param[out] DeviceCapacity Pointer to the location where the capacity information should be stored + * + * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum or MS_ERROR_LOGICAL_CMD_FAILED if not ready + */ + uint8_t MS_Host_ReadDeviceCapacity(USB_ClassInfo_MS_Host_t* const MSInterfaceInfo, const uint8_t LUNIndex, + SCSI_Capacity_t* const DeviceCapacity) ATTR_NON_NULL_PTR_ARG(1, 3); - uint8_t MS_Host_RequestSense(USB_ClassInfo_MS_Host_t* MSInterfaceInfo, uint8_t LUNIndex, - SCSI_Request_Sense_Response_t* SenseData) ATTR_NON_NULL_PTR_ARG(1, 3); + /** Retrieves the device sense data, indicating the current device state and error codes for the previously + * issued command. + * + * \param[in,out] MSInterfaceInfo Pointer to a structure containing a MS Class host configuration and state + * \param[in] LUNIndex LUN index within the device the command is being issued to + * \param[out] SenseData Pointer to the location where the sense information should be stored + * + * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum or MS_ERROR_LOGICAL_CMD_FAILED if not ready + */ + uint8_t MS_Host_RequestSense(USB_ClassInfo_MS_Host_t* const MSInterfaceInfo, const uint8_t LUNIndex, + SCSI_Request_Sense_Response_t* const SenseData) ATTR_NON_NULL_PTR_ARG(1, 3); - uint8_t MS_Host_PreventAllowMediumRemoval(USB_ClassInfo_MS_Host_t* MSInterfaceInfo, uint8_t LUNIndex, - bool PreventRemoval) ATTR_NON_NULL_PTR_ARG(1); + /** Issues a PREVENT MEDIUM REMOVAL command, to logically (or, depending on the type of device, physically) lock + * the device from removal so that blocks of data on the medium can be read or altered. + * + * \param[in,out] MSInterfaceInfo Pointer to a structure containing a MS Class host configuration and state + * \param[in] LUNIndex LUN index within the device the command is being issued to + * \param[in] PreventRemoval Boolean true if the device should be locked from removal, false otherwise + * + * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum or MS_ERROR_LOGICAL_CMD_FAILED if not ready + */ + uint8_t MS_Host_PreventAllowMediumRemoval(USB_ClassInfo_MS_Host_t* const MSInterfaceInfo, const uint8_t LUNIndex, + const bool PreventRemoval) ATTR_NON_NULL_PTR_ARG(1); - uint8_t MS_Host_ReadDeviceBlocks(USB_ClassInfo_MS_Host_t* MSInterfaceInfo, uint8_t LUNIndex, uint32_t BlockAddr, - uint8_t Blocks, uint16_t BlockSize, void* BlockBuffer) ATTR_NON_NULL_PTR_ARG(1, 6); + /** Reads blocks of data from the attached Mass Storage device's medium. + * + * \param[in,out] MSInterfaceInfo Pointer to a structure containing a MS Class host configuration and state + * \param[in] LUNIndex LUN index within the device the command is being issued to + * \param[in] BlockAddress Starting block address within the device to read from + * \param[in] Blocks Total number of blocks to read + * \param[in] BlockSize Size in bytes of each block within the device + * \param[out] BlockBuffer Pointer to where the read data from the device should be stored + * + * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum or MS_ERROR_LOGICAL_CMD_FAILED if not ready + */ + uint8_t MS_Host_ReadDeviceBlocks(USB_ClassInfo_MS_Host_t* const MSInterfaceInfo, const uint8_t LUNIndex, + const uint32_t BlockAddress, const uint8_t Blocks, const uint16_t BlockSize, + void* BlockBuffer) ATTR_NON_NULL_PTR_ARG(1, 6); - uint8_t MS_Host_WriteDeviceBlocks(USB_ClassInfo_MS_Host_t* MSInterfaceInfo, uint8_t LUNIndex, uint32_t BlockAddr, - uint8_t Blocks, uint16_t BlockSize, void* BlockBuffer) ATTR_NON_NULL_PTR_ARG(1, 6); + /** Writes blocks of data to the attached Mass Storage device's medium. + * + * \param[in,out] MSInterfaceInfo Pointer to a structure containing a MS Class host configuration and state + * \param[in] LUNIndex LUN index within the device the command is being issued to + * \param[in] BlockAddress Starting block address within the device to write to + * \param[in] Blocks Total number of blocks to read + * \param[in] BlockSize Size in bytes of each block within the device + * \param[in] BlockBuffer Pointer to where the data to write should be sourced from + * + * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum or MS_ERROR_LOGICAL_CMD_FAILED if not ready + */ + uint8_t MS_Host_WriteDeviceBlocks(USB_ClassInfo_MS_Host_t* const MSInterfaceInfo, const uint8_t LUNIndex, + const uint32_t BlockAddress, const uint8_t Blocks, const uint16_t BlockSize, + void* BlockBuffer) ATTR_NON_NULL_PTR_ARG(1, 6); /* Private Interface - For use in library only: */ #if !defined(__DOXYGEN__) @@ -266,11 +325,12 @@ /* Function Prototypes: */ #if defined(INCLUDE_FROM_MS_CLASS_HOST_C) - static uint8_t DComp_NextMassStorageInterface(void* CurrentDescriptor); - static uint8_t DComp_NextInterfaceBulkDataEndpoint(void* CurrentDescriptor); + static uint8_t DComp_NextMSInterface(void* CurrentDescriptor); + static uint8_t DComp_NextMSInterfaceEndpoint(void* CurrentDescriptor); static uint8_t MS_Host_SendCommand(USB_ClassInfo_MS_Host_t* MSInterfaceInfo, - MS_CommandBlockWrapper_t* SCSICommandBlock); + MS_CommandBlockWrapper_t* SCSICommandBlock, + void* BufferPtr); static uint8_t MS_Host_WaitForDataReceived(USB_ClassInfo_MS_Host_t* MSInterfaceInfo); static uint8_t MS_Host_SendReceiveData(USB_ClassInfo_MS_Host_t* MSInterfaceInfo, MS_CommandBlockWrapper_t* SCSICommandBlock, void* BufferPtr);