source: arduino-1-6-7/trunk/fuentes/arduino-ide-amd64/hardware/arduino/avr/firmwares/wifishield/wifi_dnld/src/SOFTWARE_FRAMEWORK/DRIVERS/FLASHC/flashc.h @ 46

Last change on this file since 46 was 46, checked in by jrpelegrina, 4 years ago

First release to Xenial

File size: 36.3 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 FLASHC driver for AVR32 UC3.
7 *
8 * AVR32 Flash Controller driver module.
9 *
10 * - Compiler:           IAR EWAVR32 and GNU GCC for AVR32
11 * - Supported devices:  All AVR32 devices with a FLASHC module can be used.
12 * - AppNote:
13 *
14 * \author               Atmel Corporation: http://www.atmel.com \n
15 *                       Support and FAQ: http://support.atmel.no/
16 *
17 ******************************************************************************/
18
19/* Copyright (c) 2009 Atmel Corporation. All rights reserved.
20 *
21 * Redistribution and use in source and binary forms, with or without
22 * modification, are permitted provided that the following conditions are met:
23 *
24 * 1. Redistributions of source code must retain the above copyright notice, this
25 * list of conditions and the following disclaimer.
26 *
27 * 2. Redistributions in binary form must reproduce the above copyright notice,
28 * this list of conditions and the following disclaimer in the documentation
29 * and/or other materials provided with the distribution.
30 *
31 * 3. The name of Atmel may not be used to endorse or promote products derived
32 * from this software without specific prior written permission.
33 *
34 * 4. This software may only be redistributed and used in connection with an Atmel
35 * AVR product.
36 *
37 * THIS SOFTWARE IS PROVIDED BY ATMEL "AS IS" AND ANY EXPRESS OR IMPLIED
38 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
39 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT ARE
40 * EXPRESSLY AND SPECIFICALLY DISCLAIMED. IN NO EVENT SHALL ATMEL BE LIABLE FOR
41 * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
42 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
43 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
44 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
45 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
46 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE
47 *
48 */
49
50#ifndef _FLASHC_H_
51#define _FLASHC_H_
52
53#include <avr32/io.h>
54#include <stddef.h>
55#include "compiler.h"
56
57//! Number of flash regions defined by the FLASHC.
58#define AVR32_FLASHC_REGIONS  (AVR32_FLASHC_FLASH_SIZE /\
59                               (AVR32_FLASHC_PAGES_PR_REGION * AVR32_FLASHC_PAGE_SIZE))
60
61
62/*! \name Flash Properties
63 */
64//! @{
65
66/*! \brief Gets the size of the whole flash array.
67 *
68 * \return The size of the whole flash array in bytes.
69 */
70extern unsigned int flashc_get_flash_size(void);
71
72/*! \brief Gets the total number of pages in the flash array.
73 *
74 * \return The total number of pages in the flash array.
75 */
76extern unsigned int flashc_get_page_count(void);
77
78/*! \brief Gets the number of pages in each flash region.
79 *
80 * \return The number of pages in each flash region.
81 */
82extern unsigned int flashc_get_page_count_per_region(void);
83
84/*! \brief Gets the region number of a page.
85 *
86 * \param page_number The page number:
87 *   \arg \c 0 to <tt>(flashc_get_page_count() - 1)</tt>: a page number within
88 *        the flash array;
89 *   \arg <tt>< 0</tt>: the current page number.
90 *
91 * \return The region number of the specified page.
92 */
93extern unsigned int flashc_get_page_region(int page_number);
94
95/*! \brief Gets the number of the first page of a region.
96 *
97 * \param region The region number: \c 0 to <tt>(AVR32_FLASHC_REGIONS - 1)</tt>.
98 *
99 * \return The number of the first page of the specified region.
100 */
101extern unsigned int flashc_get_region_first_page_number(unsigned int region);
102
103//! @}
104
105
106/*! \name FLASHC Control
107 */
108//! @{
109
110/*! \brief Gets the number of wait states of flash read accesses.
111 *
112 * \return The number of wait states of flash read accesses.
113 */
114extern unsigned int flashc_get_wait_state(void);
115
116/*! \brief Sets the number of wait states of flash read accesses.
117 *
118 * \param wait_state The number of wait states of flash read accesses: \c 0 to
119 *                   \c 1.
120 */
121extern void flashc_set_wait_state(unsigned int wait_state);
122
123/*! \brief Tells whether the Flash Ready interrupt is enabled.
124 *
125 * \return Whether the Flash Ready interrupt is enabled.
126 */
127extern Bool flashc_is_ready_int_enabled(void);
128
129/*! \brief Enables or disables the Flash Ready interrupt.
130 *
131 * \param enable Whether to enable the Flash Ready interrupt: \c TRUE or
132 *               \c FALSE.
133 */
134extern void flashc_enable_ready_int(Bool enable);
135
136/*! \brief Tells whether the Lock Error interrupt is enabled.
137 *
138 * \return Whether the Lock Error interrupt is enabled.
139 */
140extern Bool flashc_is_lock_error_int_enabled(void);
141
142/*! \brief Enables or disables the Lock Error interrupt.
143 *
144 * \param enable Whether to enable the Lock Error interrupt: \c TRUE or
145 *               \c FALSE.
146 */
147extern void flashc_enable_lock_error_int(Bool enable);
148
149/*! \brief Tells whether the Programming Error interrupt is enabled.
150 *
151 * \return Whether the Programming Error interrupt is enabled.
152 */
153extern Bool flashc_is_prog_error_int_enabled(void);
154
155/*! \brief Enables or disables the Programming Error interrupt.
156 *
157 * \param enable Whether to enable the Programming Error interrupt: \c TRUE or
158 *               \c FALSE.
159 */
160extern void flashc_enable_prog_error_int(Bool enable);
161
162//! @}
163
164
165/*! \name FLASHC Status
166 */
167//! @{
168
169/*! \brief Tells whether the FLASHC is ready to run a new command.
170 *
171 * \return Whether the FLASHC is ready to run a new command.
172 */
173extern Bool flashc_is_ready(void);
174
175/*! \brief Waits actively until the FLASHC is ready to run a new command.
176 *
177 * This is the default function assigned to \ref flashc_wait_until_ready.
178 */
179extern void flashc_default_wait_until_ready(void);
180
181//! Pointer to the function used by the driver when it needs to wait until the
182//! FLASHC is ready to run a new command.
183//! The default function is \ref flashc_default_wait_until_ready.
184//! The user may change this pointer to use another implementation.
185extern void (*volatile flashc_wait_until_ready)(void);
186
187/*! \brief Tells whether a Lock Error has occurred during the last function
188 *         called that issued one or more FLASHC commands.
189 *
190 * \return Whether a Lock Error has occurred during the last function called
191 *         that issued one or more FLASHC commands.
192 */
193extern Bool flashc_is_lock_error(void);
194
195/*! \brief Tells whether a Programming Error has occurred during the last
196 *         function called that issued one or more FLASHC commands.
197 *
198 * \return Whether a Programming Error has occurred during the last function
199 *         called that issued one or more FLASHC commands.
200 */
201extern Bool flashc_is_programming_error(void);
202
203//! @}
204
205
206/*! \name FLASHC Command Control
207 */
208//! @{
209
210/*! \brief Gets the last issued FLASHC command.
211 *
212 * \return The last issued FLASHC command.
213 */
214extern unsigned int flashc_get_command(void);
215
216/*! \brief Gets the current FLASHC page number.
217 *
218 * \return The current FLASHC page number.
219 */
220extern unsigned int flashc_get_page_number(void);
221
222/*! \brief Issues a FLASHC command.
223 *
224 * \param command The command: \c AVR32_FLASHC_FCMD_CMD_x.
225 * \param page_number The page number to apply the command to:
226 *   \arg \c 0 to <tt>(flashc_get_page_count() - 1)</tt>: a page number within
227 *        the flash array;
228 *   \arg <tt>< 0</tt>: use this to apply the command to the current page number
229 *        or if the command does not apply to any page number;
230 *   \arg this argument may have other meanings according to the command. See
231 *        the FLASHC chapter of the MCU datasheet.
232 *
233 * \warning A Lock Error is issued if the command violates the protection
234 *          mechanism.
235 *
236 * \warning A Programming Error is issued if the command is invalid.
237 *
238 * \note The FLASHC error status returned by \ref flashc_is_lock_error and
239 *       \ref flashc_is_programming_error is updated.
240 */
241extern void flashc_issue_command(unsigned int command, int page_number);
242
243//! @}
244
245
246/*! \name FLASHC Global Commands
247 */
248//! @{
249
250/*! \brief Issues a No Operation command to the FLASHC.
251 *
252 * \note The FLASHC error status returned by \ref flashc_is_lock_error and
253 *       \ref flashc_is_programming_error is updated.
254 */
255extern void flashc_no_operation(void);
256
257/*! \brief Issues an Erase All command to the FLASHC.
258 *
259 * This command erases all bits in the flash array, the general-purpose fuse
260 * bits and the Security bit. The User page is not erased.
261 *
262 * This command also ensures that all volatile memories, such as register file
263 * and RAMs, are erased before the Security bit is erased, i.e. deactivated.
264 *
265 * \warning A Lock Error is issued if at least one region is locked or the
266 *          bootloader protection is active.
267 *
268 * \note The FLASHC error status returned by \ref flashc_is_lock_error and
269 *       \ref flashc_is_programming_error is updated.
270 *
271 * \note An erase operation can only set bits.
272 */
273extern void flashc_erase_all(void);
274
275//! @}
276
277
278/*! \name FLASHC Protection Mechanisms
279 */
280//! @{
281
282/*! \brief Tells whether the Security bit is active.
283 *
284 * \return Whether the Security bit is active.
285 */
286extern Bool flashc_is_security_bit_active(void);
287
288/*! \brief Activates the Security bit.
289 *
290 * \note The FLASHC error status returned by \ref flashc_is_lock_error and
291 *       \ref flashc_is_programming_error is updated.
292 */
293extern void flashc_activate_security_bit(void);
294
295/*! \brief Gets the bootloader protected size.
296 *
297 * \return The bootloader protected size in bytes.
298 */
299extern unsigned int flashc_get_bootloader_protected_size(void);
300
301/*! \brief Sets the bootloader protected size.
302 *
303 * \param bootprot_size The wanted bootloader protected size in bytes. If this
304 *                      size is not supported, the actual size will be the
305 *                      nearest greater available size or the maximal possible
306 *                      size if the requested size is too large.
307 *
308 * \return The actual bootloader protected size in bytes.
309 *
310 * \warning A Lock Error is issued if the Security bit is active.
311 *
312 * \note The FLASHC error status returned by \ref flashc_is_lock_error and
313 *       \ref flashc_is_programming_error is updated.
314 */
315extern unsigned int flashc_set_bootloader_protected_size(unsigned int bootprot_size);
316
317/*! \brief Tells whether external privileged fetch is locked.
318 *
319 * \return Whether external privileged fetch is locked.
320 */
321extern Bool flashc_is_external_privileged_fetch_locked(void);
322
323/*! \brief Locks or unlocks external privileged fetch.
324 *
325 * \param lock Whether to lock external privileged fetch: \c TRUE or \c FALSE.
326 *
327 * \warning A Lock Error is issued if the Security bit is active.
328 *
329 * \note The FLASHC error status returned by \ref flashc_is_lock_error and
330 *       \ref flashc_is_programming_error is updated.
331 */
332extern void flashc_lock_external_privileged_fetch(Bool lock);
333
334/*! \brief Tells whether the region of a page is locked.
335 *
336 * \param page_number The page number:
337 *   \arg \c 0 to <tt>(flashc_get_page_count() - 1)</tt>: a page number within
338 *        the flash array;
339 *   \arg <tt>< 0</tt>: the current page number.
340 *
341 * \return Whether the region of the specified page is locked.
342 */
343extern Bool flashc_is_page_region_locked(int page_number);
344
345/*! \brief Tells whether a region is locked.
346 *
347 * \param region The region number: \c 0 to <tt>(AVR32_FLASHC_REGIONS - 1)</tt>.
348 *
349 * \return Whether the specified region is locked.
350 */
351extern Bool flashc_is_region_locked(unsigned int region);
352
353/*! \brief Locks or unlocks the region of a page.
354 *
355 * \param page_number The page number:
356 *   \arg \c 0 to <tt>(flashc_get_page_count() - 1)</tt>: a page number within
357 *        the flash array;
358 *   \arg <tt>< 0</tt>: the current page number.
359 * \param lock Whether to lock the region of the specified page: \c TRUE or
360 *             \c FALSE.
361 *
362 * \note The FLASHC error status returned by \ref flashc_is_lock_error and
363 *       \ref flashc_is_programming_error is updated.
364 */
365extern void flashc_lock_page_region(int page_number, Bool lock);
366
367/*! \brief Locks or unlocks a region.
368 *
369 * \param region The region number: \c 0 to <tt>(AVR32_FLASHC_REGIONS - 1)</tt>.
370 * \param lock Whether to lock the specified region: \c TRUE or \c FALSE.
371 *
372 * \note The FLASHC error status returned by \ref flashc_is_lock_error and
373 *       \ref flashc_is_programming_error is updated.
374 */
375extern void flashc_lock_region(unsigned int region, Bool lock);
376
377/*! \brief Locks or unlocks all regions.
378 *
379 * \param lock Whether to lock the regions: \c TRUE or \c FALSE.
380 *
381 * \note The FLASHC error status returned by \ref flashc_is_lock_error and
382 *       \ref flashc_is_programming_error is updated.
383 */
384extern void flashc_lock_all_regions(Bool lock);
385
386//! @}
387
388
389/*! \name Access to General-Purpose Fuses
390 */
391//! @{
392
393/*! \brief Reads a general-purpose fuse bit.
394 *
395 * \param gp_fuse_bit The general-purpose fuse bit: \c 0 to \c 63.
396 *
397 * \return The value of the specified general-purpose fuse bit.
398 *
399 * \note The actual number of general-purpose fuse bits implemented by hardware
400 *       is given by \c AVR32_FLASHC_GPF_NUM. The other bits among the 64 are
401 *       fixed at 1 by hardware.
402 */
403extern Bool flashc_read_gp_fuse_bit(unsigned int gp_fuse_bit);
404
405/*! \brief Reads a general-purpose fuse bit-field.
406 *
407 * \param pos The bit-position of the general-purpose fuse bit-field: \c 0 to
408 *            \c 63.
409 * \param width The bit-width of the general-purpose fuse bit-field: \c 0 to
410 *              \c 64.
411 *
412 * \return The value of the specified general-purpose fuse bit-field.
413 *
414 * \note The actual number of general-purpose fuse bits implemented by hardware
415 *       is given by \c AVR32_FLASHC_GPF_NUM. The other bits among the 64 are
416 *       fixed at 1 by hardware.
417 */
418extern U64 flashc_read_gp_fuse_bitfield(unsigned int pos, unsigned int width);
419
420/*! \brief Reads a general-purpose fuse byte.
421 *
422 * \param gp_fuse_byte The general-purpose fuse byte: \c 0 to \c 7.
423 *
424 * \return The value of the specified general-purpose fuse byte.
425 *
426 * \note The actual number of general-purpose fuse bits implemented by hardware
427 *       is given by \c AVR32_FLASHC_GPF_NUM. The other bits among the 64 are
428 *       fixed at 1 by hardware.
429 */
430extern U8 flashc_read_gp_fuse_byte(unsigned int gp_fuse_byte);
431
432/*! \brief Reads all general-purpose fuses.
433 *
434 * \return The value of all general-purpose fuses as a word.
435 *
436 * \note The actual number of general-purpose fuse bits implemented by hardware
437 *       is given by \c AVR32_FLASHC_GPF_NUM. The other bits among the 64 are
438 *       fixed at 1 by hardware.
439 */
440extern U64 flashc_read_all_gp_fuses(void);
441
442/*! \brief Erases a general-purpose fuse bit.
443 *
444 * \param gp_fuse_bit The general-purpose fuse bit: \c 0 to \c 63.
445 * \param check Whether to check erase: \c TRUE or \c FALSE.
446 *
447 * \return Whether the erase succeeded or always \c TRUE if erase check was not
448 *         requested.
449 *
450 * \warning A Lock Error is issued if the Security bit is active and the command
451 *          is applied to BOOTPROT or EPFL fuses.
452 *
453 * \note The FLASHC error status returned by \ref flashc_is_lock_error and
454 *       \ref flashc_is_programming_error is updated.
455 *
456 * \note An erase operation can only set bits.
457 *
458 * \note The actual number of general-purpose fuse bits implemented by hardware
459 *       is given by \c AVR32_FLASHC_GPF_NUM. The other bits among the 64 are
460 *       fixed at 1 by hardware.
461 */
462extern Bool flashc_erase_gp_fuse_bit(unsigned int gp_fuse_bit, Bool check);
463
464/*! \brief Erases a general-purpose fuse bit-field.
465 *
466 * \param pos The bit-position of the general-purpose fuse bit-field: \c 0 to
467 *            \c 63.
468 * \param width The bit-width of the general-purpose fuse bit-field: \c 0 to
469 *              \c 64.
470 * \param check Whether to check erase: \c TRUE or \c FALSE.
471 *
472 * \return Whether the erase succeeded or always \c TRUE if erase check was not
473 *         requested.
474 *
475 * \warning A Lock Error is issued if the Security bit is active and the command
476 *          is applied to BOOTPROT or EPFL fuses.
477 *
478 * \note The FLASHC error status returned by \ref flashc_is_lock_error and
479 *       \ref flashc_is_programming_error is updated.
480 *
481 * \note An erase operation can only set bits.
482 *
483 * \note The actual number of general-purpose fuse bits implemented by hardware
484 *       is given by \c AVR32_FLASHC_GPF_NUM. The other bits among the 64 are
485 *       fixed at 1 by hardware.
486 */
487extern Bool flashc_erase_gp_fuse_bitfield(unsigned int pos, unsigned int width, Bool check);
488
489/*! \brief Erases a general-purpose fuse byte.
490 *
491 * \param gp_fuse_byte The general-purpose fuse byte: \c 0 to \c 7.
492 * \param check Whether to check erase: \c TRUE or \c FALSE.
493 *
494 * \return Whether the erase succeeded or always \c TRUE if erase check was not
495 *         requested.
496 *
497 * \warning A Lock Error is issued if the Security bit is active.
498 *
499 * \note The FLASHC error status returned by \ref flashc_is_lock_error and
500 *       \ref flashc_is_programming_error is updated.
501 *
502 * \note An erase operation can only set bits.
503 *
504 * \note The actual number of general-purpose fuse bits implemented by hardware
505 *       is given by \c AVR32_FLASHC_GPF_NUM. The other bits among the 64 are
506 *       fixed at 1 by hardware.
507 */
508extern Bool flashc_erase_gp_fuse_byte(unsigned int gp_fuse_byte, Bool check);
509
510/*! \brief Erases all general-purpose fuses.
511 *
512 * \param check Whether to check erase: \c TRUE or \c FALSE.
513 *
514 * \return Whether the erase succeeded or always \c TRUE if erase check was not
515 *         requested.
516 *
517 * \warning A Lock Error is issued if the Security bit is active.
518 *
519 * \note The FLASHC error status returned by \ref flashc_is_lock_error and
520 *       \ref flashc_is_programming_error is updated.
521 *
522 * \note An erase operation can only set bits.
523 *
524 * \note The actual number of general-purpose fuse bits implemented by hardware
525 *       is given by \c AVR32_FLASHC_GPF_NUM. The other bits among the 64 are
526 *       fixed at 1 by hardware.
527 */
528extern Bool flashc_erase_all_gp_fuses(Bool check);
529
530/*! \brief Writes a general-purpose fuse bit.
531 *
532 * \param gp_fuse_bit The general-purpose fuse bit: \c 0 to \c 63.
533 * \param value The value of the specified general-purpose fuse bit.
534 *
535 * \warning A Lock Error is issued if the Security bit is active and the command
536 *          is applied to BOOTPROT or EPFL fuses.
537 *
538 * \note The FLASHC error status returned by \ref flashc_is_lock_error and
539 *       \ref flashc_is_programming_error is updated.
540 *
541 * \note A write operation can only clear bits.
542 *
543 * \note The actual number of general-purpose fuse bits implemented by hardware
544 *       is given by \c AVR32_FLASHC_GPF_NUM. The other bits among the 64 are
545 *       fixed at 1 by hardware.
546 */
547extern void flashc_write_gp_fuse_bit(unsigned int gp_fuse_bit, Bool value);
548
549/*! \brief Writes a general-purpose fuse bit-field.
550 *
551 * \param pos The bit-position of the general-purpose fuse bit-field: \c 0 to
552 *            \c 63.
553 * \param width The bit-width of the general-purpose fuse bit-field: \c 0 to
554 *              \c 64.
555 * \param value The value of the specified general-purpose fuse bit-field.
556 *
557 * \warning A Lock Error is issued if the Security bit is active and the command
558 *          is applied to BOOTPROT or EPFL fuses.
559 *
560 * \note The FLASHC error status returned by \ref flashc_is_lock_error and
561 *       \ref flashc_is_programming_error is updated.
562 *
563 * \note A write operation can only clear bits.
564 *
565 * \note The actual number of general-purpose fuse bits implemented by hardware
566 *       is given by \c AVR32_FLASHC_GPF_NUM. The other bits among the 64 are
567 *       fixed at 1 by hardware.
568 */
569extern void flashc_write_gp_fuse_bitfield(unsigned int pos, unsigned int width, U64 value);
570
571/*! \brief Writes a general-purpose fuse byte.
572 *
573 * \param gp_fuse_byte The general-purpose fuse byte: \c 0 to \c 7.
574 * \param value The value of the specified general-purpose fuse byte.
575 *
576 * \warning A Lock Error is issued if the Security bit is active.
577 *
578 * \note The FLASHC error status returned by \ref flashc_is_lock_error and
579 *       \ref flashc_is_programming_error is updated.
580 *
581 * \note A write operation can only clear bits.
582 *
583 * \note The actual number of general-purpose fuse bits implemented by hardware
584 *       is given by \c AVR32_FLASHC_GPF_NUM. The other bits among the 64 are
585 *       fixed at 1 by hardware.
586 */
587extern void flashc_write_gp_fuse_byte(unsigned int gp_fuse_byte, U8 value);
588
589/*! \brief Writes all general-purpose fuses.
590 *
591 * \param value The value of all general-purpose fuses as a word.
592 *
593 * \warning A Lock Error is issued if the Security bit is active.
594 *
595 * \note The FLASHC error status returned by \ref flashc_is_lock_error and
596 *       \ref flashc_is_programming_error is updated.
597 *
598 * \note A write operation can only clear bits.
599 *
600 * \note The actual number of general-purpose fuse bits implemented by hardware
601 *       is given by \c AVR32_FLASHC_GPF_NUM. The other bits among the 64 are
602 *       fixed at 1 by hardware.
603 */
604extern void flashc_write_all_gp_fuses(U64 value);
605
606/*! \brief Sets a general-purpose fuse bit with the appropriate erase and write
607 *         operations.
608 *
609 * \param gp_fuse_bit The general-purpose fuse bit: \c 0 to \c 63.
610 * \param value The value of the specified general-purpose fuse bit.
611 *
612 * \warning A Lock Error is issued if the Security bit is active and the command
613 *          is applied to BOOTPROT or EPFL fuses.
614 *
615 * \note The FLASHC error status returned by \ref flashc_is_lock_error and
616 *       \ref flashc_is_programming_error is updated.
617 *
618 * \note The actual number of general-purpose fuse bits implemented by hardware
619 *       is given by \c AVR32_FLASHC_GPF_NUM. The other bits among the 64 are
620 *       fixed at 1 by hardware.
621 */
622extern void flashc_set_gp_fuse_bit(unsigned int gp_fuse_bit, Bool value);
623
624/*! \brief Sets a general-purpose fuse bit-field with the appropriate erase and
625 *         write operations.
626 *
627 * \param pos The bit-position of the general-purpose fuse bit-field: \c 0 to
628 *            \c 63.
629 * \param width The bit-width of the general-purpose fuse bit-field: \c 0 to
630 *              \c 64.
631 * \param value The value of the specified general-purpose fuse bit-field.
632 *
633 * \warning A Lock Error is issued if the Security bit is active and the command
634 *          is applied to BOOTPROT or EPFL fuses.
635 *
636 * \note The FLASHC error status returned by \ref flashc_is_lock_error and
637 *       \ref flashc_is_programming_error is updated.
638 *
639 * \note The actual number of general-purpose fuse bits implemented by hardware
640 *       is given by \c AVR32_FLASHC_GPF_NUM. The other bits among the 64 are
641 *       fixed at 1 by hardware.
642 */
643extern void flashc_set_gp_fuse_bitfield(unsigned int pos, unsigned int width, U64 value);
644
645/*! \brief Sets a general-purpose fuse byte with the appropriate erase and write
646 *         operations.
647 *
648 * \param gp_fuse_byte The general-purpose fuse byte: \c 0 to \c 7.
649 * \param value The value of the specified general-purpose fuse byte.
650 *
651 * \warning A Lock Error is issued if the Security bit is active.
652 *
653 * \note The FLASHC error status returned by \ref flashc_is_lock_error and
654 *       \ref flashc_is_programming_error is updated.
655 *
656 * \note The actual number of general-purpose fuse bits implemented by hardware
657 *       is given by \c AVR32_FLASHC_GPF_NUM. The other bits among the 64 are
658 *       fixed at 1 by hardware.
659 */
660extern void flashc_set_gp_fuse_byte(unsigned int gp_fuse_byte, U8 value);
661
662/*! \brief Sets all general-purpose fuses with the appropriate erase and write
663 *         operations.
664 *
665 * \param value The value of all general-purpose fuses as a word.
666 *
667 * \warning A Lock Error is issued if the Security bit is active.
668 *
669 * \note The FLASHC error status returned by \ref flashc_is_lock_error and
670 *       \ref flashc_is_programming_error is updated.
671 *
672 * \note The actual number of general-purpose fuse bits implemented by hardware
673 *       is given by \c AVR32_FLASHC_GPF_NUM. The other bits among the 64 are
674 *       fixed at 1 by hardware.
675 */
676extern void flashc_set_all_gp_fuses(U64 value);
677
678//! @}
679
680
681/*! \name Access to Flash Pages
682 */
683//! @{
684
685/*! \brief Clears the page buffer.
686 *
687 * This command resets all bits in the page buffer to one. Write accesses to the
688 * page buffer can only change page buffer bits from one to zero.
689 *
690 * \warning The page buffer is not automatically reset after a page write.
691 *
692 * \note The FLASHC error status returned by \ref flashc_is_lock_error and
693 *       \ref flashc_is_programming_error is updated.
694 */
695extern void flashc_clear_page_buffer(void);
696
697/*! \brief Tells whether the page to which the last Quick Page Read or Quick
698 *         Page Read User Page command was applied was erased.
699 *
700 * \return Whether the page to which the last Quick Page Read or Quick Page Read
701 *         User Page command was applied was erased.
702 */
703extern Bool flashc_is_page_erased(void);
704
705/*! \brief Applies the Quick Page Read command to a page.
706 *
707 * \param page_number The page number:
708 *   \arg \c 0 to <tt>(flashc_get_page_count() - 1)</tt>: a page number within
709 *        the flash array;
710 *   \arg <tt>< 0</tt>: the current page number.
711 *
712 * \return Whether the specified page is erased.
713 *
714 * \note The FLASHC error status returned by \ref flashc_is_lock_error and
715 *       \ref flashc_is_programming_error is updated.
716 */
717extern Bool flashc_quick_page_read(int page_number);
718
719/*! \brief Erases a page.
720 *
721 * \param page_number The page number:
722 *   \arg \c 0 to <tt>(flashc_get_page_count() - 1)</tt>: a page number within
723 *        the flash array;
724 *   \arg <tt>< 0</tt>: the current page number.
725 * \param check Whether to check erase: \c TRUE or \c FALSE.
726 *
727 * \return Whether the erase succeeded or always \c TRUE if erase check was not
728 *         requested.
729 *
730 * \warning A Lock Error is issued if the command is applied to a page belonging
731 *          to a locked region or to the bootloader protected area.
732 *
733 * \note The FLASHC error status returned by \ref flashc_is_lock_error and
734 *       \ref flashc_is_programming_error is updated.
735 *
736 * \note An erase operation can only set bits.
737 */
738extern Bool flashc_erase_page(int page_number, Bool check);
739
740/*! \brief Erases all pages within the flash array.
741 *
742 * \param check Whether to check erase: \c TRUE or \c FALSE.
743 *
744 * \return Whether the erase succeeded or always \c TRUE if erase check was not
745 *         requested.
746 *
747 * \warning A Lock Error is issued if at least one region is locked or the
748 *          bootloader protection is active.
749 *
750 * \note The FLASHC error status returned by \ref flashc_is_lock_error and
751 *       \ref flashc_is_programming_error is updated.
752 *
753 * \note An erase operation can only set bits.
754 */
755extern Bool flashc_erase_all_pages(Bool check);
756
757/*! \brief Writes a page from the page buffer.
758 *
759 * \param page_number The page number:
760 *   \arg \c 0 to <tt>(flashc_get_page_count() - 1)</tt>: a page number within
761 *        the flash array;
762 *   \arg <tt>< 0</tt>: the current page number.
763 *
764 * \warning A Lock Error is issued if the command is applied to a page belonging
765 *          to a locked region or to the bootloader protected area.
766 *
767 * \warning The page buffer is not automatically reset after a page write.
768 *
769 * \note The FLASHC error status returned by \ref flashc_is_lock_error and
770 *       \ref flashc_is_programming_error is updated.
771 *
772 * \note A write operation can only clear bits.
773 */
774extern void flashc_write_page(int page_number);
775
776/*! \brief Issues a Quick Page Read User Page command to the FLASHC.
777 *
778 * \return Whether the User page is erased.
779 *
780 * \note The FLASHC error status returned by \ref flashc_is_lock_error and
781 *       \ref flashc_is_programming_error is updated.
782 */
783extern Bool flashc_quick_user_page_read(void);
784
785/*! \brief Erases the User page.
786 *
787 * \param check Whether to check erase: \c TRUE or \c FALSE.
788 *
789 * \return Whether the erase succeeded or always \c TRUE if erase check was not
790 *         requested.
791 *
792 * \note The FLASHC error status returned by \ref flashc_is_lock_error and
793 *       \ref flashc_is_programming_error is updated.
794 *
795 * \note An erase operation can only set bits.
796 */
797extern Bool flashc_erase_user_page(Bool check);
798
799/*! \brief Writes the User page from the page buffer.
800 *
801 * \warning The page buffer is not automatically reset after a page write.
802 *
803 * \note The FLASHC error status returned by \ref flashc_is_lock_error and
804 *       \ref flashc_is_programming_error is updated.
805 *
806 * \note A write operation can only clear bits.
807 */
808extern void flashc_write_user_page(void);
809
810/*! \brief Copies \a nbytes bytes to the flash destination pointed to by \a dst
811 *         from the repeated \a src source byte.
812 *
813 * The destination areas that are not within the flash array or the User page
814 * are ignored.
815 *
816 * All pointer and size alignments are supported.
817 *
818 * \param dst Pointer to flash destination.
819 * \param src Source byte.
820 * \param nbytes Number of bytes to set.
821 * \param erase Whether to erase before writing: \c TRUE or \c FALSE.
822 *
823 * \return The value of \a dst.
824 *
825 * \warning This function may be called with \a erase set to \c FALSE only if
826 *          the destination consists only of erased words, i.e. this function
827 *          can not be used to write only one bit of a previously written word.
828 *          E.g., if \c 0x00000001 then \c 0xFFFFFFFE are written to a word, the
829 *          resulting value in flash may be different from \c 0x00000000.
830 *
831 * \warning A Lock Error is issued if the command is applied to pages belonging
832 *          to a locked region or to the bootloader protected area.
833 *
834 * \note The FLASHC error status returned by \ref flashc_is_lock_error and
835 *       \ref flashc_is_programming_error is updated.
836 */
837extern volatile void *flashc_memset8(volatile void *dst, U8 src, size_t nbytes, Bool erase);
838
839/*! \brief Copies \a nbytes bytes to the flash destination pointed to by \a dst
840 *         from the repeated \a src big-endian source half-word.
841 *
842 * The destination areas that are not within the flash array or the User page
843 * are ignored.
844 *
845 * All pointer and size alignments are supported.
846 *
847 * \param dst Pointer to flash destination.
848 * \param src Source half-word.
849 * \param nbytes Number of bytes to set.
850 * \param erase Whether to erase before writing: \c TRUE or \c FALSE.
851 *
852 * \return The value of \a dst.
853 *
854 * \warning This function may be called with \a erase set to \c FALSE only if
855 *          the destination consists only of erased words, i.e. this function
856 *          can not be used to write only one bit of a previously written word.
857 *          E.g., if \c 0x00000001 then \c 0xFFFFFFFE are written to a word, the
858 *          resulting value in flash may be different from \c 0x00000000.
859 *
860 * \warning A Lock Error is issued if the command is applied to pages belonging
861 *          to a locked region or to the bootloader protected area.
862 *
863 * \note The FLASHC error status returned by \ref flashc_is_lock_error and
864 *       \ref flashc_is_programming_error is updated.
865 */
866extern volatile void *flashc_memset16(volatile void *dst, U16 src, size_t nbytes, Bool erase);
867
868/*! \brief Copies \a nbytes bytes to the flash destination pointed to by \a dst
869 *         from the repeated \a src big-endian source word.
870 *
871 * The destination areas that are not within the flash array or the User page
872 * are ignored.
873 *
874 * All pointer and size alignments are supported.
875 *
876 * \param dst Pointer to flash destination.
877 * \param src Source word.
878 * \param nbytes Number of bytes to set.
879 * \param erase Whether to erase before writing: \c TRUE or \c FALSE.
880 *
881 * \return The value of \a dst.
882 *
883 * \warning This function may be called with \a erase set to \c FALSE only if
884 *          the destination consists only of erased words, i.e. this function
885 *          can not be used to write only one bit of a previously written word.
886 *          E.g., if \c 0x00000001 then \c 0xFFFFFFFE are written to a word, the
887 *          resulting value in flash may be different from \c 0x00000000.
888 *
889 * \warning A Lock Error is issued if the command is applied to pages belonging
890 *          to a locked region or to the bootloader protected area.
891 *
892 * \note The FLASHC error status returned by \ref flashc_is_lock_error and
893 *       \ref flashc_is_programming_error is updated.
894 */
895extern volatile void *flashc_memset32(volatile void *dst, U32 src, size_t nbytes, Bool erase);
896
897/*! \brief Copies \a nbytes bytes to the flash destination pointed to by \a dst
898 *         from the repeated \a src big-endian source double-word.
899 *
900 * The destination areas that are not within the flash array or the User page
901 * are ignored.
902 *
903 * All pointer and size alignments are supported.
904 *
905 * \param dst Pointer to flash destination.
906 * \param src Source double-word.
907 * \param nbytes Number of bytes to set.
908 * \param erase Whether to erase before writing: \c TRUE or \c FALSE.
909 *
910 * \return The value of \a dst.
911 *
912 * \warning This function may be called with \a erase set to \c FALSE only if
913 *          the destination consists only of erased words, i.e. this function
914 *          can not be used to write only one bit of a previously written word.
915 *          E.g., if \c 0x00000001 then \c 0xFFFFFFFE are written to a word, the
916 *          resulting value in flash may be different from \c 0x00000000.
917 *
918 * \warning A Lock Error is issued if the command is applied to pages belonging
919 *          to a locked region or to the bootloader protected area.
920 *
921 * \note The FLASHC error status returned by \ref flashc_is_lock_error and
922 *       \ref flashc_is_programming_error is updated.
923 */
924extern volatile void *flashc_memset64(volatile void *dst, U64 src, size_t nbytes, Bool erase);
925
926/*! \brief Copies \a nbytes bytes to the flash destination pointed to by \a dst
927 *         from the repeated \a src big-endian source pattern.
928 *
929 * The destination areas that are not within the flash array or the User page
930 * are ignored.
931 *
932 * All pointer and size alignments are supported.
933 *
934 * \param dst Pointer to flash destination.
935 * \param src Source double-word.
936 * \param src_width \a src width in bits: 8, 16, 32 or 64.
937 * \param nbytes Number of bytes to set.
938 * \param erase Whether to erase before writing: \c TRUE or \c FALSE.
939 *
940 * \return The value of \a dst.
941 *
942 * \warning This function may be called with \a erase set to \c FALSE only if
943 *          the destination consists only of erased words, i.e. this function
944 *          can not be used to write only one bit of a previously written word.
945 *          E.g., if \c 0x00000001 then \c 0xFFFFFFFE are written to a word, the
946 *          resulting value in flash may be different from \c 0x00000000.
947 *
948 * \warning A Lock Error is issued if the command is applied to pages belonging
949 *          to a locked region or to the bootloader protected area.
950 *
951 * \note The FLASHC error status returned by \ref flashc_is_lock_error and
952 *       \ref flashc_is_programming_error is updated.
953 */
954#define flashc_memset(dst, src, src_width, nbytes, erase) \
955          TPASTE2(flashc_memset, src_width)((dst), (src), (nbytes), (erase))
956
957/*! \brief Copies \a nbytes bytes to the flash destination pointed to by \a dst
958 *         from the source pointed to by \a src.
959 *
960 * The destination areas that are not within the flash array or the User page
961 * are ignored.
962 *
963 * All pointer and size alignments are supported.
964 *
965 * \param dst Pointer to flash destination.
966 * \param src Pointer to source data.
967 * \param nbytes Number of bytes to copy.
968 * \param erase Whether to erase before writing: \c TRUE or \c FALSE.
969 *
970 * \return The value of \a dst.
971 *
972 * \warning If copying takes place between areas that overlap, the behavior is
973 *          undefined.
974 *
975 * \warning This function may be called with \a erase set to \c FALSE only if
976 *          the destination consists only of erased words, i.e. this function
977 *          can not be used to write only one bit of a previously written word.
978 *          E.g., if \c 0x00000001 then \c 0xFFFFFFFE are written to a word, the
979 *          resulting value in flash may be different from \c 0x00000000.
980 *
981 * \warning A Lock Error is issued if the command is applied to pages belonging
982 *          to a locked region or to the bootloader protected area.
983 *
984 * \note The FLASHC error status returned by \ref flashc_is_lock_error and
985 *       \ref flashc_is_programming_error is updated.
986 */
987extern volatile void *flashc_memcpy(volatile void *dst, const void *src, size_t nbytes, Bool erase);
988
989#if UC3C
990
991/*! \brief Depednding to the CPU frequency, set the wait states of flash read
992 *         accesses and enable or disable the High speed read mode.
993 *
994 * \param cpu_f_hz The CPU frequency
995 */
996void flashc_set_flash_waitstate_and_readmode(unsigned long cpu_f_hz);
997#endif // UC3C device-specific implementation
998
999//! @}
1000
1001
1002#endif  // _FLASHC_H_
Note: See TracBrowser for help on using the repository browser.