xf_fal

xf_fal Flash 抽象层 FAL (Flash Abstraction Layer). 更多...

结构体
struct	_xf_fal_flash_dev_t
	flash 设备结构体。 更多...
struct	_xf_fal_partition_t
	flash 分区结构体。 更多...

类型定义
typedef struct _xf_fal_flash_dev_t	xf_fal_flash_dev_t
	flash 设备结构体。
typedef struct _xf_fal_partition_t	xf_fal_partition_t
	flash 分区结构体。

函数
xf_err_t	xf_fal_check_and_update_cache (void)
	更新分区表中的分区与关联的 flash 设备的缓存。
const xf_fal_ctx_t *	xf_fal_get_ctx (void)
	获取 xf_fal 上下文。
xf_err_t	xf_fal_register_flash_device (const xf_fal_flash_dev_t *p_dev)
	注册一个 flash 设备到 xf_fal 中。
xf_err_t	xf_fal_register_partition_table (const xf_fal_partition_t *p_table, size_t table_len)
	注册一个分区表到 xf_fal 中。
xf_err_t	xf_fal_unregister_flash_device (const xf_fal_flash_dev_t *p_dev)
	从 xf_fal 中注销一个 flash 设备。
xf_err_t	xf_fal_unregister_partition_table (const xf_fal_partition_t *p_table)
	从 xf_fal 中注销一个分区表。
bool	xf_fal_check_register_state (void)
	检查 xf_fal 注册状态。
xf_err_t	xf_fal_init (void)
	初始化 FAL.
xf_err_t	xf_fal_deinit (void)
	反初始化 FAL.
const xf_fal_flash_dev_t *	xf_fal_flash_device_find (const char *name)
	根据 flash 名称查找 flash 设备。
const xf_fal_flash_dev_t *	xf_fal_flash_device_find_by_part (const xf_fal_partition_t *part)
	通过给定分区查找 flash 设备。
const xf_fal_partition_t *	xf_fal_partition_find (const char *name)
	根据分区名称查找分区句柄。
xf_err_t	xf_fal_partition_read (const xf_fal_partition_t *part, size_t src_offset, void *dst, size_t size)
	从指定分区读取数据。
xf_err_t	xf_fal_partition_write (const xf_fal_partition_t *part, size_t dst_offset, const void *src, size_t size)
	将数据写入指定分区。
xf_err_t	xf_fal_partition_erase (const xf_fal_partition_t *part, size_t offset, size_t size)
	擦除指定分区数据。
xf_err_t	xf_fal_partition_erase_all (const xf_fal_partition_t *part)
	擦除指定分区所有数据。
void	xf_fal_show_part_table (void)
	打印分区表信息。

详细描述

xf_fal Flash 抽象层 FAL (Flash Abstraction Layer).

类型定义说明

xf_fal_flash_dev_t

typedef struct _xf_fal_flash_dev_t xf_fal_flash_dev_t

flash 设备结构体。

注意

结构体是可见的，但禁止用户修改其中内容。

xf_fal_partition_t

typedef struct _xf_fal_partition_t xf_fal_partition_t

flash 分区结构体。

描述各分区的分区名、分区在哪个 flash、分区在 flash 上的偏移地址和长度。

注意

结构体是可见的，但禁止用户修改其中内容。

函数说明

xf_fal_check_and_update_cache()

xf_err_t xf_fal_check_and_update_cache

(

void

)

更新分区表中的分区与关联的 flash 设备的缓存。

注解

xf_fal_init() 内会自动调用一次。

如果在初始化后注册或反注册了分区表或 flash 设备， 需要调用此接口更新缓存。

返回

xf_err_t

• XF_OK 成功
• XF_FAIL 失败
• XF_ERR_INVALID_PORT 未注册 xf_fal

在文件 xf_fal.c 第 579 行定义.

xf_fal_get_ctx()

const xf_fal_ctx_t * xf_fal_get_ctx

(

void

)

获取 xf_fal 上下文。

注解

通过此接口可获取当前 xf_fal 注册状态、注册的 flash 设备和注册的分区表。 可用于动态扩展分区表。

注意

禁止直接修改其中内容。

返回

xf_fal_ctx_t* xf_fal 上下文

在文件 xf_fal.c 第 254 行定义.

xf_fal_register_flash_device()

xf_err_t xf_fal_register_flash_device

(

const xf_fal_flash_dev_t *

p_dev

)

注册一个 flash 设备到 xf_fal 中。

注意

xf_fal 内仅保存 flash 设备指针， 用户必须保证在使用 xf_fal 的整个过程中 flash 设备可访问。

