当前文档版本为 v0.8.0,您可以访问当前页面的 开发中 版本以获取最近可能的更新。

Driver: Flash Shell

1 功能概述

本文主要介绍PAN1080 EVB板flash shell演示,可以通过类shell命令来实现flash api的相关操作。

2 环境要求

  • PAN1080 EVB 一块

  • USB-TypeC 线一条(用于供电和查看串口打印 Log)

  • 硬件接线:

    • 使用USB线,将 PC USB 与 EVB USB-TypeC(USB->UART)相连

    • 根据 EVB 核心板芯片的封装不同,使用杜邦线将 EVB 底板上的:

      • TX0 与 P00 相连, RX0 与 P01 相连(若 EVB 板芯片为 QFN32 或 LQFP64 封装)

      • TX0 与 P30 相连, RX0 与 P31 相连(若 EVB 板芯片为 QFN48 封装)

  • PC 软件: 串口调试助手(UartAssist)或终端工具(SecureCRT),波特率921600

3 编译和烧录

项目位置:zephyr\samples_panchip\drivers\flash_shell

使用 ZAL 工具可以对其进行编译、烧录、打开 VS Code 调试等操作。关于 ZAL 工具的详细介绍请参考:Zephyr APP Launcher 工具介绍

4 演示说明

通过串口命令输入flash_cmd命令来实现flash api操作,通过连续两个tab会自动补全命令,例如输入flash_cmd后,则shell会输出flash_cmd相关细指令。

详情参考5.1 flash_shell支持的命令5.2 flash_cmd使用以及命令解析.

5 开发说明

5.1 flash_shell支持的命令

flash_cmd - Flash related commands.
Subcommands:
  erase             :<off> <len>
                     Erase <len> bytes from device offset <off>, subject to
                     hardware page limitations.
  page_count        :Print the number of pages on the flash device.
  page_erase        :<page> [num]
                     Erase [num] pages (default 1), starting at page <page>.
  page_layout       :[start_page] [end_page]
                     Print layout of flash pages in the range [start_page,
                     end_page], which is inclusive. By default, all pages are
                     printed.
  page_read         :<page> <len> OR <page> <off> <len>
                     Read <len> bytes from given page, starting at page offset
                     <off>,or offset 0 if not given. No checks are made that
                     bytes read are all within the page.
  page_write        :<page> <off> <byte1> [... byteN]
                     Write given bytes to given page, starting at page offset
                     <off>. No checks are made that the bytes all fall within
                     the page. Pages must be erased before they can be written.
  read              :<off> <len>
                     Read <len> bytes from device offset <off>.
  set_device        :<device_name>
                     Set flash device by name. If a flash device was not found,
                     this command must be run first to bind a device to this
                     module.
  write             :<off> <byte1> [... byteN]
                     Write given bytes, starting at device offset <off>.
                     Pages must be erased before they can be written.
  write_block_size  :Print the device's write block size. This is the smallest
                     amount of data which may be written to the device, in
                     bytes.
  write_unaligned   :<off> <byte1> [... byteN]
                     Write given bytes, starting at device offset <off>.
                     Being unaligned, affected memory areas are backed up,
                     erased, protected and then overwritten.
                     This command is designed to test writing to large flash
                     pages.
  write_pattern     :<off> <len>
                     Writes a pattern of (0x00 0x01 .. 0xFF 0x00 ..) of
                     length<len> at the offset <off>.
                     Unaligned writing is used, i.e. protection and erasing are
                     automated.This command is designed to test writing to large
                     flash pages.

5.2 flash_cmd使用以及命令解析

5.2.1 使用flash_cmd read 读取地址0x1000处16个字节

uart:~$ flash_cmd read 0x1000 0x10
53 46 1d 68 | af 68 fb 68 |00 2b 04 d0 | 00 21 28 00

5.2.2 使用flash_cmd write 写入地址0xc8000处4个字节

uart:~$ flash_cmd read 0xc8000 0x4					//从800K地址处读取4个字节,因为该地址正常没写入过,默认为全ff
ff ff ff ff
uart:~$ flash_cmd write 0xc8000 0x1 0x2 0x3 0x4		//从800K地址处写入4个字节:0x1 0x2 0x3 0x4
Reading back written bytes:
01 02 03 04
uart:~$ flash_cmd read 0xc8000 0x4					//从800K地址处读取4个字节:0x1 0x2 0x3 0x4
01 02 03 04

