[freertos] /

/*\r
 * @brief Definition of functions exported by ROM based MSC function driver\r
 *\r
 * @note\r
 * Copyright(C) NXP Semiconductors, 2012\r
  * All rights reserved.\r
 *\r
 * @par\r
 * Software that is described herein is for illustrative purposes only\r
 * which provides customers with programming information regarding the\r
 * LPC products.  This software is supplied "AS IS" without any warranties of\r
 * any kind, and NXP Semiconductors and its licensor disclaim any and\r
 * all warranties, express or implied, including all implied warranties of\r
 * merchantability, fitness for a particular purpose and non-infringement of\r
 * intellectual property rights.  NXP Semiconductors assumes no responsibility\r
 * or liability for the use of the software, conveys no license or rights under any\r
 * patent, copyright, mask work right, or any other intellectual property rights in\r
 * or to any products. NXP Semiconductors reserves the right to make changes\r
 * in the software without notification. NXP Semiconductors also makes no\r
 * representation or warranty that such application will be suitable for the\r
 * specified use without further testing or modification.\r
 *\r
 * @par\r
 * Permission to use, copy, modify, and distribute this software and its\r
 * documentation is hereby granted, under NXP Semiconductors' and its\r
 * licensor's relevant copyrights in the software, without fee, provided that it\r
 * is used in conjunction with NXP Semiconductors microcontrollers.  This\r
 * copyright, permission, and disclaimer notice must appear in all copies of\r
 * this code.\r
 */\r
\r
#include "error.h"\r
#include "usbd.h"\r
#include "usbd_msc.h"\r
#include "usbd_core.h"\r
\r
#ifndef __MSCUSER_H__\r
#define __MSCUSER_H__\r
\r
\r
/** @ingroup Group_USBD_Class\r
 *  @defgroup USBD_MSC Mass Storage Class (MSC) Function Driver\r
 *  @section Sec_MSCModDescription Module Description\r
 *  MSC Class Function Driver module. This module contains an internal implementation of the USB MSC Class.\r
 *  User applications can use this class driver instead of implementing the MSC class manually\r
 *  via the low-level USBD_HW and USBD_Core APIs.\r
 *\r
 *  This module is designed to simplify the user code by exposing only the required interface needed to interface with\r
 *  Devices using the USB MSC Class.\r
 */\r
\r
/** @brief Mass Storage class function driver initilization parameter data structure.\r
 *  @ingroup USBD_MSC\r
 *\r
 *  @details  This data structure is used to pass initialization parameters to the\r
 *  Mass Storage class function driver's init function.\r
 *\r
 */\r
