See Quickstart guide for SAM FLASHCALW driver.

FLASHCALW interfaces a flash block with the 32-bit internal HSB bus.

Modules
	Related Project(s)
	In this section you can find all the projects related to the FLASHCALW - FLASH Controller Double-Word.

	Quick Start Guide(s)
	In this section you can find a list of all Quick Start guides related to the FLASHCALW - FLASH Controller Double-Word.

Flash Properties
uint32_t	flashcalw_get_flash_size (void)
	Gets the size of the whole flash array. More...

uint32_t	flashcalw_get_page_count (void)
	Gets the total number of pages in the flash array. More...

uint32_t	flashcalw_get_page_count_per_region (void)
	Gets the number of pages in each flash region. More...

uint32_t	flashcalw_get_page_region (int32_t page_number)
	Gets the region number of a page. More...

uint32_t	flashcalw_get_region_first_page_number (uint32_t region)
	Gets the number of the first page of a region. More...

FLASHC Control
uint32_t	flashcalw_get_wait_state (void)
	Gets the number of wait states of flash read accesses. More...

void	flashcalw_set_wait_state (uint32_t wait_state)
	Sets the number of wait states of flash read accesses. More...

void	flashcalw_set_flash_waitstate_and_readmode (uint32_t cpu_f_hz, uint32_t ps_value, bool is_fwu_enabled)
	Depending on the CPU frequency, on the Power Scaling mode and on the Fast Wakeup mode, set the wait states of flash read accesses and enable or disable the High speed read mode. More...

bool	flashcalw_is_ready_int_enabled (void)
	Tells whether the Flash Ready interrupt is enabled. More...

void	flashcalw_enable_ready_int (bool enable)
	Enables or disables the Flash Ready interrupt. More...

bool	flashcalw_is_lock_error_int_enabled (void)
	Tells whether the Lock Error interrupt is enabled. More...

void	flashcalw_enable_lock_error_int (bool enable)
	Enables or disables the Lock Error interrupt. More...

bool	flashcalw_is_prog_error_int_enabled (void)
	Tells whether the Programming Error interrupt is enabled. More...

void	flashcalw_enable_prog_error_int (bool enable)
	Enables or disables the Programming Error interrupt. More...

#define	FLASH_FWS_0_MAX_FREQ CHIP_FREQ_FWS_0

#define	FLASH_FWS_1_MAX_FREQ CHIP_FREQ_FWS_1

#define	FLASH_HSEN_FWS_0_MAX_FREQ CHIP_FREQ_FLASH_HSEN_FWS_0

#define	FLASH_HSEN_FWS_1_MAX_FREQ CHIP_FREQ_FLASH_HSEN_FWS_1

FLASHCALW Status
void(*volatile	flashcalw_wait_until_ready )(void) = flashcalw_default_wait_until_ready
	Pointer to the function used by the driver when it needs to wait until the FLASHCALW is ready to run a new command. More...

static uint32_t	flashcalw_error_status = 0
	Sticky error status of the FLASHCALW. More...

bool	flashcalw_is_ready (void)
	Tells whether the FLASHCALW is ready to run a new command. More...

void	flashcalw_default_wait_until_ready (void)
	Waits actively until the FLASHCALW is ready to run a new command. More...

static uint32_t	flashcalw_get_error_status (void)
	Gets the error status of the FLASHCALW. More...

bool	flashcalw_is_lock_error (void)
	Tells whether a Lock Error has occurred during the last function called that issued one or more FLASHCALW commands. More...

bool	flashcalw_is_programming_error (void)
	Tells whether a Programming Error has occurred during the last function called that issued one or more FLASHCALW commands. More...

FLASHCALW Command Control
uint32_t	flashcalw_get_command (void)
	Gets the last issued FLASHCALW command. More...

uint32_t	flashcalw_get_page_number (void)
	Gets the current FLASHCALW page number. More...

void	flashcalw_issue_command (uint32_t command, int page_number)
	Issues a FLASHCALW command. More...

FLASHCALW Global Commands
void	flashcalw_no_operation (void)
	Issues a No Operation command to the FLASHCALW. More...

void	flashcalw_erase_all (void)
	Issues an Erase All command to the FLASHCALW. More...

FLASHCALW Protection Mechanisms
bool	flashcalw_is_security_bit_active (void)
	Tells whether the Security bit is active. More...

void	flashcalw_set_security_bit (void)
	Activates the Security bit. More...

bool	flashcalw_is_page_region_locked (uint32_t page_number)
	Tells whether the region of a page is locked. More...

bool	flashcalw_is_region_locked (uint32_t region)
	Tells whether a region is locked. More...

void	flashcalw_lock_page_region (int page_number, bool lock)
	Locks or unlocks the region of a page. More...

void	flashcalw_lock_region (uint32_t region, bool lock)
	Locks or unlocks a region. More...

void	flashcalw_lock_all_regions (bool lock)
	Locks or unlocks all regions. More...

Access to General-Purpose Fuses
bool	flashcalw_read_gp_fuse_bit (uint32_t gp_fuse_bit)
	Reads a general-purpose fuse bit. More...

uint64_t	flashcalw_read_gp_fuse_bitfield (uint32_t pos, uint32_t width)
	Reads a general-purpose fuse bit-field. More...

uint8_t	flashcalw_read_gp_fuse_byte (uint32_t gp_fuse_byte)
	Reads a general-purpose fuse byte. More...

uint64_t	flashcalw_read_all_gp_fuses (void)
	Reads all general-purpose fuses. More...

bool	flashcalw_erase_gp_fuse_bit (uint32_t gp_fuse_bit, bool check)
	Erases a general-purpose fuse bit. More...

bool	flashcalw_erase_gp_fuse_bitfield (uint32_t pos, uint32_t width, bool check)
	Erases a general-purpose fuse bit-field. More...

bool	flashcalw_erase_gp_fuse_byte (uint32_t gp_fuse_byte, bool check)
	Erases a general-purpose fuse byte. More...

bool	flashcalw_erase_all_gp_fuses (bool check)
	Erases all general-purpose fuses. More...

