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