git.sur5r.net Git - freertos/blob - Demo/lwIP_AVR32_UC3/DRIVERS/FLASHC/flashc.h

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