void	flashcalw_write_gp_fuse_bit (uint32_t gp_fuse_bit, bool value)
	Writes a general-purpose fuse bit. More...

void	flashcalw_write_gp_fuse_bitfield (uint32_t pos, uint32_t width, uint64_t value)
	Writes a general-purpose fuse bit-field. More...

void	flashcalw_write_gp_fuse_byte (uint32_t gp_fuse_byte, uint8_t value)
	Writes a general-purpose fuse byte. More...

void	flashcalw_write_all_gp_fuses (uint64_t value)
	Writes all general-purpose fuses. More...

void	flashcalw_set_gp_fuse_bit (uint32_t gp_fuse_bit, bool value)
	Sets a general-purpose fuse bit with the appropriate erase and write operations. More...

void	flashcalw_set_gp_fuse_bitfield (uint32_t pos, uint32_t width, uint64_t value)
	Sets a general-purpose fuse bit-field with the appropriate erase and write operations. More...

void	flashcalw_set_gp_fuse_byte (uint32_t gp_fuse_byte, uint8_t value)
	Sets a general-purpose fuse byte with the appropriate erase and write operations. More...

void	flashcalw_set_all_gp_fuses (uint64_t value)
	Sets all general-purpose fuses with the appropriate erase and write operations. More...

Access to Flash Pages
void	flashcalw_clear_page_buffer (void)
	Clears the page buffer. More...

bool	flashcalw_is_page_erased (void)
	Tells whether the page to which the last Quick Page Read or Quick Page Read User Page command was applied was erased. More...

bool	flashcalw_quick_page_read (int page_number)
	Applies the Quick Page Read command to a page. More...

bool	flashcalw_erase_page (int page_number, bool check)
	Erases a page. More...

bool	flashcalw_erase_all_pages (bool check)
	Erases all pages within the flash array. More...

void	flashcalw_write_page (int page_number)
	Writes a page from the page buffer. More...

bool	flashcalw_quick_user_page_read (void)
	Issues a Quick Page Read User Page command to the FLASHCALW. More...

bool	flashcalw_erase_user_page (bool check)
	Erases the User page. More...

void	flashcalw_write_user_page (void)
	Writes the User page from the page buffer. More...

volatile void *	flashcalw_memset8 (volatile void *dst, uint8_t src, size_t nbytes, bool erase)
	Copies nbytes bytes to the flash destination pointed to by dst from the repeated src source byte. More...

volatile void *	flashcalw_memset16 (volatile void *dst, uint16_t src, size_t nbytes, bool erase)
	Copies nbytes bytes to the flash destination pointed to by dst from the repeated src big-endian source half-word. More...

volatile void *	flashcalw_memset32 (volatile void *dst, uint32_t src, size_t nbytes, bool erase)
	Copies nbytes bytes to the flash destination pointed to by dst from the repeated src big-endian source word. More...

volatile void *	flashcalw_memset64 (volatile void *dst, uint64_t src, size_t nbytes, bool erase)
	Copies nbytes bytes to the flash destination pointed to by dst from the repeated src big-endian source double-word. More...

volatile void *	flashcalw_memcpy (volatile void dst, const void src, size_t nbytes, bool erase)
	Copies nbytes bytes to the flash destination pointed to by dst from the source pointed to by src. More...

PicoCache interfaces
void	flashcalw_picocache_enable (void)
	Enable PicoCache. More...

void	flashcalw_picocache_disable (void)
	Disable PicoCache. More...

uint32_t	flashcalw_picocache_get_status (void)
	Get PicoCache status. More...

void	flashcalw_picocache_invalid_all (void)
	Invalid all PicoCache lines. More...

void	flashcalw_picocache_invalid_line (uint32_t index)
	Invalid specific cache line. More...

void	flashcalw_picocache_set_monitor_mode (uint32_t mode)
	Set PicoCache monitor mode. More...

void	flashcalw_picocache_enable_monitor (void)
	Enable PicoCache monitor. More...

void	flashcalw_picocache_disable_monitor (void)
	Disable PicoCache monitor. More...

void	flashcalw_picocache_reset_monitor (void)
	Reset PicoCache monitor. More...

uint32_t	flashcalw_picocache_get_monitor_cnt (void)
	Get PicoCache monitor count number. More...

uint32_t	flashcalw_picocache_get_version (void)
	Get PicoCache version. More...

#define FLASH_FWS_0_MAX_FREQ CHIP_FREQ_FWS_0

#define FLASH_FWS_1_MAX_FREQ CHIP_FREQ_FWS_1

#define FLASH_HSEN_FWS_0_MAX_FREQ CHIP_FREQ_FLASH_HSEN_FWS_0

#define FLASH_HSEN_FWS_1_MAX_FREQ CHIP_FREQ_FLASH_HSEN_FWS_1

void flashcalw_clear_page_buffer ( void )

Clears the page buffer.

This command resets all bits in the page buffer to one. Write accesses to the page buffer can only change page buffer bits from one to zero.

Warning: The page buffer is not automatically reset after a page write.

Note: The FLASHCALW error status returned by flashcalw_is_lock_error and flashcalw_is_programming_error is updated.

References flashcalw_issue_command().

Referenced by flashcalw_memcpy(), and flashcalw_memset64().

void flashcalw_default_wait_until_ready ( void )

Waits actively until the FLASHCALW is ready to run a new command.

This is the default function assigned to flashcalw_wait_until_ready.

References flashcalw_is_ready().

void flashcalw_enable_lock_error_int ( bool enable )

Enables or disables the Lock Error interrupt.

Parameters

enable Whether to enable the Lock Error interrupt: true or false.

void flashcalw_enable_prog_error_int ( bool enable )

Enables or disables the Programming Error interrupt.

Parameters

enable Whether to enable the Programming Error interrupt: true or false.

void flashcalw_enable_ready_int ( bool enable )

Enables or disables the Flash Ready interrupt.

Parameters

enable Whether to enable the Flash Ready interrupt: true or false.

void flashcalw_erase_all ( void )

Issues an Erase All command to the FLASHCALW.

