SAMV71 Xplained Ultra Software Package 1.5

ctrl_access.h

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 Abstraction layer for memory interfaces.
00034  *
00035  * This module contains the interfaces:
00036  *   - MEM <-> USB;
00037  *   - MEM <-> RAM;
00038  *   - MEM <-> MEM.
00039  *
00040  * This module may be configured and expanded to support the following features:
00041  *   - write-protected globals;
00042  *   - password-protected data;
00043  *   - specific features;
00044  *   - etc.
00045  *
00046  ******************************************************************************/
00047 /*
00048  * Support and FAQ: visit <a href="http://www.atmel.com/design-support/">Atmel Support</a>
00049  */
00050 
00051 
00052 #ifndef _CTRL_ACCESS_H_
00053 #define _CTRL_ACCESS_H_
00054 
00055 #ifdef __cplusplus
00056 extern "C" {
00057 #endif
00058 
00059 /**
00060  * \defgroup group_common_services_storage_ctrl_access Memory Control Access
00061  *
00062  * Common abstraction layer for memory interfaces. It provides interfaces between:
00063  * Memory and USB, Memory and RAM, Memory and Memory. Common API for XMEGA and UC3.
00064  *
00065  * \{
00066  */
00067 
00068 #include "compiler.h"
00069 #include "conf_access.h"
00070 
00071 #ifndef SECTOR_SIZE
00072 #define SECTOR_SIZE  512
00073 #endif
00074 
00075 //! Status returned by CTRL_ACCESS interfaces.
00076 typedef enum {
00077     CTRL_GOOD       = PASS,     //!< Success, memory ready.
00078     CTRL_FAIL       = FAIL,     //!< An error occurred.
00079     CTRL_NO_PRESENT = FAIL + 1, //!< Memory unplugged.
00080     CTRL_BUSY       = FAIL + 2  //!< Memory not initialized or changed.
00081 } Ctrl_status;
00082 
00083 
00084 // FYI: Each Logical Unit Number (LUN) corresponds to a memory.
00085 
00086 // Check LUN defines.
00087 #ifndef LUN_0
00088 #error LUN_0 must be defined as ENABLE or DISABLE in conf_access.h
00089 #endif
00090 #ifndef LUN_1
00091 #error LUN_1 must be defined as ENABLE or DISABLE in conf_access.h
00092 #endif
00093 #ifndef LUN_2
00094 #error LUN_2 must be defined as ENABLE or DISABLE in conf_access.h
00095 #endif
00096 #ifndef LUN_3
00097 #error LUN_3 must be defined as ENABLE or DISABLE in conf_access.h
00098 #endif
00099 #ifndef LUN_4
00100 #error LUN_4 must be defined as ENABLE or DISABLE in conf_access.h
00101 #endif
00102 #ifndef LUN_5
00103 #error LUN_5 must be defined as ENABLE or DISABLE in conf_access.h
00104 #endif
00105 #ifndef LUN_6
00106 #error LUN_6 must be defined as ENABLE or DISABLE in conf_access.h
00107 #endif
00108 #ifndef LUN_7
00109 #error LUN_7 must be defined as ENABLE or DISABLE in conf_access.h
00110 #endif
00111 #ifndef LUN_USB
00112 #error LUN_USB must be defined as ENABLE or DISABLE in conf_access.h
00113 #endif
00114 
00115 /*! \name LUN IDs
00116  */
00117 //! @{
00118 #define LUN_ID_0        (0)                 //!< First static LUN.
00119 #define LUN_ID_1        (LUN_ID_0 + LUN_0)
00120 #define LUN_ID_2        (LUN_ID_1 + LUN_1)
00121 #define LUN_ID_3        (LUN_ID_2 + LUN_2)
00122 #define LUN_ID_4        (LUN_ID_3 + LUN_3)
00123 #define LUN_ID_5        (LUN_ID_4 + LUN_4)
00124 #define LUN_ID_6        (LUN_ID_5 + LUN_5)
00125 #define LUN_ID_7        (LUN_ID_6 + LUN_6)
00126 #define MAX_LUN         (LUN_ID_7 + LUN_7)  //!< Number of static LUNs.
00127 #define LUN_ID_USB      (MAX_LUN)           //!< First dynamic LUN (USB host mass storage).
00128 //! @}
00129 
00130 
00131 // Include LUN header files.
00132 #if LUN_0 == ENABLE
00133 #include LUN_0_INCLUDE
00134 #endif
00135 #if LUN_1 == ENABLE
00136 #include LUN_1_INCLUDE
00137 #endif
00138 #if LUN_2 == ENABLE
00139 #include LUN_2_INCLUDE
00140 #endif
00141 #if LUN_3 == ENABLE
00142 #include LUN_3_INCLUDE
00143 #endif
00144 #if LUN_4 == ENABLE
00145 #include LUN_4_INCLUDE
00146 #endif
00147 #if LUN_5 == ENABLE
00148 #include LUN_5_INCLUDE
00149 #endif
00150 #if LUN_6 == ENABLE
00151 #include LUN_6_INCLUDE
00152 #endif
00153 #if LUN_7 == ENABLE
00154 #include LUN_7_INCLUDE
00155 #endif
00156 #if LUN_USB == ENABLE
00157 #include LUN_USB_INCLUDE
00158 #endif
00159 
00160 
00161 // Check the configuration of write protection in conf_access.h.
00162 #ifndef GLOBAL_WR_PROTECT
00163 #error GLOBAL_WR_PROTECT must be defined as true or false in conf_access.h
00164 #endif
00165 
00166 
00167 #if GLOBAL_WR_PROTECT == true
00168 
00169 //! Write protect.
00170 extern bool g_wr_protect;
00171 
00172 #endif
00173 
00174 
00175 /*! \name Control Interface
00176  */
00177 //! @{
00178 
00179 #ifdef FREERTOS_USED
00180 
00181 /*! \brief Initializes the LUN access locker.
00182  *
00183  * \return \c true if the locker was successfully initialized, else \c false.
00184  */
00185 extern bool ctrl_access_init(void);
00186 
00187 #endif  // FREERTOS_USED
00188 
00189 /*! \brief Returns the number of LUNs.
00190  *
00191  * \return Number of LUNs in the system.
00192  */
00193 extern uint8_t get_nb_lun(void);
00194 
00195 /*! \brief Returns the current LUN.
00196  *
00197  * \return Current LUN.
00198  *
00199  * \todo Implement.
00200  */
00201 extern uint8_t get_cur_lun(void);
00202 
00203 /*! \brief Tests the memory state and initializes the memory if required.
00204  *
00205  * The TEST UNIT READY SCSI primary command allows an application client to poll
00206  * a LUN until it is ready without having to allocate memory for returned data.
00207  *
00208  * This command may be used to check the media status of LUNs with removable
00209  * media.
00210  *
00211  * \param lun Logical Unit Number.
00212  *
00213  * \return Status.
00214  */
00215 extern Ctrl_status mem_test_unit_ready(uint8_t lun);
00216 
00217 /*! \brief Returns the address of the last valid sector (512 bytes) in the
00218  *         memory.
00219  *
00220  * \param lun           Logical Unit Number.
00221  * \param u32_nb_sector Pointer to the address of the last valid sector.
00222  *
00223  * \return Status.
00224  */
00225 extern Ctrl_status mem_read_capacity(uint8_t lun, uint32_t *u32_nb_sector);
00226 
00227 /*! \brief Returns the size of the physical sector.
00228  *
00229  * \param lun Logical Unit Number.
00230  *
00231  * \return Sector size (unit: 512 bytes).
00232  */
00233 extern uint8_t mem_sector_size(uint8_t lun);
00234 
00235 /*! \brief Unload/load the medium.
00236  *
00237  * \param lun Logical Unit Number.
00238  * \param unload \c true to unload the medium, \c false to load the medium.
00239  *
00240  * \return \c true if unload/load success, else \c false.
00241  */
00242 extern bool mem_unload(uint8_t lun, bool unload);
00243 
00244 /*! \brief Returns the write-protection state of the memory.
00245  *
00246  * \param lun Logical Unit Number.
00247  *
00248  * \return \c true if the memory is write-protected, else \c false.
00249  *
00250  * \note Only used by removable memories with hardware-specific write
00251  *       protection.
00252  */
00253 extern bool mem_wr_protect(uint8_t lun);
00254 
00255 /*! \brief Tells whether the memory is removable.
00256  *
00257  * \param lun Logical Unit Number.
00258  *
00259  * \return \c true if the memory is removable, else \c false.
00260  */
00261 extern bool mem_removal(uint8_t lun);
00262 
00263 /*! \brief Returns a pointer to the LUN name.
00264  *
00265  * \param lun Logical Unit Number.
00266  *
00267  * \return Pointer to the LUN name string.
00268  */
00269 extern const char *mem_name(uint8_t lun);
00270 
00271 //! @}
00272 
00273 
00274 #if ACCESS_USB == true
00275 
00276 /*! \name MEM <-> USB Interface
00277  */
00278 //! @{
00279 
00280 /*! \brief Transfers data from the memory to USB.
00281  *
00282  * \param lun       Logical Unit Number.
00283  * \param addr      Address of first memory sector to read.
00284  * \param nb_sector Number of sectors to transfer.
00285  *
00286  * \return Status.
00287  */
00288 extern Ctrl_status memory_2_usb(uint8_t lun, uint32_t addr, U16 nb_sector);
00289 
00290 /*! \brief Transfers data from USB to the memory.
00291  *
00292  * \param lun       Logical Unit Number.
00293  * \param addr      Address of first memory sector to write.
00294  * \param nb_sector Number of sectors to transfer.
00295  *
00296  * \return Status.
00297  */
00298 extern Ctrl_status usb_2_memory(uint8_t lun, uint32_t addr, U16 nb_sector);
00299 
00300 //! @}
00301 
00302 #endif  // ACCESS_USB == true
00303 
00304 
00305 #if ACCESS_MEM_TO_RAM == true
00306 
00307 /*! \name MEM <-> RAM Interface
00308  */
00309 //! @{
00310 
00311 /*! \brief Copies 1 data sector from the memory to RAM.
00312  *
00313  * \param lun   Logical Unit Number.
00314  * \param addr  Address of first memory sector to read.
00315  * \param ram   Pointer to RAM buffer to write.
00316  *
00317  * \return Status.
00318  */
00319 extern Ctrl_status memory_2_ram(uint8_t lun, uint32_t addr, void *ram);
00320 
00321 /*! \brief Copies 1 data sector from RAM to the memory.
00322  *
00323  * \param lun   Logical Unit Number.
00324  * \param addr  Address of first memory sector to write.
00325  * \param ram   Pointer to RAM buffer to read.
00326  *
00327  * \return Status.
00328  */
00329 extern Ctrl_status ram_2_memory(uint8_t lun, uint32_t addr, const void *ram);
00330 
00331 //! @}
00332 
00333 #endif  // ACCESS_MEM_TO_RAM == true
00334 
00335 
00336 #if ACCESS_STREAM == true
00337 
00338 /*! \name Streaming MEM <-> MEM Interface
00339  */
00340 //! @{
00341 
00342 //! Erroneous streaming data transfer ID.
00343 #define ID_STREAM_ERR         0xFF
00344 
00345 #if ACCESS_MEM_TO_MEM == true
00346 
00347 /*! \brief Copies data from one memory to another.
00348  *
00349  * \param src_lun   Source Logical Unit Number.
00350  * \param src_addr  Source address of first memory sector to read.
00351  * \param dest_lun  Destination Logical Unit Number.
00352  * \param dest_addr Destination address of first memory sector to write.
00353  * \param nb_sector Number of sectors to copy.
00354  *
00355  * \return Status.
00356  */
00357 extern Ctrl_status stream_mem_to_mem(uint8_t src_lun, uint32_t src_addr,
00358                                      uint8_t dest_lun, uint32_t dest_addr, U16 nb_sector);
00359 
00360 #endif  // ACCESS_MEM_TO_MEM == true
00361 
00362 /*! \brief Returns the state of a streaming data transfer.
00363  *
00364  * \param id  Transfer ID.
00365  *
00366  * \return Status.
00367  *
00368  * \todo Implement.
00369  */
00370 extern Ctrl_status stream_state(uint8_t id);
00371 
00372 /*! \brief Stops a streaming data transfer.
00373  *
00374  * \param id  Transfer ID.
00375  *
00376  * \return Number of remaining sectors.
00377  *
00378  * \todo Implement.
00379  */
00380 extern U16 stream_stop(uint8_t id);
00381 
00382 //! @}
00383 
00384 #endif  // ACCESS_STREAM == true
00385 
00386 /**
00387  * \}
00388  */
00389 
00390 #ifdef __cplusplus
00391 }
00392 #endif
00393 
00394 #endif  // _CTRL_ACCESS_H_
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Defines