用户应保证 flash 设备名不重复。否则只会找到第一个。

注册完毕后需要调用 xf_fal_init() 初始化 xf_fal .

已初始化后禁止注册或注销，需调用 xf_fal_deinit() 反初始化.

参数

p_dev

flash 设备。

返回

xf_err_t

• XF_OK 成功
• XF_FAIL xf_fal 已初始化，禁止注册注销
• XF_ERR_BUSY xf_fal 被别处占用
• XF_ERR_INVALID_ARG 无效参数
• XF_ERR_INVALID_PORT 无效对接, p_dev->ops 的 read, write, erase 存在 NULL
• XF_ERR_INITED p_dev 已注册
• XF_ERR_RESOURCE xf_fal 的设备表数组已满，需增大 XF_FAL_FLASH_DEVICE_NUM

在文件 xf_fal.c 第 95 行定义.

xf_fal_register_partition_table()

xf_err_t xf_fal_register_partition_table	(	const xf_fal_partition_t *	p_table,
		size_t	table_len
	)

注册一个分区表到 xf_fal 中。

注意

xf_fal 内仅保存分区表指针， 用户必须保证在使用 xf_fal 的整个过程中分区表可访问。

用户应保证分区表内的分区不发生交叠，且分区不重名，否则只会找到第一个。

注册完毕后需要调用 xf_fal_init() 初始化 xf_fal .

已初始化后禁止注册或注销，需调用 xf_fal_deinit() 反初始化.

参数

p_table	分区表数组。注意不是分区。
table_len	分区表表长。单位：分区个数。

返回

xf_err_t

• XF_OK 成功
• XF_FAIL xf_fal 已初始化，禁止注册注销
• XF_ERR_BUSY xf_fal 被别处占用
• XF_ERR_INVALID_ARG 无效参数
• XF_ERR_INITED p_table 已注册
• XF_ERR_RESOURCE xf_fal 的分区表数组已满，需增大 XF_FAL_PARTITION_TABLE_NUM

在文件 xf_fal.c 第 139 行定义.

xf_fal_unregister_flash_device()

xf_err_t xf_fal_unregister_flash_device

(

const xf_fal_flash_dev_t *

p_dev

)

从 xf_fal 中注销一个 flash 设备。

注意

已初始化后禁止注册或注销，需调用 xf_fal_deinit() 反初始化.

参数

p_dev

要注销的 flash 设备。

返回

xf_err_t

• XF_OK 成功
• XF_FAIL xf_fal 已初始化，禁止注册注销
• XF_ERR_BUSY xf_fal 被别处占用
• XF_ERR_INVALID_ARG 无效参数
• XF_ERR_NOT_FOUND 未找到

在文件 xf_fal.c 第 180 行定义.

xf_fal_unregister_partition_table()

xf_err_t xf_fal_unregister_partition_table

(

const xf_fal_partition_t *

p_table

)

从 xf_fal 中注销一个分区表。

注意

已初始化后禁止注册或注销，需调用 xf_fal_deinit() 反初始化.

参数

p_table

分区表数组。注意不是分区。

返回

xf_err_t

• XF_OK 成功
• XF_FAIL xf_fal 已初始化，禁止注册注销
• XF_ERR_BUSY xf_fal 被别处占用
• XF_ERR_INVALID_ARG 无效参数
• XF_ERR_NOT_FOUND 未找到

在文件 xf_fal.c 第 213 行定义.

xf_fal_check_register_state()

bool xf_fal_check_register_state

(

void

)

检查 xf_fal 注册状态。

返回

true 已注册

false 未注册

在文件 xf_fal.c 第 246 行定义.

xf_fal_init()

xf_err_t xf_fal_init

(

void

)

初始化 FAL.

返回

xf_err_t

• XF_OK 成功
• XF_FAIL 失败
• XF_ERR_INITED 已初始化
• XF_ERR_INVALID_PORT 未注册 xf_fal

在文件 xf_fal.c 第 259 行定义.

xf_fal_deinit()

xf_err_t xf_fal_deinit

(

void

)

反初始化 FAL.

返回

xf_err_t

• XF_OK 成功
• XF_FAIL 失败
• XF_ERR_UNINIT 未初始化
• XF_ERR_INVALID_PORT 未注册 xf_fal

在文件 xf_fal.c 第 293 行定义.

xf_fal_flash_device_find()

const xf_fal_flash_dev_t * xf_fal_flash_device_find

(

const char *

name

)

根据 flash 名称查找 flash 设备。

参数

name

flash 名称。

返回

const xf_fal_flash_dev_t*

• NULL 未找到或参数错误或未注册 xf_fal
• (OTHER) flash 设备句柄