This command erases all bits in the flash array, the general-purpose fuse bits and the Security bit. The User page is not erased.

This command also ensures that all volatile memories, such as register file and RAMs, are erased before the Security bit is erased, i.e. deactivated.

Warning: A Lock Error is issued if at least one region is locked or the bootloader protection is active.

Note: The FLASHCALW error status returned by flashcalw_is_lock_error and flashcalw_is_programming_error is updated.; An erase operation can only set bits.

References flashcalw_issue_command().

bool flashcalw_erase_all_gp_fuses ( bool check )

Erases all general-purpose fuses.

Parameters

check Whether to check erase: true or false.

Returns: Whether the erase succeeded or always true if erase check was not requested.

Warning: A Lock Error is issued if the Security bit is active.

Note: The FLASHCALW error status returned by flashcalw_is_lock_error and flashcalw_is_programming_error is updated.; An erase operation can only set bits.; The actual number of general-purpose fuse bits implemented by hardware is given by FLASH_GPF_NUM. The other bits among the 64 are fixed at 1 by hardware.

use (uint64_t)-1 instead of 0xFFFFFFFFFFFFFFFFULL to avoid compilation warning

References flashcalw_issue_command(), and flashcalw_read_all_gp_fuses().

Referenced by flashcalw_erase_gp_fuse_byte(), flashcalw_set_all_gp_fuses(), and run_flashcalw_gp_fuse_test().

bool flashcalw_erase_all_pages ( bool check )

Erases all pages within the flash array.

Parameters

check Whether to check erase: true or false.

Returns: Whether the erase succeeded or always true if erase check was not requested.

Warning: A Lock Error is issued if at least one region is locked or the bootloader protection is active.

Note: The FLASHCALW error status returned by flashcalw_is_lock_error and flashcalw_is_programming_error is updated.; An erase operation can only set bits.

References flashcalw_erase_page(), flashcalw_error_status, and flashcalw_get_page_count().

bool flashcalw_erase_gp_fuse_bit	(	uint32_t	gp_fuse_bit,
		bool	check
	)

Erases a general-purpose fuse bit.

Parameters

gp_fuse_bit	The general-purpose fuse bit: `0` to `63`.
check	Whether to check erase: `true` or `false`.

Returns: Whether the erase succeeded or always 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.

Note: The FLASHCALW error status returned by flashcalw_is_lock_error and flashcalw_is_programming_error is updated.; An erase operation can only set bits.; The actual number of general-purpose fuse bits implemented by hardware is given by FLASH_GPF_NUM. The other bits among the 64 are fixed at 1 by hardware.

References flashcalw_issue_command(), and flashcalw_read_gp_fuse_bit().

Referenced by flashcalw_erase_gp_fuse_bitfield(), flashcalw_set_gp_fuse_bit(), main(), and run_flashcalw_gp_fuse_test().

bool flashcalw_erase_gp_fuse_bitfield	(	uint32_t	pos,
		uint32_t	width,
		bool	check
	)

Erases a general-purpose fuse bit-field.

Parameters

pos	The bit-position of the general-purpose fuse bit-field: `0` to `63`.
width	The bit-width of the general-purpose fuse bit-field: `0` to `64`.
check	Whether to check erase: `true` or `false`.

Returns: Whether the erase succeeded or always 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.

Note: The FLASHCALW error status returned by flashcalw_is_lock_error and flashcalw_is_programming_error is updated.; An erase operation can only set bits.; The actual number of general-purpose fuse bits implemented by hardware is given by FLASH_GPF_NUM. The other bits among the 64 are fixed at 1 by hardware.

References flashcalw_erase_gp_fuse_bit(), flashcalw_error_status, flashcalw_read_gp_fuse_bitfield(), and Min.

Referenced by run_flashcalw_gp_fuse_test().

bool flashcalw_erase_gp_fuse_byte	(	uint32_t	gp_fuse_byte,
		bool	check
	)

Erases a general-purpose fuse byte.

Parameters

gp_fuse_byte	The general-purpose fuse byte: `0` to `7`.
check	Whether to check erase: `true` or `false`.

Returns: Whether the erase succeeded or always true if erase check was not requested.

Warning: A Lock Error is issued if the Security bit is active.

Note: The FLASHCALW error status returned by flashcalw_is_lock_error and flashcalw_is_programming_error is updated.; An erase operation can only set bits.; The actual number of general-purpose fuse bits implemented by hardware is given by FLASH_GPF_NUM. The other bits among the 64 are fixed at 1 by hardware.

References flashcalw_erase_all_gp_fuses(), flashcalw_error_status, flashcalw_read_all_gp_fuses(), flashcalw_read_gp_fuse_byte(), and flashcalw_write_gp_fuse_byte().

Referenced by flashcalw_set_gp_fuse_byte(), and run_flashcalw_gp_fuse_test().

bool flashcalw_erase_page	(	int	page_number,
		bool	check
	)

Erases a page.

Parameters

page_number	The page number: `0` to `(flashcalw_get_page_count() - 1)`: a page number within the flash array; `< 0`: the current page number.
check	Whether to check erase: `true` or `false`.

Returns: Whether the erase succeeded or always true if erase check was not requested.

Warning: A Lock Error is issued if the command is applied to a page belonging to a locked region or to the bootloader protected area.

Note: The FLASHCALW error status returned by flashcalw_is_lock_error and flashcalw_is_programming_error is updated.; An erase operation can only set bits.

References flashcalw_error_status, flashcalw_issue_command(), and flashcalw_quick_page_read().

Referenced by flashcalw_erase_all_pages(), flashcalw_memcpy(), flashcalw_memset64(), and program_memory().

bool flashcalw_erase_user_page ( bool check )

Erases the User page.

Parameters

check Whether to check erase: true or false.

Returns: Whether the erase succeeded or always true if erase check was not requested.

Note: The FLASHCALW error status returned by flashcalw_is_lock_error and flashcalw_is_programming_error is updated.; An erase operation can only set bits.

References flashcalw_issue_command(), and flashcalw_quick_user_page_read().

