3 Copyright (C) Dean Camera, 2014.
5 dean [at] fourwalledcubicle [dot] com
10 Copyright 2014 Dean Camera (dean [at] fourwalledcubicle [dot] com)
12 Permission to use, copy, modify, distribute, and sell this
13 software and its documentation for any purpose is hereby granted
14 without fee, provided that the above copyright notice appear in
15 all copies and that both that the copyright notice and this
16 permission notice and warranty disclaimer appear in supporting
17 documentation, and that the name of the author not be used in
18 advertising or publicity pertaining to distribution of the
19 software without specific, written prior permission.
21 The author disclaims all warranties with regard to this
22 software, including all implied warranties of merchantability
23 and fitness. In no event shall the author be liable for any
24 special, indirect or consequential damages or any damages
25 whatsoever resulting from loss of use, data or profits, whether
26 in an action of contract, negligence or other tortious action,
27 arising out of or in connection with the use or performance of
32 * \brief Host mode driver for the library USB Mass Storage Class driver.
34 * Host mode driver for the library USB Mass Storage Class driver.
36 * \note This file should not be included directly. It is automatically included as needed by the USB module driver
37 * dispatch header located in LUFA/Drivers/USB.h.
40 /** \ingroup Group_USBClassMS
41 * \defgroup Group_USBClassMassStorageHost Mass Storage Class Host Mode Driver
43 * \section Sec_USBClassMassStorageHost_Dependencies Module Source Dependencies
44 * The following files must be built with any user project that uses this module:
45 * - LUFA/Drivers/USB/Class/Host/MassStorageClassHost.c <i>(Makefile source module name: LUFA_SRC_USBCLASS)</i>
47 * \section Sec_USBClassMassStorageHost_ModDescription Module Description
48 * Host Mode USB Class driver framework interface, for the Mass Storage USB Class driver.
53 #ifndef __MS_CLASS_HOST_H__
54 #define __MS_CLASS_HOST_H__
57 #include "../../USB.h"
58 #include "../Common/MassStorageClassCommon.h"
60 /* Enable C linkage for C++ Compilers: */
61 #if defined(__cplusplus)
65 /* Preprocessor Checks: */
66 #if !defined(__INCLUDE_FROM_MS_DRIVER)
67 #error Do not include this file directly. Include LUFA/Drivers/USB.h instead.
70 /* Public Interface - May be used in end-application: */
72 /** Error code for some Mass Storage Host functions, indicating a logical (and not hardware) error. */
73 #define MS_ERROR_LOGICAL_CMD_FAILED 0x80
76 /** \brief Mass Storage Class Host Mode Configuration and State Structure.
78 * Class state structure. An instance of this structure should be made within the user application,
79 * and passed to each of the Mass Storage class driver functions as the \c MSInterfaceInfo parameter. This
80 * stores each Mass Storage interface's configuration and state information.
86 USB_Pipe_Table_t DataINPipe; /**< Data IN Pipe configuration table. */
87 USB_Pipe_Table_t DataOUTPipe; /**< Data OUT Pipe configuration table. */
88 } Config; /**< Config data for the USB class interface within the device. All elements in this section
89 * <b>must</b> be set or the interface will fail to enumerate and operate correctly.
93 bool IsActive; /**< Indicates if the current interface instance is connected to an attached device, valid
94 * after \ref MS_Host_ConfigurePipes() is called and the Host state machine is in the
97 uint8_t InterfaceNumber; /**< Interface index of the Mass Storage interface within the attached device. */
99 uint32_t TransactionTag; /**< Current transaction tag for data synchronizing of packets. */
100 } State; /**< State data for the USB class interface within the device. All elements in this section
101 * <b>may</b> be set to initial values, but may also be ignored to default to sane values when
102 * the interface is enumerated.
104 } USB_ClassInfo_MS_Host_t;
106 /** \brief SCSI Device LUN Capacity Structure.
108 * SCSI capacity structure, to hold the total capacity of the device in both the number
109 * of blocks in the current LUN, and the size of each block. This structure is filled by
110 * the device when the \ref MS_Host_ReadDeviceCapacity() function is called.
114 uint32_t Blocks; /**< Number of blocks in the addressed LUN of the device. */
115 uint32_t BlockSize; /**< Number of bytes in each block in the addressed LUN. */
119 /** Enum for the possible error codes returned by the \ref MS_Host_ConfigurePipes() function. */
120 enum MS_Host_EnumerationFailure_ErrorCodes_t
122 MS_ENUMERROR_NoError = 0, /**< Configuration Descriptor was processed successfully. */
123 MS_ENUMERROR_InvalidConfigDescriptor = 1, /**< The device returned an invalid Configuration Descriptor. */
124 MS_ENUMERROR_NoCompatibleInterfaceFound = 2, /**< A compatible Mass Storage interface was not found in the device's Configuration Descriptor. */
125 MS_ENUMERROR_PipeConfigurationFailed = 3, /**< One or more pipes for the specified interface could not be configured correctly. */
128 /* Function Prototypes: */
129 /** Host interface configuration routine, to configure a given Mass Storage host interface instance using the
130 * Configuration Descriptor read from an attached USB device. This function automatically updates the given Mass
131 * Storage Host instance's state values and configures the pipes required to communicate with the interface if it
132 * is found within the device. This should be called once after the stack has enumerated the attached device, while
133 * the host state machine is in the Addressed state.
135 * \param[in,out] MSInterfaceInfo Pointer to a structure containing an MS Class host configuration and state.
136 * \param[in] ConfigDescriptorSize Length of the attached device's Configuration Descriptor.
137 * \param[in] DeviceConfigDescriptor Pointer to a buffer containing the attached device's Configuration Descriptor.
139 * \return A value from the \ref MS_Host_EnumerationFailure_ErrorCodes_t enum.
141 uint8_t MS_Host_ConfigurePipes(USB_ClassInfo_MS_Host_t* const MSInterfaceInfo,
142 uint16_t ConfigDescriptorSize,
143 void* DeviceConfigDescriptor) ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(3);
145 /** Sends a MASS STORAGE RESET control request to the attached device, resetting the Mass Storage Interface
146 * and readying it for the next Mass Storage command. This should be called after a failed SCSI request to
147 * ensure the attached Mass Storage device is ready to receive the next command.
149 * \param[in,out] MSInterfaceInfo Pointer to a structure containing a MS Class host configuration and state.
151 * \return A value from the \ref USB_Host_SendControlErrorCodes_t enum.
153 uint8_t MS_Host_ResetMSInterface(USB_ClassInfo_MS_Host_t* const MSInterfaceInfo) ATTR_NON_NULL_PTR_ARG(1);
155 /** Sends a GET MAX LUN control request to the attached device, retrieving the index of the highest LUN (Logical
156 * UNit, a logical drive) in the device. This value can then be used in the other functions of the Mass Storage
157 * Host mode Class driver to address a specific LUN within the device.
159 * \note Some devices do not support this request, and will STALL it when issued. To get around this,
160 * on unsupported devices the max LUN index will be reported as zero and no error will be returned
161 * if the device STALLs the request.
163 * \param[in,out] MSInterfaceInfo Pointer to a structure containing a MS Class host configuration and state.
164 * \param[out] MaxLUNIndex Pointer to a location where the highest LUN index value should be stored.
166 * \return A value from the \ref USB_Host_SendControlErrorCodes_t enum.
168 uint8_t MS_Host_GetMaxLUN(USB_ClassInfo_MS_Host_t* const MSInterfaceInfo,
169 uint8_t* const MaxLUNIndex) ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(2);
171 /** Retrieves the Mass Storage device's inquiry data for the specified LUN, indicating the device characteristics and
174 * \pre This function must only be called when the Host state machine is in the \ref HOST_STATE_Configured state or the
177 * \param[in,out] MSInterfaceInfo Pointer to a structure containing a MS Class host configuration and state.
178 * \param[in] LUNIndex LUN index within the device the command is being issued to.
179 * \param[out] InquiryData Location where the read inquiry data should be stored.
181 * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum or \ref MS_ERROR_LOGICAL_CMD_FAILED.
183 uint8_t MS_Host_GetInquiryData(USB_ClassInfo_MS_Host_t* const MSInterfaceInfo,
184 const uint8_t LUNIndex,
185 SCSI_Inquiry_Response_t* const InquiryData) ATTR_NON_NULL_PTR_ARG(1)
186 ATTR_NON_NULL_PTR_ARG(3);
188 /** Sends a TEST UNIT READY command to the device, to determine if it is ready to accept other SCSI commands.
190 * \param[in,out] MSInterfaceInfo Pointer to a structure containing a MS Class host configuration and state.
191 * \param[in] LUNIndex LUN index within the device the command is being issued to.
193 * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum or \ref MS_ERROR_LOGICAL_CMD_FAILED if not ready.
195 uint8_t MS_Host_TestUnitReady(USB_ClassInfo_MS_Host_t* const MSInterfaceInfo,
196 const uint8_t LUNIndex) ATTR_NON_NULL_PTR_ARG(1);
198 /** Retrieves the total capacity of the attached USB Mass Storage device, in blocks, and block size.
200 * \pre This function must only be called when the Host state machine is in the \ref HOST_STATE_Configured state or the
203 * \param[in,out] MSInterfaceInfo Pointer to a structure containing a MS Class host configuration and state.
204 * \param[in] LUNIndex LUN index within the device the command is being issued to.
205 * \param[out] DeviceCapacity Pointer to the location where the capacity information should be stored.
207 * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum or \ref MS_ERROR_LOGICAL_CMD_FAILED if not ready.
209 uint8_t MS_Host_ReadDeviceCapacity(USB_ClassInfo_MS_Host_t* const MSInterfaceInfo,
210 const uint8_t LUNIndex,
211 SCSI_Capacity_t* const DeviceCapacity) ATTR_NON_NULL_PTR_ARG(1)
212 ATTR_NON_NULL_PTR_ARG(3);
214 /** Retrieves the device sense data, indicating the current device state and error codes for the previously
217 * \pre This function must only be called when the Host state machine is in the \ref HOST_STATE_Configured state or the
220 * \param[in,out] MSInterfaceInfo Pointer to a structure containing a MS Class host configuration and state.
221 * \param[in] LUNIndex LUN index within the device the command is being issued to.
222 * \param[out] SenseData Pointer to the location where the sense information should be stored.
224 * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum or \ref MS_ERROR_LOGICAL_CMD_FAILED if not ready.
226 uint8_t MS_Host_RequestSense(USB_ClassInfo_MS_Host_t* const MSInterfaceInfo,
227 const uint8_t LUNIndex,
228 SCSI_Request_Sense_Response_t* const SenseData) ATTR_NON_NULL_PTR_ARG(1)
229 ATTR_NON_NULL_PTR_ARG(3);
231 /** Issues a PREVENT MEDIUM REMOVAL command, to logically (or, depending on the type of device, physically) lock
232 * the device from removal so that blocks of data on the medium can be read or altered.
234 * \pre This function must only be called when the Host state machine is in the \ref HOST_STATE_Configured state or the
237 * \param[in,out] MSInterfaceInfo Pointer to a structure containing a MS Class host configuration and state.
238 * \param[in] LUNIndex LUN index within the device the command is being issued to.
239 * \param[in] PreventRemoval Boolean \c true if the device should be locked from removal, \c false otherwise.
241 * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum or \ref MS_ERROR_LOGICAL_CMD_FAILED if not ready.
243 uint8_t MS_Host_PreventAllowMediumRemoval(USB_ClassInfo_MS_Host_t* const MSInterfaceInfo,
244 const uint8_t LUNIndex,
245 const bool PreventRemoval) ATTR_NON_NULL_PTR_ARG(1);
247 /** Reads blocks of data from the attached Mass Storage device's medium.
249 * \pre This function must only be called when the Host state machine is in the \ref HOST_STATE_Configured state or the
252 * \param[in,out] MSInterfaceInfo Pointer to a structure containing a MS Class host configuration and state.
253 * \param[in] LUNIndex LUN index within the device the command is being issued to.
254 * \param[in] BlockAddress Starting block address within the device to read from.
255 * \param[in] Blocks Total number of blocks to read.
256 * \param[in] BlockSize Size in bytes of each block within the device.
257 * \param[out] BlockBuffer Pointer to where the read data from the device should be stored.
259 * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum or \ref MS_ERROR_LOGICAL_CMD_FAILED if not ready.
261 uint8_t MS_Host_ReadDeviceBlocks(USB_ClassInfo_MS_Host_t* const MSInterfaceInfo,
262 const uint8_t LUNIndex,
263 const uint32_t BlockAddress,
264 const uint8_t Blocks,
265 const uint16_t BlockSize,
266 void* BlockBuffer) ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(6);
268 /** Writes blocks of data to the attached Mass Storage device's medium.
270 * \pre This function must only be called when the Host state machine is in the \ref HOST_STATE_Configured state or the
273 * \param[in,out] MSInterfaceInfo Pointer to a structure containing a MS Class host configuration and state.
274 * \param[in] LUNIndex LUN index within the device the command is being issued to.
275 * \param[in] BlockAddress Starting block address within the device to write to.
276 * \param[in] Blocks Total number of blocks to read.
277 * \param[in] BlockSize Size in bytes of each block within the device.
278 * \param[in] BlockBuffer Pointer to where the data to write should be sourced from.
280 * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum or \ref MS_ERROR_LOGICAL_CMD_FAILED if not ready.
282 uint8_t MS_Host_WriteDeviceBlocks(USB_ClassInfo_MS_Host_t* const MSInterfaceInfo,
283 const uint8_t LUNIndex,
284 const uint32_t BlockAddress,
285 const uint8_t Blocks,
286 const uint16_t BlockSize,
287 const void* BlockBuffer) ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(6);
289 /* Inline Functions: */
290 /** General management task for a given Mass Storage host class interface, required for the correct operation of
291 * the interface. This should be called frequently in the main program loop, before the master USB management task
292 * \ref USB_USBTask().
294 * \param[in,out] MSInterfaceInfo Pointer to a structure containing an Mass Storage Class host configuration and state.
296 static inline void MS_Host_USBTask(USB_ClassInfo_MS_Host_t* const MSInterfaceInfo) ATTR_NON_NULL_PTR_ARG(1) ATTR_ALWAYS_INLINE;
297 static inline void MS_Host_USBTask(USB_ClassInfo_MS_Host_t* const MSInterfaceInfo)
299 (void)MSInterfaceInfo;
302 /* Private Interface - For use in library only: */
303 #if !defined(__DOXYGEN__)
305 #define MS_COMMAND_DATA_TIMEOUT_MS 10000
307 /* Function Prototypes: */
308 #if defined(__INCLUDE_FROM_MASSSTORAGE_HOST_C)
309 static uint8_t MS_Host_SendCommand(USB_ClassInfo_MS_Host_t* const MSInterfaceInfo,
310 MS_CommandBlockWrapper_t* const SCSICommandBlock,
311 const void* const BufferPtr) ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(2);
312 static uint8_t MS_Host_WaitForDataReceived(USB_ClassInfo_MS_Host_t* const MSInterfaceInfo) ATTR_NON_NULL_PTR_ARG(1);
313 static uint8_t MS_Host_SendReceiveData(USB_ClassInfo_MS_Host_t* const MSInterfaceInfo,
314 MS_CommandBlockWrapper_t* const SCSICommandBlock,
315 void* BufferPtr) ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(2);
316 static uint8_t MS_Host_GetReturnedStatus(USB_ClassInfo_MS_Host_t* const MSInterfaceInfo,
317 MS_CommandStatusWrapper_t* const SCSICommandStatus)
318 ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(2);
320 static uint8_t DCOMP_MS_Host_NextMSInterface(void* const CurrentDescriptor)
321 ATTR_WARN_UNUSED_RESULT ATTR_NON_NULL_PTR_ARG(1);
322 static uint8_t DCOMP_MS_Host_NextMSInterfaceEndpoint(void* const CurrentDescriptor)
323 ATTR_WARN_UNUSED_RESULT ATTR_NON_NULL_PTR_ARG(1);
327 /* Disable C linkage for C++ Compilers: */
328 #if defined(__cplusplus)