summaryrefslogtreecommitdiff
path: root/components/fal/samples
diff options
context:
space:
mode:
authorLiuKang <[email protected]>2022-03-15 09:48:05 +0800
committerGitHub <[email protected]>2022-03-15 09:48:05 +0800
commit75a7cb69292243adfdff15722ea9b07b1642438c (patch)
treee7a821c516b1d72cd4856e49525a8f60c653120a /components/fal/samples
parent3b1445d49c316a73d53f5d9550a2a20d65282f76 (diff)
[update] add fal component. (#5662)
* [update] add fal component. * [update] format code. * [update] change PKG_USING_FAL to RT_USING_FAL * [update] format code. * [update] fal * [update] delete FAL_SW_VERSION
Diffstat (limited to 'components/fal/samples')
-rw-r--r--components/fal/samples/README.md4
-rw-r--r--components/fal/samples/porting/README.md108
-rw-r--r--components/fal/samples/porting/fal_cfg.h41
-rw-r--r--components/fal/samples/porting/fal_flash_sfud_port.c96
-rw-r--r--components/fal/samples/porting/fal_flash_stm32f2_port.c198
5 files changed, 447 insertions, 0 deletions
diff --git a/components/fal/samples/README.md b/components/fal/samples/README.md
new file mode 100644
index 0000000000..fcbb58a538
--- /dev/null
+++ b/components/fal/samples/README.md
@@ -0,0 +1,4 @@
+| 文件夹 | 说明 |
+| :------ | :----------------------- |
+| porting | 移植相关的示例代码及文档 |
+
diff --git a/components/fal/samples/porting/README.md b/components/fal/samples/porting/README.md
new file mode 100644
index 0000000000..36c04e1843
--- /dev/null
+++ b/components/fal/samples/porting/README.md
@@ -0,0 +1,108 @@
+# Flash 设备及分区移植示例
+
+本示例主要演示 Flash 设备及分区相关的移植。
+
+## 1、Flash 设备
+
+在定义 Flash 设备表前,需要先定义 Flash 设备,参考 [`fal_flash_sfud_port.c`](fal_flash_sfud_port.c) (基于 [SFUD](https://github.com/armink/SFUD) 万能 SPI Flash 驱动的 Flash 设备)与 [`fal_flash_stm32f2_port.c`](fal_flash_stm32f2_port.c) (STM32F2 片内 Flash)这两个文件。这里简介下 `fal_flash_stm32f2_port.c` 里的代码实现。
+
+### 1.1 定义 Flash 设备
+
+针对 Flash 的不同操作,这里定义了如下几个操作函数:
+
+- `static int init(void)`:**可选** 的初始化操作
+
+- `static int read(long offset, uint8_t *buf, size_t size)`:读取操作
+
+|参数 |描述|
+|:----- |:----|
+|offset |读取数据的 Flash 偏移地址|
+|buf |存放待读取数据的缓冲区|
+|size |待读取数据的大小|
+|return |返回实际读取的数据大小|
+
+- `static int write(long offset, const uint8_t *buf, size_t size)` :写入操作
+
+| 参数 | 描述 |
+| :----- | :------------------------ |
+| offset | 写入数据的 Flash 偏移地址 |
+| buf | 存放待写入数据的缓冲区 |
+| size | 待写入数据的大小 |
+| return | 返回实际写入的数据大小 |
+
+- `static int erase(long offset, size_t size)` :擦除操作
+
+| 参数 | 描述 |
+| :----- | :------------------------ |
+| offset | 擦除区域的 Flash 偏移地址 |
+| size | 擦除区域的大小 |
+| return | 返回实际擦除的区域大小 |
+
+用户需要根据自己的 Flash 情况分别实现这些操作函数。在文件最底部定义了具体的 Flash 设备对象(stm32f2_onchip_flash):
+
+`const struct fal_flash_dev stm32f2_onchip_flash = { "stm32_onchip", 0x08000000, 1024*1024, 128*1024, {init, read, write, erase} };`
+
+- `"stm32_onchip"` : Flash 设备的名字
+- 0x08000000: 对 Flash 操作的起始地址
+- 1024*1024:Flash 的总大小(1MB)
+- 128*1024:Flash 块/扇区大小(因为 STM32F2 各块大小不均匀,所以擦除粒度为最大块的大小:128K)
+- {init, read, write, erase} }:Flash 的操作函数。 如果没有 init 初始化过程,第一个操作函数位置可以置空。
+
+### 1.2 定义 Flash 设备表
+
+Flash 设备表定义在 `fal_cfg.h` 头文件中,定义分区表前需 **新建 `fal_cfg.h` 文件** 。
+
+参考 [示例文件 samples/porting/fal_cfg.h](samples/porting/fal_cfg.h) 或如下代码:
+
+```c
+/* ===================== Flash device Configuration ========================= */
+extern const struct fal_flash_dev stm32f2_onchip_flash;
+extern struct fal_flash_dev nor_flash0;
+
+/* flash device table */
+#define FAL_FLASH_DEV_TABLE \
+{ \
+ &stm32f2_onchip_flash, \
+ &nor_flash0, \
+}
+```
+
+Flash 设备表中,有两个 Flash 对象,一个为 STM32F2 的片内 Flash ,一个为片外的 Nor Flash。
+
+## 2、Flash 分区
+
+Flash 分区基于 Flash 设备,每个 Flash 设备又可以有 N 个分区,这些分区的集合就是分区表。在配置分区表前,务必保证已定义好 Flash 设备及设备表。
+
+分区表也定义在 `fal_cfg.h` 头文件中。参考 [示例文件 samples/porting/fal_cfg.h](samples/porting/fal_cfg.h) 或如下代码:
+
+```C
+#define NOR_FLASH_DEV_NAME "norflash0"
+/* ====================== Partition Configuration ========================== */
+#ifdef FAL_PART_HAS_TABLE_CFG
+/* partition table */
+#define FAL_PART_TABLE \
+{ \
+ {FAL_PART_MAGIC_WORD, "bl", "stm32_onchip", 0, 64*1024, 0}, \
+ {FAL_PART_MAGIC_WORD, "app", "stm32_onchip", 64*1024, 704*1024, 0}, \
+ {FAL_PART_MAGIC_WORD, "easyflash", NOR_FLASH_DEV_NAME, 0, 1024*1024, 0}, \
+ {FAL_PART_MAGIC_WORD, "download", NOR_FLASH_DEV_NAME, 1024*1024, 1024*1024, 0}, \
+}
+#endif /* FAL_PART_HAS_TABLE_CFG */
+```
+
+上面这个分区表详细描述信息如下:
+
+| 分区名 | Flash 设备名 | 偏移地址 | 大小 | 说明 |
+| :---------- | :------------- | :-------- | :---- | :----------------- |
+| "bl" | "stm32_onchip" | 0 | 64KB | 引导程序 |
+| "app" | "stm32_onchip" | 64*1024 | 704KB | 应用程序 |
+| "easyflash" | "norflash0" | 0 | 1MB | EasyFlash 参数存储 |
+| "download" | "norflash0" | 1024*1024 | 1MB | OTA 下载区 |
+
+用户需要修改的分区参数包括:分区名称、关联的 Flash 设备名、偏移地址(相对 Flash 设备内部)、大小,需要注意以下几点:
+
+- 分区名保证 **不能重复**
+- 关联的 Flash 设备 **务必已经在 Flash 设备表中定义好** ,并且 **名称一致** ,否则会出现无法找到 Flash 设备的错误
+- 分区的起始地址和大小 **不能超过 Flash 设备的地址范围** ,否则会导致包初始化错误
+
+> 注意:每个分区定义时,除了填写上面介绍的参数属性外,需在前面增加 `FAL_PART_MAGIC_WORD` 属性,末尾增加 `0` (目前用于保留功能)
diff --git a/components/fal/samples/porting/fal_cfg.h b/components/fal/samples/porting/fal_cfg.h
new file mode 100644
index 0000000000..71c84522e5
--- /dev/null
+++ b/components/fal/samples/porting/fal_cfg.h
@@ -0,0 +1,41 @@
+/*
+ * Copyright (c) 2006-2018, RT-Thread Development Team
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * Change Logs:
+ * Date Author Notes
+ * 2018-05-17 armink the first version
+ */
+
+#ifndef _FAL_CFG_H_
+#define _FAL_CFG_H_
+
+#include <rtconfig.h>
+#include <board.h>
+
+#define NOR_FLASH_DEV_NAME "norflash0"
+
+/* ===================== Flash device Configuration ========================= */
+extern const struct fal_flash_dev stm32f2_onchip_flash;
+extern struct fal_flash_dev nor_flash0;
+
+/* flash device table */
+#define FAL_FLASH_DEV_TABLE \
+{ \
+ &stm32f2_onchip_flash, \
+ &nor_flash0, \
+}
+/* ====================== Partition Configuration ========================== */
+#ifdef FAL_PART_HAS_TABLE_CFG
+/* partition table */
+#define FAL_PART_TABLE \
+{ \
+ {FAL_PART_MAGIC_WORD, "bl", "stm32_onchip", 0, 64*1024, 0}, \
+ {FAL_PART_MAGIC_WORD, "app", "stm32_onchip", 64*1024, 704*1024, 0}, \
+ {FAL_PART_MAGIC_WORD, "easyflash", NOR_FLASH_DEV_NAME, 0, 1024*1024, 0}, \
+ {FAL_PART_MAGIC_WORD, "download", NOR_FLASH_DEV_NAME, 1024*1024, 1024*1024, 0}, \
+}
+#endif /* FAL_PART_HAS_TABLE_CFG */
+
+#endif /* _FAL_CFG_H_ */
diff --git a/components/fal/samples/porting/fal_flash_sfud_port.c b/components/fal/samples/porting/fal_flash_sfud_port.c
new file mode 100644
index 0000000000..35bbc0f276
--- /dev/null
+++ b/components/fal/samples/porting/fal_flash_sfud_port.c
@@ -0,0 +1,96 @@
+/*
+ * Copyright (c) 2006-2018, RT-Thread Development Team
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * Change Logs:
+ * Date Author Notes
+ * 2018-01-26 armink the first version
+ */
+
+#include <fal.h>
+#include <sfud.h>
+
+#ifdef FAL_USING_SFUD_PORT
+#ifdef RT_USING_SFUD
+#include <spi_flash_sfud.h>
+#endif
+
+#ifndef FAL_USING_NOR_FLASH_DEV_NAME
+#define FAL_USING_NOR_FLASH_DEV_NAME "norflash0"
+#endif
+
+static int init(void);
+static int read(long offset, uint8_t *buf, size_t size);
+static int write(long offset, const uint8_t *buf, size_t size);
+static int erase(long offset, size_t size);
+
+static sfud_flash_t sfud_dev = NULL;
+struct fal_flash_dev nor_flash0 =
+{
+ .name = FAL_USING_NOR_FLASH_DEV_NAME,
+ .addr = 0,
+ .len = 8 * 1024 * 1024,
+ .blk_size = 4096,
+ .ops = {init, read, write, erase},
+ .write_gran = 1
+};
+
+static int init(void)
+{
+
+#ifdef RT_USING_SFUD
+ /* RT-Thread RTOS platform */
+ sfud_dev = rt_sfud_flash_find_by_dev_name(FAL_USING_NOR_FLASH_DEV_NAME);
+#else
+ /* bare metal platform */
+ extern sfud_flash sfud_norflash0;
+ sfud_dev = &sfud_norflash0;
+#endif
+
+ if (NULL == sfud_dev)
+ {
+ return -1;
+ }
+
+ /* update the flash chip information */
+ nor_flash0.blk_size = sfud_dev->chip.erase_gran;
+ nor_flash0.len = sfud_dev->chip.capacity;
+
+ return 0;
+}
+
+static int read(long offset, uint8_t *buf, size_t size)
+{
+ assert(sfud_dev);
+ assert(sfud_dev->init_ok);
+ sfud_read(sfud_dev, nor_flash0.addr + offset, size, buf);
+
+ return size;
+}
+
+static int write(long offset, const uint8_t *buf, size_t size)
+{
+ assert(sfud_dev);
+ assert(sfud_dev->init_ok);
+ if (sfud_write(sfud_dev, nor_flash0.addr + offset, size, buf) != SFUD_SUCCESS)
+ {
+ return -1;
+ }
+
+ return size;
+}
+
+static int erase(long offset, size_t size)
+{
+ assert(sfud_dev);
+ assert(sfud_dev->init_ok);
+ if (sfud_erase(sfud_dev, nor_flash0.addr + offset, size) != SFUD_SUCCESS)
+ {
+ return -1;
+ }
+
+ return size;
+}
+#endif /* FAL_USING_SFUD_PORT */
+
diff --git a/components/fal/samples/porting/fal_flash_stm32f2_port.c b/components/fal/samples/porting/fal_flash_stm32f2_port.c
new file mode 100644
index 0000000000..ed2c2c045a
--- /dev/null
+++ b/components/fal/samples/porting/fal_flash_stm32f2_port.c
@@ -0,0 +1,198 @@
+/*
+ * Copyright (c) 2006-2018, RT-Thread Development Team
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * Change Logs:
+ * Date Author Notes
+ * 2018-01-26 armink the first version
+ */
+
+#include <fal.h>
+
+#include <stm32f2xx.h>
+
+/* base address of the flash sectors */
+#define ADDR_FLASH_SECTOR_0 ((uint32_t)0x08000000) /* Base address of Sector 0, 16 K bytes */
+#define ADDR_FLASH_SECTOR_1 ((uint32_t)0x08004000) /* Base address of Sector 1, 16 K bytes */
+#define ADDR_FLASH_SECTOR_2 ((uint32_t)0x08008000) /* Base address of Sector 2, 16 K bytes */
+#define ADDR_FLASH_SECTOR_3 ((uint32_t)0x0800C000) /* Base address of Sector 3, 16 K bytes */
+#define ADDR_FLASH_SECTOR_4 ((uint32_t)0x08010000) /* Base address of Sector 4, 64 K bytes */
+#define ADDR_FLASH_SECTOR_5 ((uint32_t)0x08020000) /* Base address of Sector 5, 128 K bytes */
+#define ADDR_FLASH_SECTOR_6 ((uint32_t)0x08040000) /* Base address of Sector 6, 128 K bytes */
+#define ADDR_FLASH_SECTOR_7 ((uint32_t)0x08060000) /* Base address of Sector 7, 128 K bytes */
+#define ADDR_FLASH_SECTOR_8 ((uint32_t)0x08080000) /* Base address of Sector 8, 128 K bytes */
+#define ADDR_FLASH_SECTOR_9 ((uint32_t)0x080A0000) /* Base address of Sector 9, 128 K bytes */
+#define ADDR_FLASH_SECTOR_10 ((uint32_t)0x080C0000) /* Base address of Sector 10, 128 K bytes */
+#define ADDR_FLASH_SECTOR_11 ((uint32_t)0x080E0000) /* Base address of Sector 11, 128 K bytes */
+
+/**
+ * Get the sector of a given address
+ *
+ * @param address flash address
+ *
+ * @return The sector of a given address
+ */
+static uint32_t stm32_get_sector(uint32_t address)
+{
+ uint32_t sector = 0;
+
+ if ((address < ADDR_FLASH_SECTOR_1) && (address >= ADDR_FLASH_SECTOR_0))
+ {
+ sector = FLASH_Sector_0;
+ }
+ else if ((address < ADDR_FLASH_SECTOR_2) && (address >= ADDR_FLASH_SECTOR_1))
+ {
+ sector = FLASH_Sector_1;
+ }
+ else if ((address < ADDR_FLASH_SECTOR_3) && (address >= ADDR_FLASH_SECTOR_2))
+ {
+ sector = FLASH_Sector_2;
+ }
+ else if ((address < ADDR_FLASH_SECTOR_4) && (address >= ADDR_FLASH_SECTOR_3))
+ {
+ sector = FLASH_Sector_3;
+ }
+ else if ((address < ADDR_FLASH_SECTOR_5) && (address >= ADDR_FLASH_SECTOR_4))
+ {
+ sector = FLASH_Sector_4;
+ }
+ else if ((address < ADDR_FLASH_SECTOR_6) && (address >= ADDR_FLASH_SECTOR_5))
+ {
+ sector = FLASH_Sector_5;
+ }
+ else if ((address < ADDR_FLASH_SECTOR_7) && (address >= ADDR_FLASH_SECTOR_6))
+ {
+ sector = FLASH_Sector_6;
+ }
+ else if ((address < ADDR_FLASH_SECTOR_8) && (address >= ADDR_FLASH_SECTOR_7))
+ {
+ sector = FLASH_Sector_7;
+ }
+ else if ((address < ADDR_FLASH_SECTOR_9) && (address >= ADDR_FLASH_SECTOR_8))
+ {
+ sector = FLASH_Sector_8;
+ }
+ else if ((address < ADDR_FLASH_SECTOR_10) && (address >= ADDR_FLASH_SECTOR_9))
+ {
+ sector = FLASH_Sector_9;
+ }
+ else if ((address < ADDR_FLASH_SECTOR_11) && (address >= ADDR_FLASH_SECTOR_10))
+ {
+ sector = FLASH_Sector_10;
+ }
+ else
+ {
+ sector = FLASH_Sector_11;
+ }
+
+ return sector;
+}
+
+/**
+ * Get the sector size
+ *
+ * @param sector sector
+ *
+ * @return sector size
+ */
+static uint32_t stm32_get_sector_size(uint32_t sector) {
+ assert(IS_FLASH_SECTOR(sector));
+
+ switch (sector) {
+ case FLASH_Sector_0: return 16 * 1024;
+ case FLASH_Sector_1: return 16 * 1024;
+ case FLASH_Sector_2: return 16 * 1024;
+ case FLASH_Sector_3: return 16 * 1024;
+ case FLASH_Sector_4: return 64 * 1024;
+ case FLASH_Sector_5: return 128 * 1024;
+ case FLASH_Sector_6: return 128 * 1024;
+ case FLASH_Sector_7: return 128 * 1024;
+ case FLASH_Sector_8: return 128 * 1024;
+ case FLASH_Sector_9: return 128 * 1024;
+ case FLASH_Sector_10: return 128 * 1024;
+ case FLASH_Sector_11: return 128 * 1024;
+ default : return 128 * 1024;
+ }
+}
+static int init(void)
+{
+ /* do nothing now */
+}
+
+static int read(long offset, uint8_t *buf, size_t size)
+{
+ size_t i;
+ uint32_t addr = stm32f2_onchip_flash.addr + offset;
+ for (i = 0; i < size; i++, addr++, buf++)
+ {
+ *buf = *(uint8_t *) addr;
+ }
+
+ return size;
+}
+
+static int write(long offset, const uint8_t *buf, size_t size)
+{
+ size_t i;
+ uint32_t read_data;
+ uint32_t addr = stm32f2_onchip_flash.addr + offset;
+
+ FLASH_Unlock();
+ FLASH_ClearFlag(
+ FLASH_FLAG_EOP | FLASH_FLAG_OPERR | FLASH_FLAG_WRPERR | FLASH_FLAG_PGAERR | FLASH_FLAG_PGPERR
+ | FLASH_FLAG_PGSERR);
+ for (i = 0; i < size; i++, buf++, addr++)
+ {
+ /* write data */
+ FLASH_ProgramByte(addr, *buf);
+ read_data = *(uint8_t *) addr;
+ /* check data */
+ if (read_data != *buf)
+ {
+ return -1;
+ }
+ }
+ FLASH_Lock();
+
+ return size;
+}
+
+static int erase(long offset, size_t size)
+{
+ FLASH_Status flash_status;
+ size_t erased_size = 0;
+ uint32_t cur_erase_sector;
+ uint32_t addr = stm32f2_onchip_flash.addr + offset;
+
+ /* start erase */
+ FLASH_Unlock();
+ FLASH_ClearFlag(
+ FLASH_FLAG_EOP | FLASH_FLAG_OPERR | FLASH_FLAG_WRPERR | FLASH_FLAG_PGAERR | FLASH_FLAG_PGPERR
+ | FLASH_FLAG_PGSERR);
+ /* it will stop when erased size is greater than setting size */
+ while (erased_size < size)
+ {
+ cur_erase_sector = stm32_get_sector(addr + erased_size);
+ flash_status = FLASH_EraseSector(cur_erase_sector, VoltageRange_3);
+ if (flash_status != FLASH_COMPLETE)
+ {
+ return -1;
+ }
+ erased_size += stm32_get_sector_size(cur_erase_sector);
+ }
+ FLASH_Lock();
+
+ return size;
+}
+
+const struct fal_flash_dev stm32f2_onchip_flash =
+{
+ .name = "stm32_onchip",
+ .addr = 0x08000000,
+ .len = 1024*1024,
+ .blk_size = 128*1024,
+ .ops = {init, read, write, erase},
+ .write_gran = 8
+};
+