Referenced by flashcalw_memcpy(), and flashcalw_memset64().

uint32_t flashcalw_get_command ( void )

Gets the last issued FLASHCALW command.

Returns: The last issued FLASHCALW command.

Referenced by run_flashcalw_page_access_test().

static uint32_t flashcalw_get_error_status ( void )

static

Gets the error status of the FLASHCALW.

Returns: The error status of the FLASHCALW built up from FLASHCALW_FSR_LOCKE and FLASHCALW_FSR_PROGE.

Warning: This hardware error status is cleared by all functions reading the Flash Status Register (FSR). This function is therefore not part of the driver's API which instead presents flashcalw_is_lock_error and flashcalw_is_programming_error.

Referenced by flashcalw_issue_command().

uint32_t flashcalw_get_flash_size ( void )

Gets the size of the whole flash array.

Returns: The size of the whole flash array in Bytes.

Referenced by flashcalw_get_page_count(), flashcalw_memcpy(), flashcalw_memset64(), and run_flashcalw_properties_test().

uint32_t flashcalw_get_page_count ( void )

Gets the total number of pages in the flash array.

Returns: The total number of pages in the flash array.

References FLASH_PAGE_SIZE, and flashcalw_get_flash_size().

Referenced by flashcalw_erase_all_pages(), and flashcalw_get_page_count_per_region().

uint32_t flashcalw_get_page_count_per_region ( void )

Gets the number of pages in each flash region.

Returns: The number of pages in each flash region.

References FLASH_NB_OF_REGIONS, and flashcalw_get_page_count().

Referenced by flashcalw_get_page_region(), and flashcalw_get_region_first_page_number().

uint32_t flashcalw_get_page_number ( void )

Gets the current FLASHCALW page number.

Returns: The current FLASHCALW page number.

Referenced by flashcalw_get_page_region().

uint32_t flashcalw_get_page_region ( int32_t page_number )

Gets the region number of a page.

Parameters

page_number

The page number:

0 to (flashcalw_get_page_count() - 1): a page number within the flash array;
< 0: the current page number.

Returns: The region number of the specified page.

References flashcalw_get_page_count_per_region(), and flashcalw_get_page_number().

Referenced by flashcalw_is_page_region_locked(), and run_flashcalw_protection_test().

uint32_t flashcalw_get_region_first_page_number ( uint32_t region )

Gets the number of the first page of a region.

Parameters

region The region number: 0 to (FLASHCALW_REGIONS - 1).

Returns: The number of the first page of the specified region.

References flashcalw_get_page_count_per_region().

Referenced by flashcalw_lock_region().

uint32_t flashcalw_get_wait_state ( void )

Gets the number of wait states of flash read accesses.

Returns: The number of wait states of flash read accesses.

Referenced by run_flashcalw_control_test().

bool flashcalw_is_lock_error ( void )

Tells whether a Lock Error has occurred during the last function called that issued one or more FLASHCALW commands.

Returns: Whether a Lock Error has occurred during the last function called that issued one or more FLASHCALW commands.

Referenced by flash_protect_example(), and program_memory().

bool flashcalw_is_lock_error_int_enabled ( void )

Tells whether the Lock Error interrupt is enabled.

Returns: Whether the Lock Error interrupt is enabled.

bool flashcalw_is_page_erased ( void )

Tells whether the page to which the last Quick Page Read or Quick Page Read User Page command was applied was erased.

Returns: Whether the page to which the last Quick Page Read or Quick Page Read User Page command was applied was erased.

Referenced by flashcalw_quick_page_read(), and flashcalw_quick_user_page_read().

bool flashcalw_is_page_region_locked ( uint32_t page_number )

Tells whether the region of a page is locked.

Parameters

page_number

The page number:

0 to (flashcalw_get_page_count() - 1): a page number within the flash array;
< 0: the current page number.

Returns: Whether the region of the specified page is locked.

References flashcalw_get_page_region(), and flashcalw_is_region_locked().

Referenced by run_flashcalw_protection_test().

bool flashcalw_is_prog_error_int_enabled ( void )

Tells whether the Programming Error interrupt is enabled.

Returns: Whether the Programming Error interrupt is enabled.

bool flashcalw_is_programming_error ( void )

Tells whether a Programming Error has occurred during the last function called that issued one or more FLASHCALW commands.

Returns: Whether a Programming Error has occurred during the last function called that issued one or more FLASHCALW commands.

Referenced by program_memory().

bool flashcalw_is_ready ( void )

Tells whether the FLASHCALW is ready to run a new command.

Returns: Whether the FLASHCALW is ready to run a new command.

Referenced by flashcalw_default_wait_until_ready().

bool flashcalw_is_ready_int_enabled ( void )

Tells whether the Flash Ready interrupt is enabled.

Returns: Whether the Flash Ready interrupt is enabled.

bool flashcalw_is_region_locked ( uint32_t region )

Tells whether a region is locked.

Parameters

region The region number: 0 to (FLASHCALW_REGIONS - 1).

Returns: Whether the specified region is locked.

References FLASHCALW_REGIONS.

Referenced by flashcalw_is_page_region_locked(), and run_flashcalw_protection_test().

bool flashcalw_is_security_bit_active ( void )

Tells whether the Security bit is active.

Returns: Whether the Security bit is active.

Referenced by main().

void flashcalw_issue_command	(	uint32_t	command,
		int	page_number
	)

Issues a FLASHCALW command.

Parameters

command	The command: `FLASHCALW_FCMD_CMD_x`.
page_number	The page number to apply the command to: `0` to `(flashcalw_get_page_count() - 1)`: a page number within the flash array; `< 0`: use this to apply the command to the current page number or if the command does not apply to any page number; this argument may have other meanings according to the command. See the FLASHCALW chapter of the MCU datasheet.

Warning: A Lock Error is issued if the command violates the protection mechanism.; A Programming Error is issued if the command is invalid.

Note: The FLASHCALW error status returned by flashcalw_is_lock_error and flashcalw_is_programming_error is updated.

References flashcalw_get_error_status(), and flashcalw_wait_until_ready.

