flashc.h

FreeRTOS is a portable, open source, mini Real Time Kernel - a free to download and royalty free RTO

/*! \brief Sets the bootloader protected size.
 *
 * \param bootprot_size The wanted bootloader protected size in bytes. If this
 *                      size is not supported, the actual size will be the
 *                      nearest greater available size or the maximal possible
 *                      size if the requested size is too large.
 *
 * \return The actual bootloader protected size in bytes.
 *
 * \warning A Lock Error is issued if the Security bit is active.
 *
 * \note The FLASHC error status returned by \ref flashc_is_lock_error and
 *       \ref flashc_is_programming_error is updated.
 */
extern unsigned int flashc_set_bootloader_protected_size(unsigned int bootprot_size);

/*! \brief Tells whether external privileged fetch is locked.
 *
 * \return Whether external privileged fetch is locked.
 */
extern Bool flashc_is_external_privileged_fetch_locked(void);

/*! \brief Locks or unlocks external privileged fetch.
 *
 * \param lock Whether to lock external privileged fetch: \c TRUE or \c FALSE.
 *
 * \warning A Lock Error is issued if the Security bit is active.
 *
 * \note The FLASHC error status returned by \ref flashc_is_lock_error and
 *       \ref flashc_is_programming_error is updated.
 */
extern void flashc_lock_external_privileged_fetch(Bool lock);

/*! \brief Tells whether the region of a page is locked.
 *
 * \param page_number The page number:
 *   \arg \c 0 to <tt>(flashc_get_page_count() - 1)</tt>: a page number within
 *        the flash array;
 *   \arg <tt>< 0</tt>: the current page number.
 *
 * \return Whether the region of the specified page is locked.
 */
extern Bool flashc_is_page_region_locked(int page_number);

/*! \brief Tells whether a region is locked.
 *
 * \param region The region number: \c 0 to <tt>(AVR32_FLASHC_REGIONS - 1)</tt>.
 *
 * \return Whether the specified region is locked.
 */
extern Bool flashc_is_region_locked(unsigned int region);

/*! \brief Locks or unlocks the region of a page.
 *
 * \param page_number The page number:
 *   \arg \c 0 to <tt>(flashc_get_page_count() - 1)</tt>: a page number within
 *        the flash array;
 *   \arg <tt>< 0</tt>: the current page number.
 * \param lock Whether to lock the region of the specified page: \c TRUE or
 *             \c FALSE.
 *
 * \note The FLASHC error status returned by \ref flashc_is_lock_error and
 *       \ref flashc_is_programming_error is updated.
 */
extern void flashc_lock_page_region(int page_number, Bool lock);

/*! \brief Locks or unlocks a region.
 *
 * \param region The region number: \c 0 to <tt>(AVR32_FLASHC_REGIONS - 1)</tt>.
 * \param lock Whether to lock the specified region: \c TRUE or \c FALSE.
 *
 * \note The FLASHC error status returned by \ref flashc_is_lock_error and
 *       \ref flashc_is_programming_error is updated.
 */
extern void flashc_lock_region(unsigned int region, Bool lock);

/*! \brief Locks or unlocks all regions.
 *
 * \param lock Whether to lock the regions: \c TRUE or \c FALSE.
 *
 * \note The FLASHC error status returned by \ref flashc_is_lock_error and
 *       \ref flashc_is_programming_error is updated.
 */
extern void flashc_lock_all_regions(Bool lock);

//! @}


/*! \name Access to General-Purpose Fuses
 */
//! @{

/*! \brief Reads a general-purpose fuse bit.
 *
 * \param gp_fuse_bit The general-purpose fuse bit: \c 0 to \c 31.
 *
 * \return The value of the specified general-purpose fuse bit.
 */
extern Bool flashc_read_gp_fuse_bit(unsigned int gp_fuse_bit);

