SAMV71 Xplained Ultra Software Package 1.4

uhi_msc.h

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