Referenced by flashcalw_clear_page_buffer(), flashcalw_erase_all(), flashcalw_erase_all_gp_fuses(), flashcalw_erase_gp_fuse_bit(), flashcalw_erase_page(), flashcalw_erase_user_page(), flashcalw_lock_page_region(), flashcalw_no_operation(), flashcalw_quick_page_read(), flashcalw_quick_user_page_read(), flashcalw_set_flash_waitstate_and_readmode(), flashcalw_set_security_bit(), flashcalw_write_gp_fuse_bit(), flashcalw_write_gp_fuse_byte(), flashcalw_write_page(), and flashcalw_write_user_page().

void flashcalw_lock_all_regions ( bool lock )

Locks or unlocks all regions.

Parameters

lock	Whether to lock the regions: `true` or `false`.

Note: The FLASHCALW error status returned by flashcalw_is_lock_error and flashcalw_is_programming_error is updated.

References flashcalw_error_status, flashcalw_lock_region(), and FLASHCALW_REGIONS.

Referenced by run_flashcalw_protection_test().

void flashcalw_lock_page_region	(	int	page_number,
		bool	lock
	)

Locks or unlocks the region of a page.

Parameters

page_number	The page number: `0` to `(flashcalw_get_page_count() - 1)`: a page number within the flash array; `< 0`: the current page number.
lock	Whether to lock the region of the specified page: `true` or `false`.

Note: The FLASHCALW error status returned by flashcalw_is_lock_error and flashcalw_is_programming_error is updated.

References flashcalw_issue_command().

Referenced by flash_protect_example(), flashcalw_lock_region(), run_flashcalw_page_access_test(), and run_flashcalw_protection_test().

void flashcalw_lock_region	(	uint32_t	region,
		bool	lock
	)

Locks or unlocks a region.

Parameters

region	The region number: `0` to `(FLASHCALW_REGIONS - 1)`.
lock	Whether to lock the specified region: `true` or `false`.

Note: The FLASHCALW error status returned by flashcalw_is_lock_error and flashcalw_is_programming_error is updated.

References flashcalw_get_region_first_page_number(), and flashcalw_lock_page_region().

Referenced by flashcalw_lock_all_regions(), and run_flashcalw_protection_test().

volatile void* flashcalw_memcpy	(	volatile void *	dst,
		const void *	src,
		size_t	nbytes,
		bool	erase
	)

Copies nbytes bytes to the flash destination pointed to by dst from the source pointed to by src.

The destination areas that are not within the flash array or the User page are caught by an Assert() operation.

All pointer and size alignments are supported.

Parameters

dst	Pointer to flash destination.
src	Pointer to source data.
nbytes	Number of bytes to copy.
erase	Whether to erase before writing: `true` or `false`.

Returns: The value of dst.

Warning: If copying takes place between areas that overlap, the behavior is undefined.; This function may be called with erase set to false only if the destination consists only of erased words, i.e. this function can not be used to write only one bit of a previously written word. E.g., if 0x00000001 then 0xFFFFFFFE are written to a word, the resulting value in flash may be different from 0x00000000.; A Lock Error is issued if the command is applied to pages belonging to a locked region or to the bootloader protected area.

Note: The FLASHCALW error status returned by flashcalw_is_lock_error and flashcalw_is_programming_error is updated.

References Assert, FLASH_PAGE_SIZE, flashcalw_clear_page_buffer(), flashcalw_erase_page(), flashcalw_erase_user_page(), flashcalw_error_status, flashcalw_get_flash_size(), flashcalw_write_page(), flashcalw_write_user_page(), Union64::u64, and Union64::u8.

Referenced by flash_rw_example(), main(), program_memory(), run_flashcalw_page_access_test(), and run_wdt_test_all().

volatile void* flashcalw_memset16	(	volatile void *	dst,
		uint16_t	src,
		size_t	nbytes,
		bool	erase
	)

Copies nbytes bytes to the flash destination pointed to by dst from the repeated src big-endian source half-word.

All pointer and size alignments are supported.

Parameters

dst	Pointer to flash destination.
src	Source half-word.
nbytes	Number of bytes to set.
erase	Whether to erase before writing: `true` or `false`.

Returns: The value of dst.

Warning: This function may be called with erase set to false only if the destination consists only of erased words, i.e. this function can not be used to write only one bit of a previously written word. E.g., if 0x00000001 then 0xFFFFFFFE are written to a word, the resulting value in flash may be different from 0x00000000.; A Lock Error is issued if the command is applied to pages belonging to a locked region or to the bootloader protected area.

Note: The FLASHCALW error status returned by flashcalw_is_lock_error and flashcalw_is_programming_error is updated.

References flashcalw_memset32().

Referenced by flashcalw_memset8().

volatile void* flashcalw_memset32	(	volatile void *	dst,
		uint32_t	src,
		size_t	nbytes,
		bool	erase
	)

Copies nbytes bytes to the flash destination pointed to by dst from the repeated src big-endian source word.

All pointer and size alignments are supported.

Parameters

dst	Pointer to flash destination.
src	Source word.
nbytes	Number of bytes to set.
erase	Whether to erase before writing: `true` or `false`.

Returns: The value of dst.

Warning: This function may be called with erase set to false only if the destination consists only of erased words, i.e. this function can not be used to write only one bit of a previously written word. E.g., if 0x00000001 then 0xFFFFFFFE are written to a word, the resulting value in flash may be different from 0x00000000.; A Lock Error is issued if the command is applied to pages belonging to a locked region or to the bootloader protected area.

Note: The FLASHCALW error status returned by flashcalw_is_lock_error and flashcalw_is_programming_error is updated.

References flashcalw_memset64().

Referenced by flashcalw_memset16().

volatile void* flashcalw_memset64	(	volatile void *	dst,
		uint64_t	src,
		size_t	nbytes,
		bool	erase
	)

Copies nbytes bytes to the flash destination pointed to by dst from the repeated src big-endian source double-word.

All pointer and size alignments are supported.

Parameters