typedef struct USBD_MSC_INIT_PARAM\r
{\r
  /* memory allocation params */\r
  uint32_t mem_base;  /**< Base memory location from where the stack can allocate\r
                      data and buffers. @note The memory address set in this field\r
                      should be accessible by USB DMA controller. Also this value\r
                      should be aligned on 4 byte boundary.\r
                      */\r
  uint32_t mem_size;  /**< The size of memory buffer which stack can use.\r
                      @note The \em mem_size should be greater than the size\r
                      returned by USBD_MSC_API::GetMemSize() routine.*/\r
  /* mass storage paramas */\r
  uint8_t*  InquiryStr; /**< Pointer to the 28 character string. This string is\r
                        sent in response to the SCSI Inquiry command. @note The data\r
                        pointed by the pointer should be of global scope.\r
                        */\r
  uint32_t  BlockCount; /**< Number of blocks present in the mass storage device */\r
  uint32_t  BlockSize; /**< Block size in number of bytes */\r
  uint32_t  MemorySize; /**< Memory size in number of bytes */\r
  /** Pointer to the interface descriptor within the descriptor\r
  * array (\em high_speed_desc) passed to Init() through @ref USB_CORE_DESCS_T\r
  * structure. The stack assumes both HS and FS use same BULK endpoints.\r
  */\r
  uint8_t* intf_desc;\r
  /* user defined functions */\r
\r
 /**\r
  *  MSC Write callback function.\r
  *\r
  *  This function is provided by the application software. This function gets called\r
  *  when host sends a write command.\r
  *\r
  *  @param offset Destination start address.\r
  *  @param src  Pointer to a pointer to the source of data. Pointer-to-pointer\r
  *                       is used to implement zero-copy buffers.\r
  *  @param length  Number of bytes to be written.\r
  *  @return Nothing.\r
  *\r
  */\r
  void (*MSC_Write)( uint32_t offset, uint8_t** src, uint32_t length);\r
 /**\r
  *  MSC Read callback function.\r
  *\r
  *  This function is provided by the application software. This function gets called\r
  *  when host sends a read command.\r
  *\r
  *  @param offset Source start address.\r
  *  @param dst  Pointer to a pointer to the source of data. The MSC function drivers\r
  *         implemented in stack are written with zero-copy model. Meaning the stack doesn't make an\r
  *          extra copy of buffer before writing/reading data from USB hardware FIFO. Hence the\r
  *          parameter is pointer to a pointer containing address buffer (<em>uint8_t** dst</em>).\r
  *          So that the user application can update the buffer pointer instead of copying data to\r
  *          address pointed by the parameter. /note The updated buffer address should be accessable\r
  *          by USB DMA master. If user doesn't want to use zero-copy model, then the user should copy\r
  *          data to the address pointed by the passed buffer pointer parameter and shouldn't change\r
  *          the address value.\r
  *  @param length  Number of bytes to be read.\r
  *  @return Nothing.\r
  *\r
  */\r
  void (*MSC_Read)( uint32_t offset, uint8_t** dst, uint32_t length);\r
 /**\r
  *  MSC Verify callback function.\r
  *\r
  *  This function is provided by the application software. This function gets called\r
  *  when host sends a verify command. The callback function should compare the buffer\r
  *  with the destination memory at the requested offset and\r
  *\r
  *  @param offset Destination start address.\r
  *  @param buf  Buffer containing the data sent by the host.\r
  *  @param length  Number of bytes to verify.\r
  *  @return Returns @ref ErrorCode_t type to indicate success or error condition.\r
  *          @retval LPC_OK If data in the buffer matches the data at destination\r
  *          @retval ERR_FAILED  Atleast one byte is different.\r
  *\r
  */\r
  ErrorCode_t (*MSC_Verify)( uint32_t offset, uint8_t buf[], uint32_t length);\r
  /**\r
  *  Optional callback function to optimize MSC_Write buffer transfer.\r
  *\r
  *  This function is provided by the application software. This function gets called\r
  *  when host sends SCSI_WRITE10/SCSI_WRITE12 command. The callback function should\r
  *  update the \em buff_adr pointer so that the stack transfers the data directly\r
  *  to the target buffer. /note The updated buffer address should be accessable\r
  *  by USB DMA master. If user doesn't want to use zero-copy model, then the user\r
  *  should not update the buffer pointer.\r
  *\r
  *  @param offset Destination start address.\r
  *  \param[in,out] buf  Buffer containing the data sent by the host.\r
  *  @param length  Number of bytes to write.\r
  *  @return Nothing.\r
  *\r
  */\r
  void (*MSC_GetWriteBuf)( uint32_t offset, uint8_t** buff_adr, uint32_t length);\r
\r
  /**\r
  *  Optional user overridable function to replace the default MSC class handler.\r
  *\r
  *  The application software could override the default EP0 class handler with their\r
  *  own by providing the handler function address as this data member of the parameter\r
  *  structure. Application which like the default handler should set this data member\r
  *  to zero before calling the USBD_MSC_API::Init().\r
  *  \n\r
  *  @note\r
  *\r
  *  @param hUsb Handle to the USB device stack.\r
  *  @param data Pointer to the data which will be passed when callback function is called by the stack.\r
  *  @param event  Type of endpoint event. See @ref USBD_EVENT_T for more details.\r
  *  @return The call back should returns @ref ErrorCode_t type to indicate success or error condition.\r
  *          @retval LPC_OK On success.\r
  *          @retval ERR_USBD_UNHANDLED  Event is not handled hence pass the event to next in line.\r
  *          @retval ERR_USBD_xxx  For other error conditions.\r
  *\r
  */\r
  ErrorCode_t (*MSC_Ep0_Hdlr) (USBD_HANDLE_T hUsb, void* data, uint32_t event);\r
\r
} USBD_MSC_INIT_PARAM_T;\r
\r
/** @brief MSC class API functions structure.\r
 *  @ingroup USBD_MSC\r
 *\r
 *  This module exposes functions which interact directly with USB device controller hardware.\r
 *\r
 */\r
