SAMV71 Xplained Ultra Software Package 1.4

ctrl_access.h

00001 /*****************************************************************************
00002  *
00003  * \file
00004  *
00005  * \brief Abstraction layer for memory interfaces.
00006  *
00007  * This module contains the interfaces:
00008  *   - MEM <-> USB;
00009  *   - MEM <-> RAM;
00010  *   - MEM <-> MEM.
00011  *
00012  * This module may be configured and expanded to support the following features:
00013  *   - write-protected globals;
00014  *   - password-protected data;
00015  *   - specific features;
00016  *   - etc.
00017  *
00018  * Copyright (c) 2009-2015 Atmel Corporation. All rights reserved.
00019  *
00020  * \asf_license_start
00021  *
00022  * \page License
00023  *
00024  * Redistribution and use in source and binary forms, with or without
00025  * modification, are permitted provided that the following conditions are met:
00026  *
00027  * 1. Redistributions of source code must retain the above copyright notice,
00028  *    this list of conditions and the following disclaimer.
00029  *
00030  * 2. Redistributions in binary form must reproduce the above copyright notice,
00031  *    this list of conditions and the following disclaimer in the documentation
00032  *    and/or other materials provided with the distribution.
00033  *
00034  * 3. The name of Atmel may not be used to endorse or promote products derived
00035  *    from this software without specific prior written permission.
00036  *
00037  * 4. This software may only be redistributed and used in connection with an
00038  *    Atmel microcontroller product.
00039  *
00040  * THIS SOFTWARE IS PROVIDED BY ATMEL "AS IS" AND ANY EXPRESS OR IMPLIED
00041  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
00042  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT ARE
00043  * EXPRESSLY AND SPECIFICALLY DISCLAIMED. IN NO EVENT SHALL ATMEL BE LIABLE FOR
00044  * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
00045  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
00046  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
00047  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
00048  * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
00049  * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
00050  * POSSIBILITY OF SUCH DAMAGE.
00051  *
00052  * \asf_license_stop
00053  *
00054  ******************************************************************************/
00055 /*
00056  * Support and FAQ: visit <a href="http://www.atmel.com/design-support/">Atmel Support</a>
00057  */
00058 
00059 
00060 #ifndef _CTRL_ACCESS_H_
00061 #define _CTRL_ACCESS_H_
00062 
00063 #ifdef __cplusplus
00064 extern "C" {
00065 #endif
00066 
00067 /**
00068  * \defgroup group_common_services_storage_ctrl_access Memory Control Access
00069  *
00070  * Common abstraction layer for memory interfaces. It provides interfaces between:
00071  * Memory and USB, Memory and RAM, Memory and Memory. Common API for XMEGA and UC3.
00072  *
00073  * \{
00074  */
00075 
00076 #include "compiler.h"
00077 #include "conf_access.h"
00078 
00079 #ifndef SECTOR_SIZE
00080 #define SECTOR_SIZE  512
00081 #endif
00082 
00083 //! Status returned by CTRL_ACCESS interfaces.
00084 typedef enum
00085 {
00086   CTRL_GOOD       = PASS,     //!< Success, memory ready.
00087   CTRL_FAIL       = FAIL,     //!< An error occurred.
00088   CTRL_NO_PRESENT = FAIL + 1, //!< Memory unplugged.
00089   CTRL_BUSY       = FAIL + 2  //!< Memory not initialized or changed.
00090 } Ctrl_status;
00091 
00092 
00093 // FYI: Each Logical Unit Number (LUN) corresponds to a memory.
00094 
00095 // Check LUN defines.
00096 #ifndef LUN_0
00097   #error LUN_0 must be defined as ENABLE or DISABLE in conf_access.h
00098 #endif
00099 #ifndef LUN_1
00100   #error LUN_1 must be defined as ENABLE or DISABLE in conf_access.h
00101 #endif
00102 #ifndef LUN_2
00103   #error LUN_2 must be defined as ENABLE or DISABLE in conf_access.h
00104 #endif
00105 #ifndef LUN_3
00106   #error LUN_3 must be defined as ENABLE or DISABLE in conf_access.h
00107 #endif
00108 #ifndef LUN_4
00109   #error LUN_4 must be defined as ENABLE or DISABLE in conf_access.h
00110 #endif
00111 #ifndef LUN_5
00112   #error LUN_5 must be defined as ENABLE or DISABLE in conf_access.h
00113 #endif
00114 #ifndef LUN_6
00115   #error LUN_6 must be defined as ENABLE or DISABLE in conf_access.h
00116 #endif
00117 #ifndef LUN_7
00118   #error LUN_7 must be defined as ENABLE or DISABLE in conf_access.h
00119 #endif
00120 #ifndef LUN_USB
00121   #error LUN_USB must be defined as ENABLE or DISABLE in conf_access.h
00122 #endif
00123 
00124 /*! \name LUN IDs
00125  */
00126 //! @{
00127 #define LUN_ID_0        (0)                 //!< First static LUN.
00128 #define LUN_ID_1        (LUN_ID_0 + LUN_0)
00129 #define LUN_ID_2        (LUN_ID_1 + LUN_1)
00130 #define LUN_ID_3        (LUN_ID_2 + LUN_2)
00131 #define LUN_ID_4        (LUN_ID_3 + LUN_3)
00132 #define LUN_ID_5        (LUN_ID_4 + LUN_4)
00133 #define LUN_ID_6        (LUN_ID_5 + LUN_5)
00134 #define LUN_ID_7        (LUN_ID_6 + LUN_6)
00135 #define MAX_LUN         (LUN_ID_7 + LUN_7)  //!< Number of static LUNs.
00136 #define LUN_ID_USB      (MAX_LUN)           //!< First dynamic LUN (USB host mass storage).
00137 //! @}
00138 
00139 
00140 // Include LUN header files.
00141 #if LUN_0 == ENABLE
00142   #include LUN_0_INCLUDE
00143 #endif
00144 #if LUN_1 == ENABLE
00145   #include LUN_1_INCLUDE
00146 #endif
00147 #if LUN_2 == ENABLE
00148   #include LUN_2_INCLUDE
00149 #endif
00150 #if LUN_3 == ENABLE
00151   #include LUN_3_INCLUDE
00152 #endif
00153 #if LUN_4 == ENABLE
00154   #include LUN_4_INCLUDE
00155 #endif
00156 #if LUN_5 == ENABLE
00157   #include LUN_5_INCLUDE
00158 #endif
00159 #if LUN_6 == ENABLE
00160   #include LUN_6_INCLUDE
00161 #endif
00162 #if LUN_7 == ENABLE
00163   #include LUN_7_INCLUDE
00164 #endif
00165 #if LUN_USB == ENABLE
00166   #include LUN_USB_INCLUDE
00167 #endif
00168 
00169 
00170 // Check the configuration of write protection in conf_access.h.
00171 #ifndef GLOBAL_WR_PROTECT
00172   #error GLOBAL_WR_PROTECT must be defined as true or false in conf_access.h
00173 #endif
00174 
00175 
00176 #if GLOBAL_WR_PROTECT == true
00177 
00178 //! Write protect.
00179 extern bool g_wr_protect;
00180 
00181 #endif
00182 
00183 
00184 /*! \name Control Interface
00185  */
00186 //! @{
00187 
00188 #ifdef FREERTOS_USED
00189 
00190 /*! \brief Initializes the LUN access locker.
00191  *
00192  * \return \c true if the locker was successfully initialized, else \c false.
00193  */
00194 extern bool ctrl_access_init(void);
00195 
00196 #endif  // FREERTOS_USED
00197 
00198 /*! \brief Returns the number of LUNs.
00199  *
00200  * \return Number of LUNs in the system.
00201  */
00202 extern uint8_t get_nb_lun(void);
00203 
00204 /*! \brief Returns the current LUN.
00205  *
00206  * \return Current LUN.
00207  *
00208  * \todo Implement.
00209  */
00210 extern uint8_t get_cur_lun(void);
00211 
00212 /*! \brief Tests the memory state and initializes the memory if required.
00213  *
00214  * The TEST UNIT READY SCSI primary command allows an application client to poll
00215  * a LUN until it is ready without having to allocate memory for returned data.
00216  *
00217  * This command may be used to check the media status of LUNs with removable
00218  * media.
00219  *
00220  * \param lun Logical Unit Number.
00221  *
00222  * \return Status.
00223  */
00224 extern Ctrl_status mem_test_unit_ready(uint8_t lun);
00225 
00226 /*! \brief Returns the address of the last valid sector (512 bytes) in the
00227  *         memory.
00228  *
00229  * \param lun           Logical Unit Number.
00230  * \param u32_nb_sector Pointer to the address of the last valid sector.
00231  *
00232  * \return Status.
00233  */
00234 extern Ctrl_status mem_read_capacity(uint8_t lun, uint32_t *u32_nb_sector);
00235 
00236 /*! \brief Returns the size of the physical sector.
00237  *
00238  * \param lun Logical Unit Number.
00239  *
00240  * \return Sector size (unit: 512 bytes).
00241  */
00242 extern uint8_t mem_sector_size(uint8_t lun);
00243 
00244 /*! \brief Unload/load the medium.
00245  *
00246  * \param lun Logical Unit Number.
00247  * \param unload \c true to unload the medium, \c false to load the medium.
00248  *
00249  * \return \c true if unload/load success, else \c false.
00250  */
00251 extern bool mem_unload(uint8_t lun, bool unload);
00252 
00253 /*! \brief Returns the write-protection state of the memory.
00254  *
00255  * \param lun Logical Unit Number.
00256  *
00257  * \return \c true if the memory is write-protected, else \c false.
00258  *
00259  * \note Only used by removable memories with hardware-specific write
00260  *       protection.
00261  */
00262 extern bool mem_wr_protect(uint8_t lun);
00263 
00264 /*! \brief Tells whether the memory is removable.
00265  *
00266  * \param lun Logical Unit Number.
00267  *
00268  * \return \c true if the memory is removable, else \c false.
00269  */
00270 extern bool mem_removal(uint8_t lun);
00271 
00272 /*! \brief Returns a pointer to the LUN name.
00273  *
00274  * \param lun Logical Unit Number.
00275  *
00276  * \return Pointer to the LUN name string.
00277  */
00278 extern const char *mem_name(uint8_t lun);
00279 
00280 //! @}
00281 
00282 
00283 #if ACCESS_USB == true
00284 
00285 /*! \name MEM <-> USB Interface
00286  */
00287 //! @{
00288 
00289 /*! \brief Transfers data from the memory to USB.
00290  *
00291  * \param lun       Logical Unit Number.
00292  * \param addr      Address of first memory sector to read.
00293  * \param nb_sector Number of sectors to transfer.
00294  *
00295  * \return Status.
00296  */
00297 extern Ctrl_status memory_2_usb(uint8_t lun, uint32_t addr, U16 nb_sector);
00298 
00299 /*! \brief Transfers data from USB to the memory.
00300  *
00301  * \param lun       Logical Unit Number.
00302  * \param addr      Address of first memory sector to write.
00303  * \param nb_sector Number of sectors to transfer.
00304  *
00305  * \return Status.
00306  */
00307 extern Ctrl_status usb_2_memory(uint8_t lun, uint32_t addr, U16 nb_sector);
00308 
00309 //! @}
00310 
00311 #endif  // ACCESS_USB == true
00312 
00313 
00314 #if ACCESS_MEM_TO_RAM == true
00315 
00316 /*! \name MEM <-> RAM Interface
00317  */
00318 //! @{
00319 
00320 /*! \brief Copies 1 data sector from the memory to RAM.
00321  *
00322  * \param lun   Logical Unit Number.
00323  * \param addr  Address of first memory sector to read.
00324  * \param ram   Pointer to RAM buffer to write.
00325  *
00326  * \return Status.
00327  */
00328 extern Ctrl_status memory_2_ram(uint8_t lun, uint32_t addr, void *ram);
00329 
00330 /*! \brief Copies 1 data sector from RAM to the memory.
00331  *
00332  * \param lun   Logical Unit Number.
00333  * \param addr  Address of first memory sector to write.
00334  * \param ram   Pointer to RAM buffer to read.
00335  *
00336  * \return Status.
00337  */
00338 extern Ctrl_status ram_2_memory(uint8_t lun, uint32_t addr, const void *ram);
00339 
00340 //! @}
00341 
00342 #endif  // ACCESS_MEM_TO_RAM == true
00343 
00344 
00345 #if ACCESS_STREAM == true
00346 
00347 /*! \name Streaming MEM <-> MEM Interface
00348  */
00349 //! @{
00350 
00351 //! Erroneous streaming data transfer ID.
00352 #define ID_STREAM_ERR         0xFF
00353 
00354   #if ACCESS_MEM_TO_MEM == true
00355 
00356 /*! \brief Copies data from one memory to another.
00357  *
00358  * \param src_lun   Source Logical Unit Number.
00359  * \param src_addr  Source address of first memory sector to read.
00360  * \param dest_lun  Destination Logical Unit Number.
00361  * \param dest_addr Destination address of first memory sector to write.
00362  * \param nb_sector Number of sectors to copy.
00363  *
00364  * \return Status.
00365  */
00366 extern Ctrl_status stream_mem_to_mem(uint8_t src_lun, uint32_t src_addr, uint8_t dest_lun, uint32_t dest_addr, U16 nb_sector);
00367 
00368   #endif  // ACCESS_MEM_TO_MEM == true
00369 
00370 /*! \brief Returns the state of a streaming data transfer.
00371  *
00372  * \param id  Transfer ID.
00373  *
00374  * \return Status.
00375  *
00376  * \todo Implement.
00377  */
00378 extern Ctrl_status stream_state(uint8_t id);
00379 
00380 /*! \brief Stops a streaming data transfer.
00381  *
00382  * \param id  Transfer ID.
00383  *
00384  * \return Number of remaining sectors.
00385  *
00386  * \todo Implement.
00387  */
00388 extern U16 stream_stop(uint8_t id);
00389 
00390 //! @}
00391 
00392 #endif  // ACCESS_STREAM == true
00393 
00394 /**
00395  * \}
00396  */
00397 
00398 #ifdef __cplusplus
00399 }
00400 #endif
00401 
00402 #endif  // _CTRL_ACCESS_H_
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Defines