dst	Pointer to flash destination.
src	Source double-word.
nbytes	Number of bytes to set.
erase	Whether to erase before writing: `true` or `false`.

Returns: The value of dst.

Warning: This function may be called with erase set to false only if the destination consists only of erased words, i.e. this function can not be used to write only one bit of a previously written word. E.g., if 0x00000001 then 0xFFFFFFFE are written to a word, the resulting value in flash may be different from 0x00000000.; A Lock Error is issued if the command is applied to pages belonging to a locked region or to the bootloader protected area.

Note: The FLASHCALW error status returned by flashcalw_is_lock_error and flashcalw_is_programming_error is updated.

References Align_down, FLASH_PAGE_SIZE, flashcalw_clear_page_buffer(), flashcalw_erase_page(), flashcalw_erase_user_page(), flashcalw_error_status, flashcalw_get_flash_size(), flashcalw_write_page(), flashcalw_write_user_page(), Get_align, if(), Min, Test_align, StructCVPtr::u16ptr, UnionVPtr::u32ptr, StructCVPtr::u32ptr, Union64::u64, UnionVPtr::u64ptr, UnionCVPtr::u64ptr, StructCVPtr::u64ptr, Union64::u8, UnionVPtr::u8ptr, UnionCVPtr::u8ptr, and StructCVPtr::u8ptr.

Referenced by flashcalw_memset32().

volatile void* flashcalw_memset8	(	volatile void *	dst,
		uint8_t	src,
		size_t	nbytes,
		bool	erase
	)

Copies nbytes bytes to the flash destination pointed to by dst from the repeated src source byte.

All pointer and size alignments are supported.

Parameters

dst	Pointer to flash destination.
src	Source byte.
nbytes	Number of bytes to set.
erase	Whether to erase before writing: `true` or `false`.

Returns: The value of dst.

Warning: This function may be called with erase set to false only if the destination consists only of erased words, i.e. this function cannot be used to write only one bit of a previously written word. E.g., if 0x00000001 then 0xFFFFFFFE are written to a word, the resulting value in flash may be different from 0x00000000.; A Lock Error is issued if the command is applied to pages belonging to a locked region or to the bootloader protected area.

Note: The FLASHCALW error status returned by flashcalw_is_lock_error and flashcalw_is_programming_error is updated.

References flashcalw_memset16().

void flashcalw_no_operation ( void )

Issues a No Operation command to the FLASHCALW.

Note: The FLASHCALW error status returned by flashcalw_is_lock_error and flashcalw_is_programming_error is updated.

References flashcalw_issue_command().

void flashcalw_picocache_disable ( void )

Disable PicoCache.

References flashcalw_picocache_get_status(), and sysclk_disable_peripheral_clock().

Referenced by flash_picocache_example(), and run_flashcalw_picocache_test().

void flashcalw_picocache_disable_monitor ( void )

Disable PicoCache monitor.

Referenced by flash_picocache_example(), and run_flashcalw_picocache_test().

void flashcalw_picocache_enable ( void )

Enable PicoCache.

References flashcalw_picocache_get_status(), and sysclk_enable_peripheral_clock().

Referenced by flash_picocache_example(), and run_flashcalw_picocache_test().

void flashcalw_picocache_enable_monitor ( void )

Enable PicoCache monitor.

Referenced by flash_picocache_example().

uint32_t flashcalw_picocache_get_monitor_cnt ( void )

Get PicoCache monitor count number.

Returns: Monitor counter number.

Referenced by flash_picocache_example().

uint32_t flashcalw_picocache_get_status ( void )

Get PicoCache status.

Returns: 1 If PicoCahe is enabled, else disabled.

Referenced by flashcalw_picocache_disable(), flashcalw_picocache_enable(), and flashcalw_picocache_invalid_line().

uint32_t flashcalw_picocache_get_version ( void )

Get PicoCache version.

Returns: PicoCache version.

void flashcalw_picocache_invalid_all ( void )

Invalid all PicoCache lines.

void flashcalw_picocache_invalid_line ( uint32_t index )

Invalid specific cache line.

Parameters

index Lines to be invalid.

References flashcalw_picocache_get_status().

void flashcalw_picocache_reset_monitor ( void )

Reset PicoCache monitor.

Referenced by flash_picocache_example().

void flashcalw_picocache_set_monitor_mode ( uint32_t mode )

Set PicoCache monitor mode.

Parameters

mode	PicoCache mode, 0 for cycle, 1 for instruction hit and 2 for data hit.

References mode.

Referenced by flash_picocache_example().

bool flashcalw_quick_page_read ( int page_number )

Applies the Quick Page Read command to a page.

Parameters

page_number

The page number:

0 to (flashcalw_get_page_count() - 1): a page number within the flash array;
< 0: the current page number.

Returns: Whether the specified page is erased.

Note: The FLASHCALW error status returned by flashcalw_is_lock_error and flashcalw_is_programming_error is updated.

References flashcalw_is_page_erased(), and flashcalw_issue_command().

Referenced by flashcalw_erase_page().

bool flashcalw_quick_user_page_read ( void )

Issues a Quick Page Read User Page command to the FLASHCALW.

Returns: Whether the User page is erased.

Note: The FLASHCALW error status returned by flashcalw_is_lock_error and flashcalw_is_programming_error is updated.

References flashcalw_is_page_erased(), and flashcalw_issue_command().

Referenced by flashcalw_erase_user_page().

uint64_t flashcalw_read_all_gp_fuses ( void )

Reads all general-purpose fuses.

Returns: The value of all general-purpose fuses as a word.

Note: The actual number of general-purpose fuse bits implemented by hardware is given by FLASH_GPF_NUM. The other bits among the 64 are fixed at 1 by hardware.

Referenced by flashcalw_erase_all_gp_fuses(), flashcalw_erase_gp_fuse_byte(), flashcalw_read_gp_fuse_bit(), flashcalw_read_gp_fuse_bitfield(), flashcalw_read_gp_fuse_byte(), and run_flashcalw_gp_fuse_test().

bool flashcalw_read_gp_fuse_bit ( uint32_t gp_fuse_bit )

