git.sur5r.net Git - freertos/blob - FreeRTOS/Demo/CORTEX_M4_ATSAM4L_Atmel_Studio/src/asf/sam/drivers/flashcalw/flashcalw.h

   1 /**\r
   2  * \file\r
   3  *\r
   4  * \brief FlashCALW driver for SAM4L.\r
   5  *\r
   6  * Copyright (c) 2012-2013 Atmel Corporation. All rights reserved.\r
   7  *\r
   8  * \asf_license_start\r
   9  *\r
  10  * \page License\r
  11  *\r
  12  * Redistribution and use in source and binary forms, with or without\r
  13  * modification, are permitted provided that the following conditions are met:\r
  14  *\r
  15  * 1. Redistributions of source code must retain the above copyright notice,\r
  16  *    this list of conditions and the following disclaimer.\r
  17  *\r
  18  * 2. Redistributions in binary form must reproduce the above copyright notice,\r
  19  *    this list of conditions and the following disclaimer in the documentation\r
  20  *    and/or other materials provided with the distribution.\r
  21  *\r
  22  * 3. The name of Atmel may not be used to endorse or promote products derived\r
  23  *    from this software without specific prior written permission.\r
  24  *\r
  25  * 4. This software may only be redistributed and used in connection with an\r
  26  *    Atmel microcontroller product.\r
  27  *\r
  28  * THIS SOFTWARE IS PROVIDED BY ATMEL "AS IS" AND ANY EXPRESS OR IMPLIED\r
  29  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF\r
  30  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT ARE\r
  31  * EXPRESSLY AND SPECIFICALLY DISCLAIMED. IN NO EVENT SHALL ATMEL BE LIABLE FOR\r
  32  * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL\r
  33  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS\r
  34  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)\r
  35  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,\r
  36  * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN\r
  37  * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE\r
  38  * POSSIBILITY OF SUCH DAMAGE.\r
  39  *\r
  40  * \asf_license_stop\r
  41  *\r
  42  */\r
  43 \r
  44 #ifndef FLASHCALW_H_INCLUDED\r
  45 #define FLASHCALW_H_INCLUDED\r
  46 \r
  47 #include <stddef.h>\r
  48 #include <stdbool.h>\r
  49 #include "compiler.h"\r
  50 \r
  51 /* These defines should be part of the auto-generated header files */\r
  52 #if (!defined FLASH_PAGE_SIZE)\r
  53 #   define FLASH_PAGE_SIZE     512UL\r
  54 #endif\r
  55 #if (!defined FLASH_NB_OF_REGIONS)\r
  56 #   define FLASH_NB_OF_REGIONS 16\r
  57 #endif\r
  58 \r
  59 \r
  60 /* ! Number of flash regions defined by the FLASHCALW. */\r
  61 #define FLASHCALW_REGIONS  FLASH_NB_OF_REGIONS\r
  62 \r
  63 /** \brief Maximum operating frequency when FWS is 1 in PS0 mode and\r
  64  the Fast wakeup is enabled */\r
  65 #define FLASH_FREQ_PS1_FWS_1_FWU_MAX_FREQ    (12000000UL)\r
  66 /** \brief Maximum operating frequency when FWS is 0 in PS0 mode */\r
  67 #define FLASH_FREQ_PS0_FWS_0_MAX_FREQ        (18000000UL)\r
  68 /** \brief Maximum operating frequency when FWS is 1 in PS0 mode */\r
  69 #define FLASH_FREQ_PS0_FWS_1_MAX_FREQ        (36000000UL)\r
  70 /** \brief Maximum operating frequency when FWS is 0 in PS1 mode */\r
  71 #define FLASH_FREQ_PS1_FWS_0_MAX_FREQ        (8000000UL)\r
  72 /** \brief Maximum operating frequency when FWS is 1 in PS1 mode */\r
  73 #define FLASH_FREQ_PS1_FWS_1_MAX_FREQ        (12000000UL)\r
  74 /** \brief Maximum operating frequency when FWS is 0 in PS2 mode */\r
  75 #define FLASH_FREQ_PS2_FWS_0_MAX_FREQ        (24000000UL)\r
  76 /** \brief Maximum operating frequency when FWS is 1 in PS2 mode */\r
  77 #define FLASH_FREQ_PS2_FWS_1_MAX_FREQ        (48000000UL)\r
  78 /*! \name Flash Properties\r
  79  */\r
  80 //! @{\r
  81 \r
  82 uint32_t flashcalw_get_flash_size(void);\r
  83 \r
  84 uint32_t flashcalw_get_page_count(void);\r
  85 \r
  86 uint32_t flashcalw_get_page_count_per_region(void);\r
  87 \r
  88 uint32_t flashcalw_get_page_region(int32_t page_number);\r
  89 \r
  90 uint32_t flashcalw_get_region_first_page_number(uint32_t region);\r
  91 \r
  92 //! @}\r
  93 \r
  94 \r
  95 /*! \name FLASHCALW Control\r
  96  */\r
  97 //! @{\r
  98 \r
  99 uint32_t flashcalw_get_wait_state(void);\r
 100 \r
 101 void flashcalw_set_wait_state(uint32_t wait_state);\r
 102 \r
 103 void flashcalw_set_flash_waitstate_and_readmode(uint32_t cpu_f_hz,\r
 104                 uint32_t ps_value, bool is_fwu_enabled);\r
 105 \r
 106 /*! \brief Alias on the flashcalw_set_flash_waitstate_and_readmode() function.\r
 107  *\r
 108  * \param cpu_f_hz The CPU frequency\r
 109  * \param ps_value (boolean), Power Scaling mode\r
 110  * \param is_fwu_enabled (boolean), Fast wakeup mode\r
 111  */\r
 112 #define flash_set_bus_freq(cpu_f_hz, ps_value, is_fwu_enabled) \\r
 113         flashcalw_set_flash_waitstate_and_readmode(cpu_f_hz, ps_value, is_fwu_enabled)\r
 114 \r
 115 bool flashcalw_is_ready_int_enabled(void);\r
 116 \r
 117 void flashcalw_enable_ready_int(bool enable);\r
 118 \r
 119 bool flashcalw_is_lock_error_int_enabled(void);\r
 120 \r
 121 void flashcalw_enable_lock_error_int(bool enable);\r
 122 \r
 123 bool flashcalw_is_prog_error_int_enabled(void);\r
 124 \r
 125 void flashcalw_enable_prog_error_int(bool enable);\r
 126 \r
 127 //! @}\r
 128 \r
 129 \r
 130 /*! \name FLASHCALW Status\r
 131  */\r
 132 //! @{\r
 133 \r
 134 bool flashcalw_is_ready(void);\r
 135 \r
 136 void flashcalw_default_wait_until_ready(void);\r
 137 \r
 138 extern void (*volatile flashcalw_wait_until_ready)(void);\r
 139 \r
 140 bool flashcalw_is_lock_error(void);\r
 141 \r
 142 bool flashcalw_is_programming_error(void);\r
 143 \r
 144 //! @}\r
 145 \r
 146 \r
 147 /*! \name FLASHCALW Command Control\r
 148  */\r
 149 //! @{\r
 150 \r
 151 uint32_t flashcalw_get_command(void);\r
 152 \r
 153 uint32_t flashcalw_get_page_number(void);\r
 154 \r
 155 void flashcalw_issue_command(uint32_t command, int page_number);\r
 156 \r
 157 //! @}\r
 158 \r
 159 \r
 160 /*! \name FLASHCALW Global Commands\r
 161  */\r
 162 //! @{\r
 163 \r
 164 void flashcalw_no_operation(void);\r
 165 \r
 166 void flashcalw_erase_all(void);\r
 167 \r
 168 //! @}\r
 169 \r
 170 \r
 171 /*! \name FLASHCALW Protection Mechanisms\r
 172  */\r
 173 //! @{\r
 174 \r
 175 bool flashcalw_is_security_bit_active(void);\r
 176 \r
 177 void flashcalw_set_security_bit(void);\r
 178 \r
 179 bool flashcalw_is_page_region_locked(uint32_t page_number);\r
 180 \r
 181 bool flashcalw_is_region_locked(uint32_t region);\r
 182 \r
 183 void flashcalw_lock_page_region(int page_number, bool lock);\r
 184 \r
 185 void flashcalw_lock_region(uint32_t region, bool lock);\r
 186 \r
 187 void flashcalw_lock_all_regions(bool lock);\r
 188 \r
 189 //! @}\r
 190 \r
 191 \r
 192 /*! \name Access to General-Purpose Fuses\r
 193  */\r
 194 //! @{\r
 195 \r
 196 bool flashcalw_read_gp_fuse_bit(uint32_t gp_fuse_bit);\r
 197 \r
 198 uint64_t flashcalw_read_gp_fuse_bitfield(uint32_t pos, uint32_t width);\r
 199 \r
 200 uint8_t flashcalw_read_gp_fuse_byte(uint32_t gp_fuse_byte);\r
 201 \r
 202 uint64_t flashcalw_read_all_gp_fuses(void);\r
 203 \r
 204 bool flashcalw_erase_gp_fuse_bit(uint32_t gp_fuse_bit, bool check);\r
 205 \r
 206 bool flashcalw_erase_gp_fuse_bitfield(uint32_t pos, uint32_t width,\r
 207                 bool check);\r
 208 \r
 209 bool flashcalw_erase_gp_fuse_byte(uint32_t gp_fuse_byte, bool check);\r
 210 \r
 211 bool flashcalw_erase_all_gp_fuses(bool check);\r
 212 \r
 213 void flashcalw_write_gp_fuse_bit(uint32_t gp_fuse_bit, bool value);\r
 214 \r
 215 void flashcalw_write_gp_fuse_bitfield(uint32_t pos, uint32_t width,\r
 216                 uint64_t value);\r
 217 \r
 218 void flashcalw_write_gp_fuse_byte(uint32_t gp_fuse_byte, uint8_t value);\r
 219 \r
 220 void flashcalw_write_all_gp_fuses(uint64_t value);\r
 221 \r
 222 void flashcalw_set_gp_fuse_bit(uint32_t gp_fuse_bit, bool value);\r
 223 \r
 224 void flashcalw_set_gp_fuse_bitfield(uint32_t pos, uint32_t width,\r
 225                 uint64_t value);\r
 226 \r
 227 void flashcalw_set_gp_fuse_byte(uint32_t gp_fuse_byte, uint8_t value);\r
 228 \r
 229 void flashcalw_set_all_gp_fuses(uint64_t value);\r
 230 \r
 231 //! @}\r
 232 \r
 233 \r
 234 /*! \name Access to Flash Pages\r
 235  */\r
 236 //! @{\r
 237 \r
 238 void flashcalw_clear_page_buffer(void);\r
 239 \r
 240 bool flashcalw_is_page_erased(void);\r
 241 \r
 242 bool flashcalw_quick_page_read(int page_number);\r
 243 \r
 244 bool flashcalw_erase_page(int page_number, bool check);\r
 245 \r
 246 bool flashcalw_erase_all_pages(bool check);\r
 247 \r
 248 void flashcalw_write_page(int page_number);\r
 249 \r
 250 bool flashcalw_quick_user_page_read(void);\r
 251 \r
 252 bool flashcalw_erase_user_page(bool check);\r
 253 \r
 254 void flashcalw_write_user_page(void);\r
 255 \r
 256 volatile void *flashcalw_memset8(volatile void *dst, uint8_t src,\r
 257                 size_t nbytes, bool erase);\r
 258 \r
 259 volatile void *flashcalw_memset16(volatile void *dst, uint16_t src,\r
 260                 size_t nbytes, bool erase);\r
 261 \r
 262 volatile void *flashcalw_memset32(volatile void *dst, uint32_t src,\r
 263                 size_t nbytes, bool erase);\r
 264 \r
 265 volatile void *flashcalw_memset64(volatile void *dst, uint64_t src,\r
 266                 size_t nbytes, bool erase);\r
 267 \r
 268 /*! \brief Copies \a nbytes bytes to the flash destination pointed to by \a dst\r
 269  *         from the repeated \a src big-endian source pattern.\r
 270  *\r
 271  * All pointer and size alignments are supported.\r
 272  *\r
 273  * \param dst Pointer to flash destination.\r
 274  * \param src Source double-word.\r
 275  * \param src_width \a src width in bits: 8, 16, 32 or 64.\r
 276  * \param nbytes Number of bytes to set.\r
 277  * \param erase Whether to erase before writing: \c true or \c false.\r
 278  *\r
 279  * \return The value of \a dst.\r
 280  *\r
 281  * \warning This function may be called with \a erase set to \c false only if\r
 282  *          the destination consists only of erased words, i.e. this function\r
 283  *          can not be used to write only one bit of a previously written word.\r
 284  *          E.g., if \c 0x00000001 then \c 0xFFFFFFFE are written to a word, the\r
 285  *          resulting value in flash may be different from \c 0x00000000.\r
 286  *\r
 287  * \warning A Lock Error is issued if the command is applied to pages belonging\r
 288  *          to a locked region or to the bootloader protected area.\r
 289  *\r
 290  * \note The FLASHCALW error status returned by \ref flashcalw_is_lock_error and\r
 291  *       \ref flashcalw_is_programming_error is updated.\r
 292  */\r
 293 #define flashcalw_memset(dst, src, src_width, nbytes, erase) \\r
 294         TPASTE2(flashcalw_memset, src_width) ((dst), (src), (nbytes), (erase))\r
 295 \r
 296 volatile void *flashcalw_memcpy(volatile void *dst, const void *src,\r
 297                 size_t nbytes, bool erase);\r
 298 \r
 299 //! @}\r
 300 \r
 301 /*! \name PicoCache interfaces.\r
 302  */\r
 303 //! @{\r
 304 \r
 305 void flashcalw_picocache_enable(void);\r
 306 \r
 307 void flashcalw_picocache_disable(void);\r
 308 \r
 309 uint32_t flashcalw_picocache_get_status(void);\r
 310 \r
 311 void flashcalw_picocache_invalid_all(void);\r
 312 \r
 313 void flashcalw_picocache_invalid_line(uint32_t index);\r
 314 \r
 315 void flashcalw_picocache_set_monitor_mode(uint32_t mode);\r
 316 \r
 317 void flashcalw_picocache_enable_monitor(void);\r
 318 \r
 319 void flashcalw_picocache_disable_monitor(void);\r
 320 \r
 321 void flashcalw_picocache_reset_monitor( void );\r
 322 \r
 323 uint32_t flashcalw_picocache_get_monitor_cnt( void );\r
 324 \r
 325 uint32_t flashcalw_picocache_get_version( void );\r
 326 \r
 327 //! @}\r
 328 \r
 329 /**\r
 330  * \page sam_flashcalw_quickstart Quickstart guide for SAM FLASHCALW driver\r
 331  *\r
 332  * This is the quickstart guide for the \ref group_sam_drivers_flashcalw\r
 333  * "SAM FLASHCALW driver", with step-by-step instructions on how to\r
 334  * configure and use the driver in a selection of use cases.\r
 335  *\r
 336  * The use cases contain several code fragments. The code fragments in the\r
 337  * steps for setup can be copied into a custom initialization function, while\r
 338  * the steps for usage can be copied into, e.g., the main application function.\r
 339  *\r
 340  * \section flashcalw_basic_use_case Basic use case\r
 341  * In this basic use case, the last page page and the user page will be written\r
 342  * with a specific magic number.\r
 343  *\r
 344  * \subsection sam_flashcalw_quickstart_prereq Prerequisites\r
 345  * -# \ref sysclk_group "System Clock Management (Sysclock)"\r
 346  *\r
 347  * \section flashcalw_basic_use_case_setup Setup steps\r
 348  *  \note The CLK_FLASHCALW_AHB, CLK_FLASHCALW_APB are enabled\r
 349  * by default.\r
 350  * \subsection flashcalw_basic_use_case_setup_code Example code\r
 351  * Enable the following macro in the conf_clock.h:\r
 352  * \code\r
 353  *  #define CONFIG_SYSCLK_SOURCE   SYSCLK_SRC_RCFAST\r
 354  *  #define CONFIG_RCFAST_FRANGE    2\r
 355  * \endcode\r
 356  *\r
 357  * Add the following code in the application C-file:\r
 358  * \code\r
 359  *  sysclk_init();\r
 360  * \endcode\r
 361  *\r
 362  * \subsection flashcalw_basic_use_case_setup_flow Workflow\r
 363  * -# Set system clock source as fast RC oscillator:\r
 364  *   - \code #define CONFIG_SYSCLK_SOURCE SYSCLK_SRC_RCFAST \endcode\r
 365  * -# Set fast RC oscillator as 12MHz:\r
 366  *   - \code #define CONFIG_RCFAST_FRANGE    2 \endcode\r
 367  * -# Initialize the system clock.\r
 368  *   - \code sysclk_init(); \endcode\r
 369  *\r
 370  * \section flashcalw_basic_use_case_usage Usage steps\r
 371  * \subsection flashcalw_basic_use_case_usage_code Example code\r
 372  * Add to, e.g., main loop in application C-file:\r
 373  * \code\r
 374  *    #define MAGIC_NUM 0x4c4d5441\r
 375  *    #define PAGE_ADDRESS (FLASH_ADDR + FLASH_SIZE - FLASH_PAGE_SIZE)\r
 376  *    #define USER_PAGE_ADDRESS (FLASH_USER_PAGE_ADDR + 8)\r
 377  *    static const uint32_t write_data = MAGIC_NUM;\r
 378  *\r
 379  *    flashcalw_memcpy((void *)PAGE_ADDRESS, &write_data, 4, true);\r
 380  *    flashcalw_memcpy((void *)USER_PAGE_ADDRESS, &write_data, 4, true);\r
 381  * \endcode\r
 382  *\r
 383  * \subsection flashcalw_basic_use_case_usage_flow Workflow\r
 384  * -# Define the written locations and magic number:\r
 385  *   - \code #define MAGIC_NUM 0x4c4d5441 \endcode\r
 386  *   - \code #define PAGE_ADDRESS (FLASH_ADDR + FLASH_SIZE - FLASH_PAGE_SIZE)\r
 387  * \endcode\r
 388  *   - \code USER_PAGE_ADDRESS (FLASH_USER_PAGE_ADDR + 8) \endcode\r
 389  *   - \note The storage location must not at the beginning of the user page as the first 2\r
 390  * words of the user page is reserved.\r
 391  *   - \code static const uint32_t write_data = MAGIC_NUM; \endcode\r
 392  * -# Write the magic number to the flash array:\r
 393  *   - \code flashcalw_memcpy((void *)PAGE_ADDRESS, &write_data, 4, true); \endcode\r
 394  * -# Write the magic number to the user page:\r
 395  *   - \code flashcalw_memcpy((void *)USER_PAGE_ADDRESS, &write_data, 4, true);\r
 396  * \endcode\r
 397  *\r
 398  */\r
 399 #endif  /* FLASHCALW_H_INCLUDED */\r