X-Git-Url: http://git.linex4red.de/pub/lufa.git/blobdiff_plain/d1e52660368d34d693131f6aff3c8fd8584162e5..b2330934b9ccd51a59183eb2a11fdd95183df27b:/LUFA/Drivers/USB/Class/Device/MassStorage.h diff --git a/LUFA/Drivers/USB/Class/Device/MassStorage.h b/LUFA/Drivers/USB/Class/Device/MassStorage.h index c1874b218..0ecc4aa1d 100644 --- a/LUFA/Drivers/USB/Class/Device/MassStorage.h +++ b/LUFA/Drivers/USB/Class/Device/MassStorage.h @@ -28,6 +28,20 @@ this software. */ +/** \ingroup Group_USBDeviceClassDrivers + * @defgroup Group_USBClassMSDevice Mass Storage Device Class Driver - LUFA/Drivers/Class/Device/MassStorage.h + * + * \section Sec_Dependencies Module Source Dependencies + * The following files must be built with any user project that uses this module: + * - LUFA/Drivers/USB/Class/Device/MassStorage.c + * + * \section Module Description + * Functions, macros, variables, enums and types related to the management of USB Mass Storage Class interfaces + * within a USB device. + * + * @{ + */ + #ifndef _MS_CLASS_H_ #define _MS_CLASS_H_ @@ -36,27 +50,29 @@ #include + /* Enable C linkage for C++ Compilers: */ + #if defined(__cplusplus) + extern "C" { + #endif + /* Macros: */ /** Mass Storage Class specific request to reset the Mass Storage interface, ready for the next command. */ #define REQ_MassStorageReset 0xFF /** Mass Storage Class specific request to retrieve the total number of Logical Units (drives) in the SCSI device. */ #define REQ_GetMaxLUN 0xFE - - /** Maximum length of a SCSI command which can be issued by the device or host in a Mass Storage bulk wrapper. */ - #define MAX_SCSI_COMMAND_LENGTH 16 /** Magic signature for a Command Block Wrapper used in the Mass Storage Bulk-Only transport protocol. */ - #define CBW_SIGNATURE 0x43425355UL + #define MS_CBW_SIGNATURE 0x43425355UL /** Magic signature for a Command Status Wrapper used in the Mass Storage Bulk-Only transport protocol. */ - #define CSW_SIGNATURE 0x53425355UL + #define MS_CSW_SIGNATURE 0x53425355UL /** Mask for a Command Block Wrapper's flags attribute to specify a command with data sent from host-to-device. */ - #define COMMAND_DIRECTION_DATA_OUT (0 << 7) + #define MS_COMMAND_DIR_DATA_OUT (0 << 7) /** Mask for a Command Block Wrapper's flags attribute to specify a command with data sent from device-to-host. */ - #define COMMAND_DIRECTION_DATA_IN (1 << 7) + #define MS_COMMAND_DIR_DATA_IN (1 << 7) /* Type defines: */ /** Type define for a Command Block Wrapper, used in the Mass Storage Bulk-Only Transport protocol. */ @@ -68,7 +84,7 @@ uint8_t Flags; /**< Command block flags, indicating command data direction */ uint8_t LUN; /**< Logical Unit number this command is issued to */ uint8_t SCSICommandLength; /**< Length of the issued SCSI command within the SCSI command data array */ - uint8_t SCSICommandData[MAX_SCSI_COMMAND_LENGTH]; /**< Issued SCSI command in the Command Block */ + uint8_t SCSICommandData[16]; /**< Issued SCSI command in the Command Block */ } CommandBlockWrapper_t; /** Type define for a Command Status Wrapper, used in the Mass Storage Bulk-Only Transport protocol. */ @@ -84,14 +100,16 @@ /** Enum for the possible command status wrapper return status codes. */ enum MassStorage_CommandStatusCodes_t { - Command_Pass = 0, /**< Command completed with no error */ - Command_Fail = 1, /**< Command failed to complete - host may check the exact error via a SCSI REQUEST SENSE command */ - Phase_Error = 2 /**< Command failed due to being invalid in the current phase */ + SCSI_Command_Pass = 0, /**< Command completed with no error */ + SCSI_Command_Fail = 1, /**< Command failed to complete - host may check the exact error via a SCSI REQUEST SENSE command */ + SCSI_Phase_Error = 2 /**< Command failed due to being invalid in the current phase */ }; /* Type Defines: */ - /** Type define for the virtual serial port line encoding settings, for storing the current USART configuration - * as set by the host via a class specific request. + /** Class state structure. An instance of this structure should be made for each Mass Storage interface + * within the user application, and passed to each of the Mass Storage class driver functions as the + * MSInterfaceInfo parameter. The contents of this structure should be set to their correct + * values when used, or ommitted to force the library to use default values. */ typedef struct { @@ -103,12 +121,18 @@ uint8_t DataOUTEndpointNumber; /**< Endpoint number of the Mass Storage interface's OUT data endpoint */ uint16_t DataOUTEndpointSize; /**< Size in bytes of the Mass Storage interface's OUT data endpoint */ - uint8_t TotalLUNs; + uint8_t TotalLUNs; /**< Total number of logical drives in the Mass Storage interface */ - CommandBlockWrapper_t CommandBlock; - CommandStatusWrapper_t CommandStatus; + CommandBlockWrapper_t CommandBlock; /**< Mass Storage class command block structure, used internally + * by the class driver + */ + CommandStatusWrapper_t CommandStatus; /**< Mass Storage class command status structure, used internally + * by the class driver + */ - bool IsMassStoreReset; + bool IsMassStoreReset; /**< Flag indicating that the host has requested that the Mass Storage interface be reset + * and that all current Mass Storage operations should immediately abort + */ } USB_ClassInfo_MS_t; /* Function Prototypes: */ @@ -118,10 +142,46 @@ static uint8_t StreamCallback_AbortOnMassStoreReset(void); #endif - void USB_MS_USBTask(USB_ClassInfo_MS_t* MSInterfaceInfo); + /** Configures the endpoints of a given Mass Storage interface, ready for use. This should be linked to the library + * \ref EVENT_USB_ConfigurationChanged() event so that the endpoints are configured when the configuration + * containing the given Mass Storage interface is selected. + * + * \param MSInterfaceInfo Pointer to a structure containing a Mass Storage Class configuration and state. + * + * \return Boolean true if the endpoints were sucessfully configured, false otherwise + */ bool USB_MS_ConfigureEndpoints(USB_ClassInfo_MS_t* MSInterfaceInfo); + + /** Processes incomming control requests from the host, that are directed to the given Mass Storage class interface. This should be + * linked to the library \ref EVENT_USB_UnhandledControlPacket() event. + * + * \param MSInterfaceInfo Pointer to a structure containing a Mass Storage Class configuration and state. + */ void USB_MS_ProcessControlPacket(USB_ClassInfo_MS_t* MSInterfaceInfo); + + /** General management task for a given Mass Storage class interface, required for the correct operation of the interface. This should + * be called frequently in the main program loop, before the master USB management task \ref USB_USBTask(). + * + * \param MSInterfaceInfo Pointer to a structure containing a Mass Storage configuration and state. + */ + void USB_MS_USBTask(USB_ClassInfo_MS_t* MSInterfaceInfo); + /** Mass Storage class driver callback for the user processing of a received SCSI command. This callback will fire each time the + * host sends a SCSI command which requires processing by the user application. Inside this callback the user is responsible + * for the processing of the received SCSI command from the host. The SCSI command is available in the CommandBlock structure + * inside the Mass Storage class state structure passed as a parameter to the callback function. + * + * \param MSInterfaceInfo Pointer to a structure containing a Mass Storage Class configuration and state. + * + * \return Boolean true if the SCSI command was successfully processed, false otherwise + */ bool CALLBACK_USB_MS_SCSICommandReceived(USB_ClassInfo_MS_t* MSInterfaceInfo); + /* Disable C linkage for C++ Compilers: */ + #if defined(__cplusplus) + } + #endif + #endif + +/** @} */