SAMV71 Xplained Ultra Software Package 1.5

uhi_msc_mem.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 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_
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Defines