在文件 xf_fal.c 第 318 行定义.

xf_fal_flash_device_find_by_part()

const xf_fal_flash_dev_t * xf_fal_flash_device_find_by_part

(

const xf_fal_partition_t *

part

)

通过给定分区查找 flash 设备。

注解

此函数通常用于获取 xf_fal_flash_dev_t.sector_size 和 xf_fal_flash_dev_t.io_size . 使用户确定擦除大小。

参数

part	分区表中的指定分区。 可以通过 xf_fal_partition_find() 获取。

返回

xf_err_t

• NULL 未找到或参数错误或未注册 xf_fal
• (OTHER) flash 设备句柄

在文件 xf_fal.c 第 342 行定义.

xf_fal_partition_find()

const xf_fal_partition_t * xf_fal_partition_find

(

const char *

name

)

根据分区名称查找分区句柄。

参数

name

分区表名称。

返回

const xf_fal_partition_t*

• NULL 未找到或参数错误或未注册 xf_fal
• (OTHER) 分区表句柄

在文件 xf_fal.c 第 370 行定义.

xf_fal_partition_read()

xf_err_t xf_fal_partition_read	(	const xf_fal_partition_t *	part,
		size_t	src_offset,
		void *	dst,
		size_t	size
	)

从指定分区读取数据。

注解

读写数据的大小以及偏移地址需要是 flash 最小读写颗粒大小的整数倍。 见 xf_fal_flash_dev_t::io_size .

参数

	part	分区表中的指定分区。 可以通过 xf_fal_partition_find() 获取。
	src_offset	要读取的数据的地址。相对当前分区起始地址的偏移地址。
[out]	dst	指向读取缓冲区。
	size	要读取的数据大小，单位：字节。

返回

xf_err_t

• XF_OK 成功
• XF_FAIL 失败
• XF_ERR_UNINIT 未初始化
• XF_ERR_INVALID_ARG 无效参数

在文件 xf_fal.c 第 404 行定义.

xf_fal_partition_write()

xf_err_t xf_fal_partition_write	(	const xf_fal_partition_t *	part,
		size_t	dst_offset,
		const void *	src,
		size_t	size
	)

将数据写入指定分区。

注解

读写数据的大小以及偏移地址需要是 flash 最小读写颗粒大小的整数倍。 见 xf_fal_flash_dev_t::io_size .

写入前一定要确认目标地址已经被擦除。

参数

part	分区表中的指定分区。 可以通过 xf_fal_partition_find() 获取。
dst_offset	要写入的数据的地址。相对当前分区起始地址的偏移地址。
src	指向数据来源缓冲区。
size	要写入的数据大小，单位：字节。

返回

xf_err_t

• XF_OK 成功
• XF_FAIL 失败
• XF_ERR_UNINIT 未初始化
• XF_ERR_INVALID_ARG 无效参数

在文件 xf_fal.c 第 443 行定义.

xf_fal_partition_erase()

xf_err_t xf_fal_partition_erase	(	const xf_fal_partition_t *	part,
		size_t	offset,
		size_t	size
	)

擦除指定分区数据。

注解

擦除数据的大小推荐对齐到 flash 扇区大小的整数倍。 扇区大小见 xf_fal_flash_dev_t::sector_size . 可以通过 xf_fal_flash_device_find_by_part() 获取。

注意

如果分区偏移地址和 offset 和 size 未对齐到扇区， 则可能无法擦除。需要看对接的实现。

参数

part	分区表中的指定分区。 可以通过 xf_fal_partition_find() 获取。
offset	待擦除的地址。相对当前分区起始地址的偏移地址。 推荐对齐到 flash 扇区大小的整数倍。
size	要擦除的数据大小，单位：字节。

返回

xf_err_t

• XF_OK 成功
• XF_FAIL 失败
• XF_ERR_UNINIT 未初始化
• XF_ERR_INVALID_ARG 无效参数

在文件 xf_fal.c 第 482 行定义.

xf_fal_partition_erase_all()

xf_err_t xf_fal_partition_erase_all

(

const xf_fal_partition_t *

part

)

擦除指定分区所有数据。

参数

part	分区表的指定分区。 可以通过 xf_fal_partition_find() 获取。

返回

xf_err_t

• XF_OK 成功
• XF_FAIL 失败
• XF_ERR_UNINIT 未初始化
• XF_ERR_INVALID_ARG 无效参数

在文件 xf_fal.c 第 520 行定义.

xf_fal_show_part_table()

void xf_fal_show_part_table

(

void

)

打印分区表信息。

在文件 xf_fal.c 第 525 行定义.