typedef struct USBD_MSC_API\r
{\r
  /** @fn uint32_t GetMemSize(USBD_MSC_INIT_PARAM_T* param)\r
   *  Function to determine the memory required by the MSC function driver module.\r
   *\r
   *  This function is called by application layer before calling pUsbApi->msc->Init(), to allocate memory used\r
   *  by MSC function driver module. The application should allocate the memory which is accessible by USB\r
   *  controller/DMA controller.\r
   *  @note Some memory areas are not accessible by all bus masters.\r
   *\r
   *  @param param Structure containing HID function driver module initialization parameters.\r
   *  @return Returns the required memory size in bytes.\r
   */\r
  uint32_t (*GetMemSize)(USBD_MSC_INIT_PARAM_T* param);\r
\r
  /** @fn ErrorCode_t init(USBD_HANDLE_T hUsb, USBD_MSC_INIT_PARAM_T* param)\r
   *  Function to initialize MSC function driver module.\r
   *\r
   *  This fuction is called by application layer to initialize MSC function driver module.\r
   *\r
   *  @param hUsb Handle to the USB device stack.\r
   *  @param param Structure containing HID function driver module initialization parameters.\r
   *  @return Returns @ref ErrorCode_t type to indicate success or error condition.\r
   *          @retval LPC_OK On success\r
   *          @retval ERR_USBD_BAD_MEM_BUF  Memory buffer passed is not 4-byte\r
   *              aligned or smaller than required.\r
   *          @retval ERR_API_INVALID_PARAM2 Either MSC_Write() or MSC_Read() or\r
   *              MSC_Verify() callbacks are not defined.\r
   *          @retval ERR_USBD_BAD_INTF_DESC  Wrong interface descriptor is passed.\r
   *          @retval ERR_USBD_BAD_EP_DESC  Wrong endpoint descriptor is passed.\r
   */\r
  ErrorCode_t (*init)(USBD_HANDLE_T hUsb, USBD_MSC_INIT_PARAM_T* param);\r
\r
} USBD_MSC_API_T;\r
\r
/*-----------------------------------------------------------------------------\r
 *  Private functions & structures prototypes\r
 *-----------------------------------------------------------------------------*/\r
/** @cond  ADVANCED_API */\r
\r
typedef struct _MSC_CTRL_T\r
{\r
  /* If it's a USB HS, the max packet is 512, if it's USB FS,\r
  the max packet is 64. Use 512 for both HS and FS. */\r
  /*ALIGNED(4)*/ uint8_t  BulkBuf[512]; /* Bulk In/Out Buffer */\r
  /*ALIGNED(4)*/MSC_CBW CBW;                   /* Command Block Wrapper */\r
  /*ALIGNED(4)*/MSC_CSW CSW;                   /* Command Status Wrapper */\r
\r
  USB_CORE_CTRL_T*  pUsbCtrl;\r
\r
  uint32_t Offset;                  /* R/W Offset */\r
  uint32_t Length;                  /* R/W Length */\r
  uint32_t BulkLen;                 /* Bulk In/Out Length */\r
  uint8_t* rx_buf;\r
\r
  uint8_t BulkStage;               /* Bulk Stage */\r
  uint8_t if_num;                  /* interface number */\r
  uint8_t epin_num;                /* BULK IN endpoint number */\r
  uint8_t epout_num;               /* BULK OUT endpoint number */\r
  uint32_t MemOK;                  /* Memory OK */\r
\r
  uint8_t*  InquiryStr;\r
  uint32_t  BlockCount;\r
  uint32_t  BlockSize;\r
  uint32_t  MemorySize;\r
  /* user defined functions */\r
  void (*MSC_Write)( uint32_t offset, uint8_t** src, uint32_t length);\r
  void (*MSC_Read)( uint32_t offset, uint8_t** dst, uint32_t length);\r
  ErrorCode_t (*MSC_Verify)( uint32_t offset, uint8_t src[], uint32_t length);\r
  /* optional call back for MSC_Write optimization */\r
  void (*MSC_GetWriteBuf)( uint32_t offset, uint8_t** buff_adr, uint32_t length);\r
\r
\r
}USB_MSC_CTRL_T;\r
\r
\r
/** @endcond */\r
\r
\r
#endif  /* __MSCUSER_H__ */\r