Reads a general-purpose fuse bit.

Parameters

gp_fuse_bit The general-purpose fuse bit: 0 to 63.

Returns: The value of the specified general-purpose fuse bit.

Note: The actual number of general-purpose fuse bits implemented by hardware is given by FLASH_GPF_NUM. The other bits among the 64 are fixed at 1 by hardware.

References flashcalw_read_all_gp_fuses().

Referenced by bootloader_mode_check(), flashcalw_erase_gp_fuse_bit(), main(), and run_flashcalw_gp_fuse_test().

uint64_t flashcalw_read_gp_fuse_bitfield	(	uint32_t	pos,
		uint32_t	width
	)

Reads a general-purpose fuse bit-field.

Parameters

pos	The bit-position of the general-purpose fuse bit-field: `0` to `63`.
width	The bit-width of the general-purpose fuse bit-field: `0` to `64`.

Returns: The value of the specified general-purpose fuse bit-field.

Note: The actual number of general-purpose fuse bits implemented by hardware is given by FLASH_GPF_NUM. The other bits among the 64 are fixed at 1 by hardware.

References flashcalw_read_all_gp_fuses(), and Min.

Referenced by flashcalw_erase_gp_fuse_bitfield(), and run_flashcalw_gp_fuse_test().

uint8_t flashcalw_read_gp_fuse_byte ( uint32_t gp_fuse_byte )

Reads a general-purpose fuse byte.

Parameters

gp_fuse_byte The general-purpose fuse byte: 0 to 7.

Returns: The value of the specified general-purpose fuse byte.

Note: The actual number of general-purpose fuse bits implemented by hardware is given by FLASH_GPF_NUM. The other bits among the 64 are fixed at 1 by hardware.

References flashcalw_read_all_gp_fuses().

Referenced by flashcalw_erase_gp_fuse_byte(), and run_flashcalw_gp_fuse_test().

void flashcalw_set_all_gp_fuses ( uint64_t value )

Sets all general-purpose fuses with the appropriate erase and write operations.

Parameters

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 FLASHCALW error status returned by flashcalw_is_lock_error and flashcalw_is_programming_error is updated.; The actual number of general-purpose fuse bits implemented by hardware is given by FLASH_GPF_NUM. The other bits among the 64 are fixed at 1 by hardware.

use (uint64_t)-1 instead of 0xFFFFFFFFFFFFFFFFULL to avoid compilation warning

References flashcalw_erase_all_gp_fuses(), flashcalw_error_status, and flashcalw_write_all_gp_fuses().

void flashcalw_set_flash_waitstate_and_readmode	(	uint32_t	cpu_f_hz,
		uint32_t	ps_value,
		bool	is_fwu_enabled
	)

Depending on the CPU frequency, on the Power Scaling mode and on the Fast Wakeup mode, set the wait states of flash read accesses and enable or disable the High speed read mode.

Parameters

cpu_f_hz	The CPU frequency
ps_value	Power Scaling mode value (0, 1)
is_fwu_enabled	(boolean), Is fast wakeup mode enabled or not

References FLASH_FREQ_PS0_FWS_0_MAX_FREQ, FLASH_FREQ_PS0_FWS_1_MAX_FREQ, FLASH_FREQ_PS1_FWS_0_MAX_FREQ, FLASH_FREQ_PS1_FWS_1_FWU_MAX_FREQ, FLASH_FREQ_PS2_FWS_0_MAX_FREQ, flashcalw_issue_command(), flashcalw_set_wait_state(), and UNUSED.

void flashcalw_set_gp_fuse_bit	(	uint32_t	gp_fuse_bit,
		bool	value
	)

Sets a general-purpose fuse bit with the appropriate erase and write operations.

Parameters

gp_fuse_bit	The general-purpose fuse bit: `0` to `63`.
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.

Note: The FLASHCALW error status returned by flashcalw_is_lock_error and flashcalw_is_programming_error is updated.; The actual number of general-purpose fuse bits implemented by hardware is given by FLASH_GPF_NUM. The other bits among the 64 are fixed at 1 by hardware.

References flashcalw_erase_gp_fuse_bit(), and flashcalw_write_gp_fuse_bit().

Referenced by flashcalw_set_gp_fuse_bitfield().

void flashcalw_set_gp_fuse_bitfield	(	uint32_t	pos,
		uint32_t	width,
		uint64_t	value
	)

Sets a general-purpose fuse bit-field with the appropriate erase and write operations.

Parameters

pos	The bit-position of the general-purpose fuse bit-field: `0` to `63`.
width	The bit-width of the general-purpose fuse bit-field: `0` to `64`.
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.

Note: The FLASHCALW error status returned by flashcalw_is_lock_error and flashcalw_is_programming_error is updated.; The actual number of general-purpose fuse bits implemented by hardware is given by FLASH_GPF_NUM. The other bits among the 64 are fixed at 1 by hardware.

References flashcalw_error_status, flashcalw_set_gp_fuse_bit(), and Min.

void flashcalw_set_gp_fuse_byte	(	uint32_t	gp_fuse_byte,
		uint8_t	value
	)

Sets a general-purpose fuse byte with the appropriate erase and write operations.

Parameters

gp_fuse_byte	The general-purpose fuse byte: `0` to `7`.
value	The value of the specified general-purpose fuse byte.

Warning: A Lock Error is issued if the Security bit is active.

Note: The FLASHCALW error status returned by flashcalw_is_lock_error and flashcalw_is_programming_error is updated.; The actual number of general-purpose fuse bits implemented by hardware is given by FLASH_GPF_NUM. The other bits among the 64 are fixed at 1 by hardware.

References flashcalw_erase_gp_fuse_byte(), flashcalw_error_status, and flashcalw_write_gp_fuse_byte().

void flashcalw_set_security_bit ( void )

Activates the Security bit.

Note: The FLASHCALW error status returned by flashcalw_is_lock_error and flashcalw_is_programming_error is updated.

References flashcalw_issue_command().

Referenced by main().

void flashcalw_set_wait_state ( uint32_t wait_state )