5.2.3 使用flash_cmd erase 擦除地址0xc8000处4K字节

uart:~$ flash_cmd erase 0xc8000 0x1000				//从800K地址处擦除4K字节,默认擦写必须4K对齐,这个可以使用flash_cmd write_block_size
													//获得,该值默认在dts中定义。
uart:~$ flash_cmd read 0xc8000 0x4
ff ff ff ff

5.2.4 flash_cmd read命令代码解析

flash_cmd所有的命令均在下面,从SHELL_CMD_ARG(read, NULL, READ_HELP, cmd_read, 3, 0)我们可以知道read命令对应的实现函数,在cmd_read中。

SHELL_STATIC_SUBCMD_SET_CREATE(sub_flash,
	/* Alphabetically sorted to ensure correct Tab autocompletion. */
	SHELL_CMD_ARG(erase,	NULL,	ERASE_HELP,	cmd_erase, 3, 0),
#ifdef CONFIG_FLASH_PAGE_LAYOUT
	SHELL_CMD_ARG(page_count,  NULL, PAGE_COUNT_HELP, cmd_page_count, 1, 0),
	SHELL_CMD_ARG(page_erase, NULL, PAGE_ERASE_HELP, cmd_page_erase, 2, 1),
	SHELL_CMD_ARG(page_layout, NULL, PAGE_LAYOUT_HELP,
		      cmd_page_layout, 1, 2),
	SHELL_CMD_ARG(page_read,   NULL, PAGE_READ_HELP,  cmd_page_read, 3, 1),
	SHELL_CMD_ARG(page_write,  NULL, PAGE_WRITE_HELP,
		      cmd_page_write, 3, 255),
#endif
	SHELL_CMD_ARG(read,		NULL,	READ_HELP,	cmd_read, 3, 0),
	SHELL_CMD_ARG(set_device, NULL, SET_DEV_HELP, cmd_set_dev, 2, 0),
	SHELL_CMD_ARG(write,	  NULL,	WRITE_HELP,	cmd_write, 3, 255),
	SHELL_CMD_ARG(write_block_size,	NULL,	WRITE_BLOCK_SIZE_HELP,
						    cmd_write_block_size, 1, 0),
	SHELL_CMD_ARG(write_unaligned,  NULL,	WRITE_UNALIGNED_HELP,
							cmd_write_unaligned, 3, 255),
	SHELL_CMD_ARG(write_pattern,	NULL,	WRITE_PATTERN_HELP,
							cmd_write_pattern, 3, 255),
	SHELL_SUBCMD_SET_END /* Array terminated. */
);

SHELL_CMD_REGISTER(flash_cmd, &sub_flash, "Flash related commands.", NULL);

5.3 Flash API使用参考

5.3.1 flash_read API参考

cmd_read也是调用do_read函数,对于flash_read函数我们可以参考do_read函数:

/* Read bytes, dumping contents to console and printing on error. */
static int do_read(const struct shell *shell, off_t offset, size_t len)
{
	uint8_t buf[64];
	int ret;

	while (len > sizeof(buf)) {
		ret = flash_read(flash_device, offset, buf, sizeof(buf));
		if (ret) {
			goto err_read;
		}
		dump_buffer(shell, buf, sizeof(buf));
		len -= sizeof(buf);
		offset += sizeof(buf);
	}
	ret = flash_read(flash_device, offset, buf, len);
	if (ret) {
		goto err_read;
	}
	dump_buffer(shell, buf, len);
	return 0;

 err_read:
	PR_ERROR(shell, "flash_read error: %d\n", ret);
	return ret;
}

5.3.2 flash_write API参考

/* Write bytes and printing on error. */
static int do_write(const struct shell *shell, off_t offset, uint8_t *buf,
		    size_t len, bool read_back)
{
	int ret;

	ret = flash_write(flash_device, offset, buf, len);
	if (ret) {
		PR_ERROR(shell, "flash_write failed (err:%d).\n", ret);
		return ret;
	}

	if (read_back) {
		PR_SHELL(shell, "Reading back written bytes:\n");
		ret = do_read(shell, offset, len);
	}
	return ret;
}

