1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
|
/***********************************************************************
* $Id:: mw_usbd_mscuser.h 202 2011-06-12 21:50:01Z usb06052 $
*
* Project: USB device ROM Stack
*
* Description:
* Mass Storage Class Custom User Module definitions.
*
***********************************************************************
* Copyright(C) 2011, NXP Semiconductor
* All rights reserved.
*
* Software that is described herein is for illustrative purposes only
* which provides customers with programming information regarding the
* products. This software is supplied "AS IS" without any warranties.
* NXP Semiconductors assumes no responsibility or liability for the
* use of the software, conveys no license or title under any patent,
* copyright, or mask work right to the product. NXP Semiconductors
* reserves the right to make changes in the software without
* notification. NXP Semiconductors also make no representation or
* warranty that such application will be suitable for the specified
* use without further testing or modification.
**********************************************************************/
#ifndef __MSCUSER_H__
#define __MSCUSER_H__
#include "error.h"
#include "mw_usbd.h"
#include "mw_usbd_msc.h"
#include "mw_usbd_core.h"
#include "tusb_option.h"
/** \file
* \brief Mass Storage Class (MSC) API structures and function prototypes.
*
* Definition of functions exported by ROM based MSC function driver.
*
*/
/** \ingroup Group_USBD
* @defgroup USBD_MSC Mass Storage Class (MSC) Function Driver
* \section Sec_MSCModDescription Module Description
* MSC Class Function Driver module. This module contains an internal implementation of the USB MSC Class.
* User applications can use this class driver instead of implementing the MSC class manually
* via the low-level USBD_HW and USBD_Core APIs.
*
* This module is designed to simplify the user code by exposing only the required interface needed to interface with
* Devices using the USB MSC Class.
*/
/** \brief Mass Storage class function driver initilization parameter data structure.
* \ingroup USBD_MSC
*
* \details This data structure is used to pass initialization parameters to the
* Mass Storage class function driver's init function.
*
*/
typedef struct USBD_MSC_INIT_PARAM
{
/* memory allocation params */
uint32_t mem_base; /**< Base memory location from where the stack can allocate
data and buffers. \note The memory address set in this field
should be accessible by USB DMA controller. Also this value
should be aligned on 4 byte boundary.
*/
uint32_t mem_size; /**< The size of memory buffer which stack can use.
\note The \em mem_size should be greater than the size
returned by USBD_MSC_API::GetMemSize() routine.*/
/* mass storage paramas */
uint8_t* InquiryStr; /**< Pointer to the 28 character string. This string is
sent in response to the SCSI Inquiry command. \note The data
pointed by the pointer should be of global scope.
*/
uint32_t BlockCount; /**< Number of blocks present in the mass storage device */
uint32_t BlockSize; /**< Block size in number of bytes */
uint32_t MemorySize; /**< Memory size in number of bytes */
/** Pointer to the interface descriptor within the descriptor
* array (\em high_speed_desc) passed to Init() through \ref USB_CORE_DESCS_T
* structure. The stack assumes both HS and FS use same BULK endpoints.
*/
uint8_t* intf_desc;
/* user defined functions */
/**
* MSC Write callback function.
*
* This function is provided by the application software. This function gets called
* when host sends a write command.
*
* \param[in] offset Destination start address.
* \param[in, out] src Pointer to a pointer to the source of data. Pointer-to-pointer
* is used to implement zero-copy buffers. See \ref USBD_ZeroCopy
* for more details on zero-copy concept.
* \param[in] length Number of bytes to be written.
* \return Nothing.
*
*/
void (*MSC_Write)( uint32_t offset, uint8_t** src, uint32_t length);
/**
* MSC Read callback function.
*
* This function is provided by the application software. This function gets called
* when host sends a read command.
*
* \param[in] offset Source start address.
* \param[in, out] dst Pointer to a pointer to the source of data. The MSC function drivers
* implemented in stack are written with zero-copy model. Meaning the stack doesn't make an
* extra copy of buffer before writing/reading data from USB hardware FIFO. Hence the
* parameter is pointer to a pointer containing address buffer (<em>uint8_t** dst</em>).
* So that the user application can update the buffer pointer instead of copying data to
* address pointed by the parameter. /note The updated buffer address should be accessable
* by USB DMA master. If user doesn't want to use zero-copy model, then the user should copy
* data to the address pointed by the passed buffer pointer parameter and shouldn't change
* the address value. See \ref USBD_ZeroCopy for more details on zero-copy concept.
* \param[in] length Number of bytes to be read.
* \return Nothing.
*
*/
void (*MSC_Read)( uint32_t offset, uint8_t** dst, uint32_t length);
/**
* MSC Verify callback function.
*
* This function is provided by the application software. This function gets called
* when host sends a verify command. The callback function should compare the buffer
* with the destination memory at the requested offset and
*
* \param[in] offset Destination start address.
* \param[in] buf Buffer containing the data sent by the host.
* \param[in] length Number of bytes to verify.
* \return Returns \ref ErrorCode_t type to indicate success or error condition.
* \retval LPC_OK If data in the buffer matches the data at destination
* \retval ERR_FAILED Atleast one byte is different.
*
*/
ErrorCode_t (*MSC_Verify)( uint32_t offset, uint8_t buf[], uint32_t length);
/**
* Optional callback function to optimize MSC_Write buffer transfer.
*
* This function is provided by the application software. This function gets called
* when host sends SCSI_WRITE10/SCSI_WRITE12 command. The callback function should
* update the \em buff_adr pointer so that the stack transfers the data directly
* to the target buffer. /note The updated buffer address should be accessable
* by USB DMA master. If user doesn't want to use zero-copy model, then the user
* should not update the buffer pointer. See \ref USBD_ZeroCopy for more details
* on zero-copy concept.
*
* \param[in] offset Destination start address.
* \param[in,out] buf Buffer containing the data sent by the host.
* \param[in] length Number of bytes to write.
* \return Nothing.
*
*/
void (*MSC_GetWriteBuf)( uint32_t offset, uint8_t** buff_adr, uint32_t length);
/**
* Optional user overridable function to replace the default MSC class handler.
*
* The application software could override the default EP0 class handler with their
* own by providing the handler function address as this data member of the parameter
* structure. Application which like the default handler should set this data member
* to zero before calling the USBD_MSC_API::Init().
* \n
* \note
*
* \param[in] hUsb Handle to the USB device stack.
* \param[in] data Pointer to the data which will be passed when callback function is called by the stack.
* \param[in] event Type of endpoint event. See \ref USBD_EVENT_T for more details.
* \return The call back should returns \ref ErrorCode_t type to indicate success or error condition.
* \retval LPC_OK On success.
* \retval ERR_USBD_UNHANDLED Event is not handled hence pass the event to next in line.
* \retval ERR_USBD_xxx For other error conditions.
*
*/
ErrorCode_t (*MSC_Ep0_Hdlr) (USBD_HANDLE_T hUsb, void* data, uint32_t event);
} USBD_MSC_INIT_PARAM_T;
/** \brief MSC class API functions structure.
* \ingroup USBD_MSC
*
* This module exposes functions which interact directly with USB device controller hardware.
*
*/
typedef struct USBD_MSC_API
{
/** \fn uint32_t GetMemSize(USBD_MSC_INIT_PARAM_T* param)
* Function to determine the memory required by the MSC function driver module.
*
* This function is called by application layer before calling pUsbApi->msc->Init(), to allocate memory used
* by MSC function driver module. The application should allocate the memory which is accessible by USB
* controller/DMA controller.
* \note Some memory areas are not accessible by all bus masters.
*
* \param[in] param Structure containing MSC function driver module initialization parameters.
* \return Returns the required memory size in bytes.
*/
uint32_t (*GetMemSize)(USBD_MSC_INIT_PARAM_T* param);
/** \fn ErrorCode_t init(USBD_HANDLE_T hUsb, USBD_MSC_INIT_PARAM_T* param)
* Function to initialize MSC function driver module.
*
* This fuction is called by application layer to initialize MSC function driver module.
*
* \param[in] hUsb Handle to the USB device stack.
* \param[in, out] param Structure containing MSC function driver module initialization parameters.
* \return Returns \ref ErrorCode_t type to indicate success or error condition.
* \retval LPC_OK On success
* \retval ERR_USBD_BAD_MEM_BUF Memory buffer passed is not 4-byte
* aligned or smaller than required.
* \retval ERR_API_INVALID_PARAM2 Either MSC_Write() or MSC_Read() or
* MSC_Verify() callbacks are not defined.
* \retval ERR_USBD_BAD_INTF_DESC Wrong interface descriptor is passed.
* \retval ERR_USBD_BAD_EP_DESC Wrong endpoint descriptor is passed.
*/
ErrorCode_t (*init)(USBD_HANDLE_T hUsb, USBD_MSC_INIT_PARAM_T* param);
} USBD_MSC_API_T;
/*-----------------------------------------------------------------------------
* Private functions & structures prototypes
*-----------------------------------------------------------------------------*/
/** @cond ADVANCED_API */
typedef struct _MSC_CTRL_T
{
/* If it's a USB HS, the max packet is 512, if it's USB FS,
the max packet is 64. Use 512 for both HS and FS. */
/*ALIGNED(4)*/ uint8_t BulkBuf[USB_HS_MAX_BULK_PACKET]; /* Bulk In/Out Buffer */
/*ALIGNED(4)*/MSC_CBW CBW; /* Command Block Wrapper */
/*ALIGNED(4)*/MSC_CSW CSW; /* Command Status Wrapper */
USB_CORE_CTRL_T* pUsbCtrl;
uint32_t Offset; /* R/W Offset */
uint32_t Length; /* R/W Length */
uint32_t BulkLen; /* Bulk In/Out Length */
uint8_t* rx_buf;
uint8_t BulkStage; /* Bulk Stage */
uint8_t if_num; /* interface number */
uint8_t epin_num; /* BULK IN endpoint number */
uint8_t epout_num; /* BULK OUT endpoint number */
uint32_t MemOK; /* Memory OK */
uint8_t* InquiryStr;
uint32_t BlockCount;
uint32_t BlockSize;
uint32_t MemorySize;
/* user defined functions */
void (*MSC_Write)( uint32_t offset, uint8_t** src, uint32_t length);
void (*MSC_Read)( uint32_t offset, uint8_t** dst, uint32_t length);
ErrorCode_t (*MSC_Verify)( uint32_t offset, uint8_t src[], uint32_t length);
/* optional call back for MSC_Write optimization */
void (*MSC_GetWriteBuf)( uint32_t offset, uint8_t** buff_adr, uint32_t length);
}USB_MSC_CTRL_T;
/** @cond DIRECT_API */
extern uint32_t mwMSC_GetMemSize(USBD_MSC_INIT_PARAM_T* param);
extern ErrorCode_t mwMSC_init(USBD_HANDLE_T hUsb, USBD_MSC_INIT_PARAM_T* param);
/** @endcond */
/** @endcond */
#endif /* __MSCUSER_H__ */
|
