SAMV71 Xplained Ultra Software Package 1.5

uhi_msc.h

Go to the documentation of this file.
00001 /* ---------------------------------------------------------------------------- */
00002 /*                  Atmel Microcontroller Software Support                      */
00003 /*                       SAM Software Package License                           */
00004 /* ---------------------------------------------------------------------------- */
00005 /* Copyright (c) 2015, Atmel Corporation                                        */
00006 /*                                                                              */
00007 /* All rights reserved.                                                         */
00008 /*                                                                              */
00009 /* Redistribution and use in source and binary forms, with or without           */
00010 /* modification, are permitted provided that the following condition is met:    */
00011 /*                                                                              */
00012 /* - Redistributions of source code must retain the above copyright notice,     */
00013 /* this list of conditions and the disclaimer below.                            */
00014 /*                                                                              */
00015 /* Atmel's name may not be used to endorse or promote products derived from     */
00016 /* this software without specific prior written permission.                     */
00017 /*                                                                              */
00018 /* DISCLAIMER:  THIS SOFTWARE IS PROVIDED BY ATMEL "AS IS" AND ANY EXPRESS OR   */
00019 /* IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF */
00020 /* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT ARE   */
00021 /* DISCLAIMED. IN NO EVENT SHALL ATMEL BE LIABLE FOR ANY DIRECT, INDIRECT,      */
00022 /* INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT */
00023 /* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA,  */
00024 /* OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF    */
00025 /* LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING         */
00026 /* NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, */
00027 /* EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.                           */
00028 /* ---------------------------------------------------------------------------- */
00029 
00030 /**
00031  * \file
00032  *
00033  * \brief USB host driver for Mass Storage Class interface.
00034  *
00035  */
00036 /*
00037  * Support and FAQ: visit <a href="http://www.atmel.com/design-support/">Atmel Support</a>
00038  */
00039 
00040 #ifndef _UHI_MSC_H_
00041 #define _UHI_MSC_H_
00042 
00043 #include "conf_usb_host.h"
00044 #include "MSD.h"
00045 #include "SBC.h"
00046 #include "MSDescriptors.h"
00047 #include "USBH.h"
00048 #include "uhi.h"
00049 
00050 #ifdef __cplusplus
00051 extern "C" {
00052 #endif
00053 
00054 /**
00055  * \ingroup uhi_msc_group
00056  * \defgroup uhi_msc_group_uhc Interface with USB Host Core (UHC)
00057  *
00058  * Define and functions required by UHC.
00059  *
00060  * @{
00061  */
00062 
00063 //! Global define which contains standard UHI API for UHC.
00064 //! It must be added in USB_HOST_UHI define from conf_usb_host.h file.
00065 #define UHI_MSC { \
00066         .install = uhi_msc_install, \
00067                    .enable = uhi_msc_enable, \
00068                              .uninstall = uhi_msc_uninstall, \
00069                                           .sof_notify = NULL, \
00070     }
00071 
00072 /**
00073  * \name Functions required by UHC
00074  * @{
00075  */
00076 USBH_enum_status_t uhi_msc_install(USBH_device_t *dev);
00077 void uhi_msc_enable(USBH_device_t *dev);
00078 void uhi_msc_uninstall(USBH_device_t *dev);
00079 //@}
00080 
00081 //@}
00082 
00083 /**
00084  * \ingroup uhi_group
00085  * \defgroup uhi_msc_group UHI for Mass Storage Class
00086  *
00087  * Common APIs used by high level application to use this USB host class.
00088  *
00089  * @{
00090  */
00091 
00092 /**
00093  * \name Struct to access at Logical Unit Numbers (LUNs)
00094  * @{
00095  */
00096 
00097 //! Status of LUN
00098 typedef enum {
00099     LUN_GOOD       = 0,  //!< Success, memory ready.
00100     LUN_FAIL       = 1,  //!< An error occurred.
00101     LUN_NOT_PRESENT = 2, //!< Memory unplugged.
00102     LUN_BUSY       = 3,  //!< Memory not initialized or changed.
00103 } lun_status_t;
00104 
00105 //! Callback type used by uhi_msc_scsi() functions
00106 typedef void (*uhi_msc_scsi_callback_t) (bool);
00107 
00108 //! LUN structure information
00109 typedef struct {
00110     SBCReadCapacity10Data capacity;
00111     bool b_write_protected;
00112     lun_status_t status;
00113 } uhi_msc_lun_t;
00114 
00115 //@}
00116 
00117 /**
00118  * \brief Tests if the interface UHI Mass Storage is available
00119  * The UHI Mass Storage can be busy during the enumeration of a USB Device MSC.
00120  *
00121  * \return true, if UHI Mass Storage is available
00122  */
00123 bool uhi_msc_is_available(void);
00124 
00125 /**
00126  * \brief Gives the number of LUN available
00127  * Note: A LUN can be available, but with a status LUN_NOT_PRESENT.
00128  * It is the case for a card reader without card.
00129  *
00130  * \return Number of LUN available
00131  */
00132 uint8_t uhi_msc_get_lun(void);
00133 
00134 /**
00135  * \name Functions to access at LUNs
00136  * @{
00137  */
00138 
00139 /**
00140  * \brief Gives information about a LUN
00141  *
00142  * \param lun  LUN number
00143  *
00144  * \return Pointer on the LUN information structure.
00145  */
00146 uhi_msc_lun_t *uhi_msc_get_lun_desc(uint8_t lun);
00147 
00148 /**
00149  * \brief Checks and update the status of the LUN
00150  *
00151  * \param lun       LUN number
00152  * \param callback  Callback to call at the end of scsi command
00153  *
00154  * \return true, if the scsi command has been accepted
00155  */
00156 bool uhi_msc_scsi_test_unit_ready(uint8_t lun,
00157                                   uhi_msc_scsi_callback_t callback);
00158 
00159 /**
00160  * \brief Reads a LUN data section to RAM buffer
00161  * Note: The sector size used to define the data section
00162  * is the sector size returned by LUN in \capacity field.
00163  *
00164  * \param lun       LUN number
00165  * \param addr      Sector address to read
00166  * \param ram       RAM address used to store the data
00167  * \param nb_sector Number of sector to read
00168  * \param callback  Callback to call at the end of scsi command
00169  *
00170  * \return true, if the scsi command has been accepted
00171  */
00172 bool uhi_msc_scsi_read_10(uint8_t lun, uint32_t addr, uint8_t *ram,
00173                           uint8_t nb_sector, uhi_msc_scsi_callback_t callback);
00174 
00175 /**
00176  * \brief Writes a RAM buffer in a LUN data section
00177  * Note: The sector size used to define the data section
00178  * is the sector size returned by LUN in \capacity field.
00179  *
00180  * \param lun       LUN number
00181  * \param addr      Sector address to write
00182  * \param ram       RAM address of data to write
00183  * \param nb_sector Number of sector to write
00184  * \param callback  Callback to call at the end of scsi command
00185  *
00186  * \return true, if the scsi command has been accepted
00187  */
00188 bool uhi_msc_scsi_write_10(uint8_t lun, uint32_t addr, const uint8_t *ram,
00189                            uint8_t nb_sector, uhi_msc_scsi_callback_t callback);
00190 //@}
00191 
00192 //@}
00193 
00194 #ifdef __cplusplus
00195 }
00196 #endif
00197 #endif // _UHI_MSC_H_
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Defines