source: arduino-1-6-7/trunk/fuentes/arduino-ide-amd64/hardware/arduino/avr/firmwares/wifishield/wifiHD/src/SOFTWARE_FRAMEWORK/SERVICES/MEMORY/CTRL_ACCESS/ctrl_access.h @ 4837

Last change on this file since 4837 was 4837, checked in by daduve, 2 years ago

Adding new version

File size: 9.6 KB
Line 
1/* This header file is part of the ATMEL AVR-UC3-SoftwareFramework-1.7.0 Release */
2
3/*This file is prepared for Doxygen automatic documentation generation.*/
4/*! \file *********************************************************************
5 *
6 * \brief Abstraction layer for memory interfaces.
7 *
8 * This module contains the interfaces:
9 *   - MEM <-> USB;
10 *   - MEM <-> RAM;
11 *   - MEM <-> MEM.
12 *
13 * This module may be configured and expanded to support the following features:
14 *   - write-protected globals;
15 *   - password-protected data;
16 *   - specific features;
17 *   - etc.
18 *
19 * - Compiler:           IAR EWAVR32 and GNU GCC for AVR32
20 * - Supported devices:  All AVR32 devices can be used.
21 * - AppNote:
22 *
23 * \author               Atmel Corporation: http://www.atmel.com \n
24 *                       Support and FAQ: http://support.atmel.no/
25 *
26 ******************************************************************************/
27
28/* Copyright (c) 2009 Atmel Corporation. All rights reserved.
29 *
30 * Redistribution and use in source and binary forms, with or without
31 * modification, are permitted provided that the following conditions are met:
32 *
33 * 1. Redistributions of source code must retain the above copyright notice, this
34 * list of conditions and the following disclaimer.
35 *
36 * 2. Redistributions in binary form must reproduce the above copyright notice,
37 * this list of conditions and the following disclaimer in the documentation
38 * and/or other materials provided with the distribution.
39 *
40 * 3. The name of Atmel may not be used to endorse or promote products derived
41 * from this software without specific prior written permission.
42 *
43 * 4. This software may only be redistributed and used in connection with an Atmel
44 * AVR product.
45 *
46 * THIS SOFTWARE IS PROVIDED BY ATMEL "AS IS" AND ANY EXPRESS OR IMPLIED
47 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
48 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT ARE
49 * EXPRESSLY AND SPECIFICALLY DISCLAIMED. IN NO EVENT SHALL ATMEL BE LIABLE FOR
50 * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
51 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
52 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
53 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
54 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
55 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE
56 *
57 */
58
59#ifndef _CTRL_ACCESS_H_
60#define _CTRL_ACCESS_H_
61
62#include "compiler.h"
63#include "conf_access.h"
64
65
66//! Status returned by CTRL_ACCESS interfaces.
67typedef enum
68{
69  CTRL_GOOD       = PASS,     //!< Success, memory ready.
70  CTRL_FAIL       = FAIL,     //!< An error occurred.
71  CTRL_NO_PRESENT = FAIL + 1, //!< Memory unplugged.
72  CTRL_BUSY       = FAIL + 2  //!< Memory not initialized or changed.
73} Ctrl_status;
74
75
76// FYI: Each Logical Unit Number (LUN) corresponds to a memory.
77
78// Check LUN defines.
79#ifndef LUN_0
80  #error LUN_0 must be defined as ENABLE or DISABLE in conf_access.h
81#endif
82#ifndef LUN_1
83  #error LUN_1 must be defined as ENABLE or DISABLE in conf_access.h
84#endif
85#ifndef LUN_2
86  #error LUN_2 must be defined as ENABLE or DISABLE in conf_access.h
87#endif
88#ifndef LUN_3
89  #error LUN_3 must be defined as ENABLE or DISABLE in conf_access.h
90#endif
91#ifndef LUN_4
92  #error LUN_4 must be defined as ENABLE or DISABLE in conf_access.h
93#endif
94#ifndef LUN_5
95  #error LUN_5 must be defined as ENABLE or DISABLE in conf_access.h
96#endif
97#ifndef LUN_6
98  #error LUN_6 must be defined as ENABLE or DISABLE in conf_access.h
99#endif
100#ifndef LUN_7
101  #error LUN_7 must be defined as ENABLE or DISABLE in conf_access.h
102#endif
103#ifndef LUN_USB
104  #error LUN_USB must be defined as ENABLE or DISABLE in conf_access.h
105#endif
106
107/*! \name LUN IDs
108 */
109//! @{
110#define LUN_ID_0        (0)                 //!< First static LUN.
111#define LUN_ID_1        (LUN_ID_0 + LUN_0)
112#define LUN_ID_2        (LUN_ID_1 + LUN_1)
113#define LUN_ID_3        (LUN_ID_2 + LUN_2)
114#define LUN_ID_4        (LUN_ID_3 + LUN_3)
115#define LUN_ID_5        (LUN_ID_4 + LUN_4)
116#define LUN_ID_6        (LUN_ID_5 + LUN_5)
117#define LUN_ID_7        (LUN_ID_6 + LUN_6)
118#define MAX_LUN         (LUN_ID_7 + LUN_7)  //!< Number of static LUNs.
119#define LUN_ID_USB      (MAX_LUN)           //!< First dynamic LUN (USB host mass storage).
120//! @}
121
122
123// Include LUN header files.
124#if LUN_0 == ENABLE
125  #include LUN_0_INCLUDE
126#endif
127#if LUN_1 == ENABLE
128  #include LUN_1_INCLUDE
129#endif
130#if LUN_2 == ENABLE
131  #include LUN_2_INCLUDE
132#endif
133#if LUN_3 == ENABLE
134  #include LUN_3_INCLUDE
135#endif
136#if LUN_4 == ENABLE
137  #include LUN_4_INCLUDE
138#endif
139#if LUN_5 == ENABLE
140  #include LUN_5_INCLUDE
141#endif
142#if LUN_6 == ENABLE
143  #include LUN_6_INCLUDE
144#endif
145#if LUN_7 == ENABLE
146  #include LUN_7_INCLUDE
147#endif
148#if LUN_USB == ENABLE
149  #include LUN_USB_INCLUDE
150#endif
151
152
153// Check the configuration of write protection in conf_access.h.
154#ifndef GLOBAL_WR_PROTECT
155  #error GLOBAL_WR_PROTECT must be defined as ENABLED or DISABLED in conf_access.h
156#endif
157
158
159#if GLOBAL_WR_PROTECT == ENABLED
160
161//! Write protect.
162extern Bool g_wr_protect;
163
164#endif
165
166
167/*! \name Control Interface
168 */
169//! @{
170
171#ifdef FREERTOS_USED
172
173/*! \brief Initializes the LUN access locker.
174 *
175 * \return \c TRUE if the locker was successfully initialized, else \c FALSE.
176 */
177extern Bool ctrl_access_init(void);
178
179#endif  // FREERTOS_USED
180
181/*! \brief Returns the number of LUNs.
182 *
183 * \return Number of LUNs in the system.
184 */
185extern U8 get_nb_lun(void);
186
187/*! \brief Returns the current LUN.
188 *
189 * \return Current LUN.
190 *
191 * \todo Implement.
192 */
193extern U8 get_cur_lun(void);
194
195/*! \brief Tests the memory state and initializes the memory if required.
196 *
197 * The TEST UNIT READY SCSI primary command allows an application client to poll
198 * a LUN until it is ready without having to allocate memory for returned data.
199 *
200 * This command may be used to check the media status of LUNs with removable
201 * media.
202 *
203 * \param lun Logical Unit Number.
204 *
205 * \return Status.
206 */
207extern Ctrl_status mem_test_unit_ready(U8 lun);
208
209/*! \brief Returns the address of the last valid sector (512 bytes) in the
210 *         memory.
211 *
212 * \param lun           Logical Unit Number.
213 * \param u32_nb_sector Pointer to the address of the last valid sector.
214 *
215 * \return Status.
216 */
217extern Ctrl_status mem_read_capacity(U8 lun, U32 *u32_nb_sector);
218
219/*! \brief Returns the size of the physical sector.
220 *
221 * \param lun Logical Unit Number.
222 *
223 * \return Sector size (unit: 512 bytes).
224 */
225extern U8 mem_sector_size(U8 lun);
226
227/*! \brief Returns the write-protection state of the memory.
228 *
229 * \param lun Logical Unit Number.
230 *
231 * \return \c TRUE if the memory is write-protected, else \c FALSE.
232 *
233 * \note Only used by removable memories with hardware-specific write
234 *       protection.
235 */
236extern Bool mem_wr_protect(U8 lun);
237
238/*! \brief Tells whether the memory is removable.
239 *
240 * \param lun Logical Unit Number.
241 *
242 * \return \c TRUE if the memory is removable, else \c FALSE.
243 */
244extern Bool mem_removal(U8 lun);
245
246/*! \brief Returns a pointer to the LUN name.
247 *
248 * \param lun Logical Unit Number.
249 *
250 * \return Pointer to the LUN name string.
251 */
252extern const char *mem_name(U8 lun);
253
254//! @}
255
256
257#if ACCESS_USB == ENABLED
258
259/*! \name MEM <-> USB Interface
260 */
261//! @{
262
263/*! \brief Tranfers data from the memory to USB.
264 *
265 * \param lun       Logical Unit Number.
266 * \param addr      Address of first memory sector to read.
267 * \param nb_sector Number of sectors to transfer.
268 *
269 * \return Status.
270 */
271extern Ctrl_status memory_2_usb(U8 lun, U32 addr, U16 nb_sector);
272
273/*! \brief Tranfers data from USB to the memory.
274 *
275 * \param lun       Logical Unit Number.
276 * \param addr      Address of first memory sector to write.
277 * \param nb_sector Number of sectors to transfer.
278 *
279 * \return Status.
280 */
281extern Ctrl_status usb_2_memory(U8 lun, U32 addr, U16 nb_sector);
282
283//! @}
284
285#endif  // ACCESS_USB == ENABLED
286
287
288#if ACCESS_MEM_TO_RAM == ENABLED
289
290/*! \name MEM <-> RAM Interface
291 */
292//! @{
293
294/*! \brief Copies 1 data sector from the memory to RAM.
295 *
296 * \param lun   Logical Unit Number.
297 * \param addr  Address of first memory sector to read.
298 * \param ram   Pointer to RAM buffer to write.
299 *
300 * \return Status.
301 */
302extern Ctrl_status memory_2_ram(U8 lun, U32 addr, void *ram);
303
304/*! \brief Copies 1 data sector from RAM to the memory.
305 *
306 * \param lun   Logical Unit Number.
307 * \param addr  Address of first memory sector to write.
308 * \param ram   Pointer to RAM buffer to read.
309 *
310 * \return Status.
311 */
312extern Ctrl_status ram_2_memory(U8 lun, U32 addr, const void *ram);
313
314//! @}
315
316#endif  // ACCESS_MEM_TO_RAM == ENABLED
317
318
319#if ACCESS_STREAM == ENABLED
320
321/*! \name Streaming MEM <-> MEM Interface
322 */
323//! @{
324
325//! Erroneous streaming data transfer ID.
326#define ID_STREAM_ERR         0xFF
327
328  #if ACCESS_MEM_TO_MEM == ENABLED
329
330/*! \brief Copies data from one memory to another.
331 *
332 * \param src_lun   Source Logical Unit Number.
333 * \param src_addr  Source address of first memory sector to read.
334 * \param dest_lun  Destination Logical Unit Number.
335 * \param dest_addr Destination address of first memory sector to write.
336 * \param nb_sector Number of sectors to copy.
337 *
338 * \return Status.
339 */
340extern Ctrl_status stream_mem_to_mem(U8 src_lun, U32 src_addr, U8 dest_lun, U32 dest_addr, U16 nb_sector);
341
342  #endif  // ACCESS_MEM_TO_MEM == ENABLED
343
344/*! \brief Returns the state of a streaming data transfer.
345 *
346 * \param id  Transfer ID.
347 *
348 * \return Status.
349 *
350 * \todo Implement.
351 */
352extern Ctrl_status stream_state(U8 id);
353
354/*! \brief Stops a streaming data transfer.
355 *
356 * \param id  Transfer ID.
357 *
358 * \return Number of remaining sectors.
359 *
360 * \todo Implement.
361 */
362extern U16 stream_stop(U8 id);
363
364//! @}
365
366#endif  // ACCESS_STREAM == ENABLED
367
368
369#endif  // _CTRL_ACCESS_H_
Note: See TracBrowser for help on using the repository browser.