SAMV71 Xplained Ultra Software Package 1.4

uhi_msc_mem.h

Go to the documentation of this file.
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_
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Defines