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