5.3.3 flash_erase API参考

/* Erase area and printing on error. */
static int do_erase(const struct shell *shell, off_t offset, size_t size)
{
	int ret;

	ret = flash_erase(flash_device, offset, size);
	if (ret) {
		PR_ERROR(shell, "flash_erase failed (err:%d).\n", ret);
		return ret;
	}

	return ret;
}

5.3.4 do_write_unaligned 非对齐地址写参考实现

static int do_write_unaligned(const struct shell *shell, off_t offset, uint8_t *buf,
		    size_t len, bool read_back)
{
	int ret = 0;
	size_t page_size = flash_get_write_block_size(flash_device);
	size_t size_before = offset % page_size;
	size_t size_after = page_size - ((size_before + len) % page_size);
	size_t aligned_size = size_before + len + size_after;
	off_t  start_page = offset - size_before;
	off_t  last_page = start_page + aligned_size - page_size;
	bool single_page_write = (size_before + len < page_size);

	char *before_data;
	char *after_data;

	if (0 == size_before && 0 == size_after) {
		/* Aligned write */
		flash_erase(flash_device, offset, len);
		flash_write(flash_device, offset, buf, len);

		return 0;
	}

	before_data = k_malloc(page_size);
	after_data = k_malloc(page_size);

	if (!before_data || !after_data) {
		PR_ERROR(shell, "No heap memory for flash manipulation\n");
		ret = -ENOMEM;
		goto free_buffers;
	}

	/* Stash useful data from the pages that will be affected. */
	if (single_page_write) {
		/* Read old data before new data is written. */
		if (size_before) {
			flash_read(flash_device, start_page, before_data, size_before);
		}
		/* Fill the with new data. */
		memcpy(before_data + size_before, buf, len);
		/* Fill the last part of old data. */
		if (size_after) {
			flash_read(flash_device, offset + len,
					before_data + size_before + len,
					size_after);
		}
	} else {
		/* Multipage write, different start and end pages. */
		if (size_before) {
			flash_read(flash_device, start_page, before_data,
					size_before);
			/* Fill the rest with new data. */
			memcpy(before_data + size_before, buf,
			       page_size - size_before);
		}
		if (size_after) {
			/* Copy ending part of new data. */
			memcpy((void *)after_data,
			       (void *)(buf + len -
				   ((len + size_before) % page_size)),
			       page_size - size_after);
			/* Copy ending part of flash page. */
			flash_read(flash_device, offset + len,
					after_data + (page_size - size_after),
					size_after);
		}
	}

	/* Erase all the pages that overlap with new data. */
	flash_erase(flash_device, start_page, aligned_size);

	/* Write stashed and new data. */
	if (single_page_write || size_before > 0) {
		/* Write first page if available. */
		flash_write(flash_device, start_page, before_data,
				 page_size);
	}
	if (!single_page_write) {
		size_t middle_data_len = aligned_size;
		off_t middle_page_start = start_page;
		off_t data_offset = (off_t)buf;

		/* Write the middle bit if available */
		if (size_before > 0) {
			middle_page_start += page_size;
			middle_data_len -= page_size;
			data_offset += (page_size - size_before);
		}
		if (size_after > 0) {
			middle_data_len -= page_size;
		}
		if (middle_data_len > 0) {
			flash_write(flash_device, middle_page_start,
					 (const void *)data_offset,
					 middle_data_len);
		}

		/* Write the last page if needed. */
		if (size_after > 0) {
			flash_write(flash_device, last_page, after_data,
					 page_size);
		}
	}

	if (read_back) {
		PR_SHELL(shell, "Reading back written bytes:\n");
		ret = do_read(shell, offset, len);
	}

free_buffers:
	k_free(before_data);
	k_free(after_data);

	return ret;
}

6 RAM/Flash资源使用情况

Memory region         Used Size  Region Size  %age Used
FLASH:       70496 B       256 KB     26.89%
SRAM:       36640 B        64 KB     55.91%