Sets the number of wait states of flash read accesses.

Parameters

wait_state The number of wait states of flash read accesses: 0 to 1.

Referenced by flashcalw_set_flash_waitstate_and_readmode(), main(), run_flashcalw_control_test(), and run_flashcalw_picocache_test().

void flashcalw_write_all_gp_fuses ( uint64_t value )

Writes all general-purpose fuses.

Parameters

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 FLASHCALW error status returned by flashcalw_is_lock_error and flashcalw_is_programming_error is updated.; A write operation can only clear bits; in other words, an erase operation must first be done if some bits need to be set to 1.; The actual number of general-purpose fuse bits implemented by hardware is given by FLASH_GPF_NUM. The other bits among the 64 are fixed at 1 by hardware.

References flashcalw_error_status, and flashcalw_write_gp_fuse_byte().

Referenced by flashcalw_set_all_gp_fuses(), and run_flashcalw_gp_fuse_test().

void flashcalw_write_gp_fuse_bit	(	uint32_t	gp_fuse_bit,
		bool	value
	)

Writes a general-purpose fuse bit.

Parameters

gp_fuse_bit	The general-purpose fuse bit: `0` to `63`.
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.

Note: The FLASHCALW error status returned by flashcalw_is_lock_error and flashcalw_is_programming_error is updated.; A write operation can only clear bits; in other words, an erase operation must first be done if some bits need to be set to 1.; The actual number of general-purpose fuse bits implemented by hardware is given by FLASH_GPF_NUM. The other bits among the 64 are fixed at 1 by hardware.

References flashcalw_issue_command().

Referenced by flashcalw_set_gp_fuse_bit(), flashcalw_write_gp_fuse_bitfield(), and run_flashcalw_gp_fuse_test().

void flashcalw_write_gp_fuse_bitfield	(	uint32_t	pos,
		uint32_t	width,
		uint64_t	value
	)

Writes a general-purpose fuse bit-field.

Parameters

pos	The bit-position of the general-purpose fuse bit-field: `0` to `63`.
width	The bit-width of the general-purpose fuse bit-field: `0` to `64`.
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.

Note: The FLASHCALW error status returned by flashcalw_is_lock_error and flashcalw_is_programming_error is updated.; A write operation can only clear bits; in other words, an erase operation must first be done if some bits need to be set to 1.; The actual number of general-purpose fuse bits implemented by hardware is given by FLASH_GPF_NUM. The other bits among the 64 are fixed at 1 by hardware.

References flashcalw_error_status, flashcalw_write_gp_fuse_bit(), and Min.

Referenced by run_flashcalw_gp_fuse_test().

void flashcalw_write_gp_fuse_byte	(	uint32_t	gp_fuse_byte,
		uint8_t	value
	)

Writes a general-purpose fuse byte.

Parameters

gp_fuse_byte	The general-purpose fuse byte: `0` to `7`.
value	The value of the specified general-purpose fuse byte.

Warning: A Lock Error is issued if the Security bit is active.

Note: The FLASHCALW error status returned by flashcalw_is_lock_error and flashcalw_is_programming_error is updated.; A write operation can only clear bits; in other words, an erase operation must first be done if some bits need to be set to 1.; The actual number of general-purpose fuse bits implemented by hardware is given by FLASH_GPF_NUM. The other bits among the 64 are fixed at 1 by hardware.

References flashcalw_issue_command().

Referenced by flashcalw_erase_gp_fuse_byte(), flashcalw_set_gp_fuse_byte(), flashcalw_write_all_gp_fuses(), and run_flashcalw_gp_fuse_test().

void flashcalw_write_page ( int page_number )

Writes a page from the page buffer.

Parameters

page_number

The page number:

0 to (flashcalw_get_page_count() - 1): a page number within the flash array;
< 0: the current page number.

Warning: A Lock Error is issued if the command is applied to a page belonging to a locked region or to the bootloader protected area.; The page buffer is not automatically reset after a page write.

Note: The FLASHCALW error status returned by flashcalw_is_lock_error and flashcalw_is_programming_error is updated.; A write operation can only clear bits; in other words, an erase operation must first be done if some bits need to be set to 1.

References flashcalw_issue_command().

Referenced by flashcalw_memcpy(), and flashcalw_memset64().

void flashcalw_write_user_page ( void )

Writes the User page from the page buffer.

Warning: The page buffer is not automatically reset after a page write.

Note: The FLASHCALW error status returned by flashcalw_is_lock_error and flashcalw_is_programming_error is updated.; A write operation can only clear bits; in other words, an erase operation must first be done if some bits need to be set to 1.

References flashcalw_issue_command().

Referenced by flashcalw_memcpy(), and flashcalw_memset64().

uint32_t flashcalw_error_status = 0

static

Sticky error status of the FLASHCALW.

This variable is updated by functions that issue FLASHCALW commands. It contains the cumulated FLASHCALW error status of all the FLASHCALW commands issued by a function.

Referenced by flashcalw_erase_all_pages(), flashcalw_erase_gp_fuse_bitfield(), flashcalw_erase_gp_fuse_byte(), flashcalw_erase_page(), flashcalw_lock_all_regions(), flashcalw_memcpy(), flashcalw_memset64(), flashcalw_set_all_gp_fuses(), flashcalw_set_gp_fuse_bitfield(), flashcalw_set_gp_fuse_byte(), flashcalw_write_all_gp_fuses(), and flashcalw_write_gp_fuse_bitfield().

void(*volatile flashcalw_wait_until_ready)(void) = flashcalw_default_wait_until_ready

Pointer to the function used by the driver when it needs to wait until the FLASHCALW is ready to run a new command.

The default function is flashcalw_default_wait_until_ready. The user may change this pointer to use another implementation.

Referenced by flashcalw_issue_command().

Microchip® Advanced Software Framework

Modules

Flash Properties

FLASHC Control

FLASHCALW Status

FLASHCALW Command Control

FLASHCALW Global Commands

FLASHCALW Protection Mechanisms

Access to General-Purpose Fuses

Access to Flash Pages

PicoCache interfaces