/*! \brief Reads a general-purpose fuse bit-field.
 *
 * \param pos The bit-position of the general-purpose fuse bit-field: \c 0 to
 *            \c 31.
 * \param width The bit-width of the general-purpose fuse bit-field: \c 0 to
 *              \c 32.
 *
 * \return The value of the specified general-purpose fuse bit-field.
 */
extern U32 flashc_read_gp_fuse_bitfield(unsigned int pos, unsigned int width);

/*! \brief Reads a general-purpose fuse byte.
 *
 * \param gp_fuse_byte The general-purpose fuse byte: \c 0 to \c 3.
 *
 * \return The value of the specified general-purpose fuse byte.
 */
extern U8 flashc_read_gp_fuse_byte(unsigned int gp_fuse_byte);

/*! \brief Reads all general-purpose fuses.
 *
 * \return The value of all general-purpose fuses as a word.
 */
extern U32 flashc_read_all_gp_fuses(void);

/*! \brief Erases a general-purpose fuse bit.
 *
 * \param gp_fuse_bit The general-purpose fuse bit: \c 0 to \c 31.
 * \param check Whether to check erase: \c TRUE or \c FALSE.
 *
 * \return Whether the erase succeeded or always \c TRUE if erase check was not
 *         requested.
 *
 * \warning A Lock Error is issued if the Security bit is active and the command
 *          is applied to BOOTPROT or EPFL fuses.
 *
 * \note The FLASHC error status returned by \ref flashc_is_lock_error and
 *       \ref flashc_is_programming_error is updated.
 *
 * \note An erase operation can only set bits.
 */
extern Bool flashc_erase_gp_fuse_bit(unsigned int gp_fuse_bit, Bool check);

/*! \brief Erases a general-purpose fuse bit-field.
 *
 * \param pos The bit-position of the general-purpose fuse bit-field: \c 0 to
 *            \c 31.
 * \param width The bit-width of the general-purpose fuse bit-field: \c 0 to
 *              \c 32.
 * \param check Whether to check erase: \c TRUE or \c FALSE.
 *
 * \return Whether the erase succeeded or always \c TRUE if erase check was not
 *         requested.
 *
 * \warning A Lock Error is issued if the Security bit is active and the command
 *          is applied to BOOTPROT or EPFL fuses.
 *
 * \note The FLASHC error status returned by \ref flashc_is_lock_error and
 *       \ref flashc_is_programming_error is updated.
 *
 * \note An erase operation can only set bits.
 */
extern Bool flashc_erase_gp_fuse_bitfield(unsigned int pos, unsigned int width, Bool check);

/*! \brief Erases a general-purpose fuse byte.
 *
 * \param gp_fuse_byte The general-purpose fuse byte: \c 0 to \c 3.
 * \param check Whether to check erase: \c TRUE or \c FALSE.
 *
 * \return Whether the erase succeeded or always \c TRUE if erase check was not
 *         requested.
 *
 * \warning A Lock Error is issued if the Security bit is active.
 *
 * \note The FLASHC error status returned by \ref flashc_is_lock_error and
 *       \ref flashc_is_programming_error is updated.
 *
 * \note An erase operation can only set bits.
 */
extern Bool flashc_erase_gp_fuse_byte(unsigned int gp_fuse_byte, Bool check);

/*! \brief Erases all general-purpose fuses.
 *
 * \param check Whether to check erase: \c TRUE or \c FALSE.
 *
 * \return Whether the erase succeeded or always \c TRUE if erase check was not
 *         requested.
 *
 * \warning A Lock Error is issued if the Security bit is active.
 *
 * \note The FLASHC error status returned by \ref flashc_is_lock_error and
 *       \ref flashc_is_programming_error is updated.
 *
 * \note An erase operation can only set bits.
 */
extern Bool flashc_erase_all_gp_fuses(Bool check);

