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 Mass Storage interface for control access module. 00034 */ 00035 /* 00036 * Support and FAQ: visit <a href="http://www.atmel.com/design-support/">Atmel Support</a> 00037 */ 00038 00039 #ifndef _UHI_MSC_MEM_H_ 00040 #define _UHI_MSC_MEM_H_ 00041 00042 #include "ctrl_access.h" 00043 00044 #ifdef __cplusplus 00045 extern "C" { 00046 #endif 00047 00048 /** 00049 * \ingroup uhi_msc_group 00050 * \defgroup uhi_msc_mem_group USB host Mass Storage interface for control access module 00051 * Layer added on UHI MSC interface to allow the usage of control access module. 00052 * The control access module provides a common access at all memories and 00053 * it is used by the File Systems available in ASF. 00054 * 00055 * See \ref uhi_msc_mem_quickstart. 00056 * @{ 00057 */ 00058 00059 /** 00060 * \brief Gives the number of available LUN 00061 * 00062 * \note A LUN can be available, but with a status not present. 00063 * It is the case for a card reader without card. 00064 * 00065 * \return Number of available LUN 00066 */ 00067 uint8_t uhi_msc_mem_get_lun(void); 00068 00069 /** 00070 * \brief Checks and update the status of the LUN 00071 * 00072 * \param lun LUN number 00073 * 00074 * \return Status of the LUN 00075 */ 00076 Ctrl_status uhi_msc_mem_test_unit_ready(uint8_t lun); 00077 00078 /** 00079 * \brief Returns the capacity of the LUN 00080 * 00081 * \param lun LUN number 00082 * \param u32_nb_sector Pointer to store the last sector address possible on this LUN 00083 * 00084 * \return Status of the LUN 00085 */ 00086 Ctrl_status uhi_msc_mem_read_capacity(uint8_t lun, uint32_t *u32_nb_sector); 00087 00088 /** 00089 * \brief Returns the sector size of the LUN 00090 * 00091 * \param lun LUN number 00092 * 00093 * \return Sector size (unit 512B) 00094 */ 00095 uint8_t uhi_msc_mem_read_sector_size(uint8_t lun); 00096 00097 /** 00098 * \brief Checks if the LUN is write protected 00099 * 00100 * \param lun LUN number 00101 * 00102 * \return true, if write protected 00103 */ 00104 bool uhi_msc_mem_wr_protect(uint8_t lun); 00105 00106 /** 00107 * \brief Checks if the device is removed 00108 * 00109 * \return Always true for USB Device 00110 */ 00111 bool uhi_msc_mem_removal(void); 00112 00113 /** 00114 * \brief Reads 512 bytes from the current LUN 00115 * 00116 * The LUN is selected by uhi_msc_mem_test_unit_ready() 00117 * or uhi_msc_mem_read_capacity() function. 00118 * 00119 * \param addr Disk address (unit 512B) 00120 * \param ram Pointer to store the data 00121 * 00122 * \return Status of the LUN 00123 */ 00124 Ctrl_status uhi_msc_mem_read_10_ram(uint32_t addr, void *ram); 00125 00126 /** 00127 * \brief Writes 512 bytes to the current LUN 00128 * 00129 * The LUN is selected by uhi_msc_mem_test_unit_ready() 00130 * or uhi_msc_mem_read_capacity() function. 00131 * 00132 * \param addr Disk address (unit 512B) 00133 * \param ram Pointer on the data 00134 * 00135 * \return Status of the LUN 00136 */ 00137 Ctrl_status uhi_msc_mem_write_10_ram(uint32_t addr, const void *ram); 00138 00139 //@} 00140 00141 /** 00142 * \page uhi_msc_mem_quickstart Quick start guide for USB host mass-storage module (UHI MSC) 00143 * 00144 * This is the quick start guide for the \ref uhi_msc_mem_group 00145 * "USB host mass-storage module (UHI MSC)" with step-by-step instructions on 00146 * how to configure and use the modules in a selection of use cases. 00147 * 00148 * The use cases contain several code fragments. The code fragments in the 00149 * steps for setup can be copied into a custom initialization function, while 00150 * the steps for usage can be copied into, e.g., the main application function. 00151 * 00152 * \section uhi_msc_mem_basic_use_case Basic use case 00153 * In this basic use case, the "USB Host MSC (Single Class support)" module is used. 00154 * 00155 * The "USB Host MSC (Multiple Classes support)" module usage is described 00156 * in \ref uhi_msc_mem_use_cases "Advanced use cases". 00157 * 00158 * This example do a simple physical memory access, but a File System module 00159 * can be added to decode the USB memory file system, see FatFS examples. 00160 * 00161 * \section uhi_msc_mem_basic_use_case_setup Setup steps 00162 * \subsection uhi_msc_mem_basic_use_case_setup_prereq Prerequisites 00163 * \copydetails uhc_basic_use_case_setup_prereq 00164 * \subsection uhi_msc_mem_basic_use_case_setup_code Example code 00165 * \copydetails uhc_basic_use_case_setup_code 00166 * \subsection uhi_msc_mem_basic_use_case_setup_flow Workflow 00167 * \copydetails uhc_basic_use_case_setup_flow 00168 * 00169 * \section uhi_msc_mem_basic_use_case_usage Usage steps 00170 * 00171 * \subsection uhi_msc_mem_basic_use_case_usage_code Example code 00172 * Content of conf_usb_host.h: 00173 * \code 00174 #define USB_HOST_UHI UHI_MSC 00175 #define UHI_MSC_CHANGE(dev, b_plug) my_callback_msc_change(dev, b_plug) 00176 extern bool my_callback_msc_change(uhc_device_t* dev, bool b_plug); 00177 #include "uhi_msc_mem.h" // At the end of conf_usb_host.h file 00178 \endcode 00179 * 00180 * Add to application C-file: 00181 * \code 00182 static bool my_flag_autorize_msc_check = false; 00183 bool my_callback_msc_change(uhc_device_t* dev, bool b_plug) 00184 { 00185 if (b_plug) { 00186 my_flag_autorize_msc_check = true; 00187 } else { 00188 my_flag_autorize_msc_check = false; 00189 } 00190 } 00191 00192 void my_task(void) 00193 { 00194 if (!my_flag_autorize_msc_check) { 00195 return; 00196 } 00197 my_flag_autorize_msc_check = false; 00198 00199 // Check all new USB disks plugged 00200 for (uint8_t lun=0; lun < uhi_msc_mem_get_lun(); lun++) { 00201 // Wait the end of USB disk install 00202 while (CTRL_BUSY == uhi_msc_mem_test_unit_ready(lun)); 00203 if (CTRL_GOOD != uhi_msc_mem_test_unit_ready(lun)) { 00204 // Removal disk not present or fail 00205 continue; 00206 } 00207 // Read capacity 00208 uint32_t max_lba; 00209 uhi_msc_mem_read_capacity(lun, &max_lba); 00210 } 00211 } 00212 \endcode 00213 * 00214 * \subsection uhi_msc_mem_basic_use_case_setup_flow Workflow 00215 * -# Ensure that conf_usb_host.h is available and contains the following configuration 00216 * which is the USB host MSC configuration: 00217 * - \code #define USB_HOST_UHI UHI_MSC \endcode 00218 * \note It defines the list of UHI supported by USB host. 00219 * - \code #define UHI_MSC_CHANGE(dev, b_plug) my_callback_msc_change(dev, b_plug) 00220 extern bool my_callback_msc_change(uhc_device_t* dev, bool b_plug); \endcode 00221 * \note This callback is called when a USB device MSC is plugged or unplugged. 00222 * -# The access of the USB memories is allowed through functions described in \ref uhi_msc_mem_group. 00223 * 00224 * \section uhi_msc_mem_use_cases Advanced use cases 00225 * For more advanced use of the UHI MSC module, see the following use cases: 00226 * - \subpage uhc_use_case_1 00227 * - \subpage uhc_use_case_2 00228 * - \subpage uhc_use_case_3 00229 */ 00230 00231 00232 #ifdef __cplusplus 00233 } 00234 #endif 00235 00236 #endif // _UHI_MSC_MEM_H_