packages/ti/board/diag/usb_device/src/usbdmscglue.h

   1 /******************************************************************************
   2  * Copyright (c) 2017-2018 Texas Instruments Incorporated - http://www.ti.com
   3  *
   4  *  Redistribution and use in source and binary forms, with or without
   5  *  modification, are permitted provided that the following conditions
   6  *  are met:
   7  *
   8  *    Redistributions of source code must retain the above copyright
   9  *    notice, this list of conditions and the following disclaimer.
  10  *
  11  *    Redistributions in binary form must reproduce the above copyright
  12  *    notice, this list of conditions and the following disclaimer in the
  13  *    documentation and/or other materials provided with the
  14  *    distribution.
  15  *
  16  *    Neither the name of Texas Instruments Incorporated nor the names of
  17  *    its contributors may be used to endorse or promote products derived
  18  *    from this software without specific prior written permission.
  19  *
  20  *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  21  *  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  22  *  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  23  *  A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  24  *  OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  25  *  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  26  *  LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  27  *  DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  28  *  THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  29  *  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  30  *  OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  31  *
  32  *****************************************************************************/
  33
  34 /**
  35 *  \file  usbdmscglue.h
  36 *
  37 *  \brief   Prototypes for functions supplied for use by the mass storage
  38 *           class device.
  39 */
  40
  41 #ifndef USBDMSCGLUE_H_
  42 #define USBDMSCGLUE_H_
  43
  44
  45 /* ========================================================================== */
  46 /*                             Include Files                                  */
  47 /* ========================================================================== */
  48
  49 #include "types.h"
  50 #include "usblib.h"
  51 #include "usbdevice.h"
  52 #include "usbdmsc.h"
  53 #include "usb_msc_structs.h"
  54 #include "ramdiskutils.h"
  55 #include "usb-ids.h"
  56
  57 #ifdef __cplusplus
  58 extern "C" {
  59 #endif
  60
  61 /* ========================================================================== */
  62 /*                          Macros and Typedefs                               */
  63 /* ========================================================================== */
  64 #ifdef DEBUG
  65 #define ASSERT(expr) {                                      \
  66                          if(!(expr))                        \
  67                          {                                  \
  68                              __error__(__FILE__, __LINE__); \
  69                          }                                  \
  70                      }
  71 #else
  72 #define ASSERT(expr)
  73 #endif
  74
  75 #define SDCARD_PRESENT          0x00000001
  76 #define SDCARD_IN_USE           0x00000002
  77
  78 #define USBDMSC_IDLE            0x00000000
  79 #define USBDMSC_NOT_PRESENT     0x00000001
  80
  81
  82 /* ========================================================================== */
  83 /*                         Structures and Enums                               */
  84 /* ========================================================================== */
  85
  86 /* ========================================================================== */
  87 /*                         Global Variables Declarations                      */
  88 /* ========================================================================== */
  89
  90
  91 /* ========================================================================== */
  92 /*                          Function Declarations                             */
  93 /* ========================================================================== */
  94
  95 /**
  96  *  \brief This function opens the drive number and prepares it for use by the Mass
  97  *         storage class device.
  98  *
  99  *  \param ulDrive is the driver number to open.
 100  *
 101  * This function is used to initialize and open the physical drive number
 102  * associated with the parameter /e ulDrive.  The function will return zero if
 103  * the drive could not be opened for some reason.  In the case of removable
 104  * device like an SD card this function should return zero if the SD card is
 105  * not present.
 106  *
 107  * \retval Returns a pointer to data that should be passed to other APIs or it
 108  *         will return 0 if no drive was found.
 109  */
 110 extern void * USBDMSCStorageOpen(uint32_t ulDrive);
 111
 112 /**
 113  * \brief This function closes the drive number in use by the mass storage class device.
 114  *
 115  * \param pvDrive is the pointer that was returned from a call to
 116  *        USBDMSCStorageOpen().
 117  *
 118  * This function is used to close the physical drive number associated with the
 119  * parameter /e pvDrive.  This function will return 0 if the drive was closed
 120  * successfully and any other value will indicate a failure.
 121  *
 122  * \retval Returns 0 if the drive was successfully closed or non-zero for a
 123  * failure.
 124  */extern void USBDMSCStorageClose(void * pvDrive);
 125
 126 /**
 127  *  \brief This function will read a block from a device opened by the
 128  *         USBDMSCStorageOpen() call.
 129  *
 130  *  \param pvDrive is the pointer that was returned from a call to
 131  *         USBDMSCStorageOpen().
 132  *  \param pucData is the buffer that data will be written into.
 133  *  \param ulNumBlocks is the number of blocks to read.
 134  *
 135  * This function is use to read blocks from a physical device and return them
 136  * in the /e pucData buffer.  The data area pointed to by /e pucData should be
 137  * at least /e ulNumBlocks * Block Size bytes to prevent overwriting data.
 138  *
 139  * /retval Returns the number of bytes that were read from the device.
 140  */
 141 extern uint32_t USBDMSCStorageRead(void * pvDrive,
 142                                    uint8_t *pucData,
 143                                    uint32_t ulSector,
 144                                    uint32_t ulNumBlocks);
 145
 146 /**
 147  *  \brief This function will write a block to a device opened by the
 148  *         USBDMSCStorageOpen() call.
 149  *
 150  *  \param pvDrive is the pointer that was returned from a call to
 151  *         USBDMSCStorageOpen().
 152  *  \param pucData is the buffer that data will be used for writing.
 153  *  \param ulNumBlocks is the number of blocks to write.
 154  *
 155  * This function is use to write blocks to a physical device from the buffer
 156  * pointed to by the /e pucData buffer.  If the number of blocks is greater than
 157  * one then the block address will increment and write to the next block until
 158  * /e ulNumBlocks * Block Size bytes have been written.
 159  *
 160  * /return Returns the number of bytes that were written to the device.
 161  */
 162 extern uint32_t USBDMSCStorageWrite(void * pvDrive,
 163                                     uint8_t *pucData,
 164                                     uint32_t ulSector,
 165                                     uint32_t ulNumBlocks);
 166
 167
 168 /**
 169  * \brief This function will return the number of blocks present on a device.
 170  *
 171  *  \param pvDrive is the pointer that was returned from a call to
 172  *         USBDMSCStorageOpen().
 173  *
 174  * This function is used to return the total number of blocks on a physical
 175  * device based on the /e pvDrive parameter.
 176  *
 177  * \retval return Returns the number of blocks that are present in a device.
 178  */
 179 uint32_t USBDMSCStorageNumBlocks(void * pvDrive);
 180
 181
 182 #ifdef __cplusplus
 183 }
 184 #endif
 185
 186 #endif /* #ifndef USBDMSCGLUE_H */