/*! \brief Writes a general-purpose fuse bit.
 *
 * \param gp_fuse_bit The general-purpose fuse bit: \c 0 to \c 31.
 * \param value The value of the specified general-purpose fuse bit.
 *
 * \warning A Lock Error is issued if the Security bit is active and the command
 *          is applied to BOOTPROT or EPFL fuses.
 *
 * \note The FLASHC error status returned by \ref flashc_is_lock_error and
 *       \ref flashc_is_programming_error is updated.
 *
 * \note A write operation can only clear bits.
 */
extern void flashc_write_gp_fuse_bit(unsigned int gp_fuse_bit, Bool value);

/*! \brief Writes a general-purpose fuse bit-field.
 *
 * \param pos The bit-position of the general-purpose fuse bit-field: \c 0 to
 *            \c 31.
 * \param width The bit-width of the general-purpose fuse bit-field: \c 0 to
 *              \c 32.
 * \param value The value of the specified general-purpose fuse bit-field.
 *
 * \warning A Lock Error is issued if the Security bit is active and the command
 *          is applied to BOOTPROT or EPFL fuses.
 *
 * \note The FLASHC error status returned by \ref flashc_is_lock_error and
 *       \ref flashc_is_programming_error is updated.
 *
 * \note A write operation can only clear bits.
 */
extern void flashc_write_gp_fuse_bitfield(unsigned int pos, unsigned int width, U32 value);

/*! \brief Writes a general-purpose fuse byte.
 *
 * \param gp_fuse_byte The general-purpose fuse byte: \c 0 to \c 3.
 * \param value The value of the specified general-purpose fuse byte.
 *
 * \warning A Lock Error is issued if the Security bit is active.
 *
 * \note The FLASHC error status returned by \ref flashc_is_lock_error and
 *       \ref flashc_is_programming_error is updated.
 *
 * \note A write operation can only clear bits.
 */
extern void flashc_write_gp_fuse_byte(unsigned int gp_fuse_byte, U8 value);

/*! \brief Writes all general-purpose fuses.
 *
 * \param value The value of all general-purpose fuses as a word.
 *
 * \warning A Lock Error is issued if the Security bit is active.
 *
 * \note The FLASHC error status returned by \ref flashc_is_lock_error and
 *       \ref flashc_is_programming_error is updated.
 *
 * \note A write operation can only clear bits.
 */
extern void flashc_write_all_gp_fuses(U32 value);

/*! \brief Sets a general-purpose fuse bit with the appropriate erase and write
 *         operations.
 *
 * \param gp_fuse_bit The general-purpose fuse bit: \c 0 to \c 31.
 * \param value The value of the specified general-purpose fuse bit.
 *
 * \warning A Lock Error is issued if the Security bit is active and the command
 *          is applied to BOOTPROT or EPFL fuses.
 *
 * \note The FLASHC error status returned by \ref flashc_is_lock_error and
 *       \ref flashc_is_programming_error is updated.
 */
extern void flashc_set_gp_fuse_bit(unsigned int gp_fuse_bit, Bool value);

/*! \brief Sets a general-purpose fuse bit-field with the appropriate erase and
 *         write operations.
 *
 * \param pos The bit-position of the general-purpose fuse bit-field: \c 0 to
 *            \c 31.
 * \param width The bit-width of the general-purpose fuse bit-field: \c 0 to
 *              \c 32.
 * \param value The value of the specified general-purpose fuse bit-field.
 *
 * \warning A Lock Error is issued if the Security bit is active and the command
 *          is applied to BOOTPROT or EPFL fuses.
 *
 * \note The FLASHC error status returned by \ref flashc_is_lock_error and
 *       \ref flashc_is_programming_error is updated.
 */
extern void flashc_set_gp_fuse_bitfield(unsigned int pos, unsigned int width, U32 value);

/*! \brief Sets a general-purpose fuse byte with the appropriate erase and write
 *         operations.
 *
 * \param gp_fuse_byte The general-purpose fuse byte: \c 0 to \c 3.
 * \param value The value of the specified general-purpose fuse byte.
 *
 * \warning A Lock Error is issued if the Security bit is active.
 *