SPINAND API¶

REVISION HISTORY¶

Revision No.	Description	Date
1.0	Initial release	11/18/2024

1. Overview¶

SPINAN is a NAND flash that uses SPI for data access.

This article mainly introduces data access to SPINAND flash under Rtos and Linux systems.

2. Hardware functions¶

The controller comes with two chip selects and supports GPIO chip selects, which can be operated in multiple flashes in time-sharing mode
Supports continue read mode
Supports four-wire read and write mode
The clock supports four gears: 12Mhz, 54Mhz, 86Mhz, and 108Mhz
Not support DTR fast reading, and the status of different chips is as follows

chipname DTR support status

iford yes

souffle yes

ifado no

pcupid no

ibopper no

ifackel yes

ihalo yes

mhera no

3. Hardware connection diagram¶

4. Rtos usage reference¶

4.1. Rtos Config configuration¶

Rtos uses SPINAND, which requires configuration:

CONFIG_FSP_QSPI_SUPPORT=y
CONFIG_FLASH_SUPPORT=y
CONFIG_SGS_NAND=y

The configuration selected by menuconfig is as follows:

BSP Driver Options  --->
    [*] Support fsp_qspi driver

BSP Driver Options  --->
    [*] Support Flash driver
    [*]   SPINAND

4.2. Rtos SYS configuration¶

4.2.1. fsp_qspi node configuration¶

<fsp_qspi0>
    [cs_num_u8] 2;
    [cs_mode_u8] 0;
    [engine_u8] 0;
    [ext_num_u8] 0;
    [cs_ext_u32] 0;
    [dma_u8] 1;
    [reg_u32_u16] 0x1F201A00 0x100, 0x1F201C00 0x100;

Attribute	Description	Remark
cs_num_u8	Used to mark the number of chip selects that the controller comes with	No need to modify
cs_mode_u8	Used to specify whether cs uses software or hardware control	Can be modified as needed
engine_u8	Used to specify the controller number	Modification is prohibited
ext_num_u8	Used to specify the number of GPIOs used as chip selects	Can be modified as needed
cs_ext_u32	Used to specify the pad index to be used in addition to the cs that comes with the Engine	Used with ext_num
dma_u8	Used to specify whether to enable DMA mode	Can be modified as needed
reg_u32_u16	Used to specify the bank address of the fspi and qspi registers	No need to modify

4.2.2. spinand node configuration¶

<nandflash0>
    [engine_u8] 0;
    [cs_select_u8] 0;

Attribute	Description	Remark
engine_u8	Used to specify the controller number to be used	No need to modify
cs_select_u8	Used to specify the chip select number to be used	No need to modify

5. Linux usage reference¶

5.1. Linux Config configuration¶

Linux uses SPINAND, which requires configuration:

CONFIG_FSP_QSPI_SUPPORT=y
CONFIG_FLASH_SUPPORT=y
CONFIG_SGS_NAND=y

The configuration selected by menuconfig is as follows:

Device Drivers  --->
    [*] Sgs SoC platform drivers  --->
        <*>   Sgs FSP-QSPI Driver

Device Drivers  --->
    [*] Sgs SoC platform drivers  --->
        <*>   Sgs FLASH
        <*>     SPINAND

5.2. dtsi node description¶

5.2.1. fsp_qspi node configuration¶

fsp-qspi0 {
    compatible = "sgs,fsp-qspi";
    reg = <0x0 0x1F201A00 0x200>, <0x0 0x1F201C00 0x200>;
    interrupts = <GIC_SPI INT_IRQ_NONPM_FSP IRQ_TYPE_LEVEL_HIGH>;
    auto-check = <1>;
    clocks = <&CLK_fsp_qspi>;
    cs-num = <2>;
    cs-mode = <0>;
    cs-ext = <PAD_GPIO0>;
    engine = <0>;
    dma = <1>;
    status = "ok";
};

Attribute	Description	Remark
compatible	Used to match the driver for driver registration, must be consistent with the code	Modification prohibited
reg	Used to specify the address of the fsp qspi register bank	No modification required
clocks	Used to specify the clock source to be used	No modification required
auto-check	Used to enable automatic flash OIP detection in FSP hardware	Can be modified as needed
cs-num	Used to mark the number of chip selects built into the controller	No modification required
cs-mode	Used to specify whether cs uses software or hardware control	Can be modified as needed
cs-ext	Used to specify the pad index to be used in addition to the cs built into the Engine	Can be modified as needed
engine	Used to specify the controller number	No need to change
dma	Used to specify whether to enable DMA mode	Can be modified as needed
status	Used to specify whether to enable fsp qspi driver	Can be modified as needed

5.2.2. spinand node configuration¶

nandflash0 {
    compatible = "sgs-nandflash";
    engine = <0>;
    cs-select = <0>;
    status = "ok";
};

Attribute	Description	Remark
compatible	Used to match the driver for driver registration, must be consistent with the code	Modification prohibited
engine	Used to specify the controller number	No need to change
cs-select	Used to specify the chip select number used	No need to modify
status	Used to specify whether to enable fsp qspi driver	Can be modified as needed

6. API reference¶

6.1. Linux usage¶

Linux usage connects to standard MTD devices and accesses flash according to the MTD operation method.

6.2. Rtos usage¶

Rtos path: proj/sc/driver/sysdriver_common/flash/drv_part.h

API name	Function
sgs_part_mark_active	Mark the boot partition
sgs_part_get	Get partition information
sgs_part_get_active	Get primary partition information
sgs_part_is_support_xzdec	Determine whether xz decompression is supported
sgs_part_load	Read partition data
sgs_part_load_to_xzdec	Read partition data and perform xz decompression
sgs_part_program	Write data to the partition
sgs_part_erase	Erase partition data
sgs_part_block_isbad	Determine whether a certain location of the partition is a bad block

6.2.1. sgs_part_mark_active¶

Function

Mark the boot partition

Syntax

u8 sgs_part_mark_active(u8 *part_name, u8 trunk);

Parameters

Parameter name Description Input/Output

part_name Partition name Input

trunk Primary/backup partition flag Input
Return value
- 0: Failed.
- Non-0: Successful.
Dependencies
- Header file: drv_part.h

6.2.2. sgs_part_get¶

Function

Get partition information

Syntax

u8 sgs_part_get(u8 *part_name, u8 trunk, struct sgs_part *part);

Parameters

Parameter name Description Input/Output

part_name Partition name Input

trunk Primary/backup partition flag Input

part Partition information structure Output
Return value
- 0: Failed.
- 1: Successful.
Dependencies
- Header file: drv_part.h

6.2.3. sgs_part_get_active¶

Function

Get primary partition information

Syntax

u8 sgs_part_get_active(u8 *part_name, struct sgs_part *part);

Parameters

Parameter name Description Input/Output

part_name Partition name Input

part Partition information structure Output
Return value
- 0: Failed.
- 1: Successful.
Dependencies
- Header file: drv_part.h

6.2.4. sgs_part_is_support_xzdec¶

Function

Determine whether xz decompression is supported

Syntax

u8 sgs_part_is_support_xzdec(struct sgs_part *part);

Return value
- 0: Not supported.
- 1: Supported.
Parameters

Parameter name Description Input/Output

part Partition information structure Input
Dependencies
- Header file: drv_part.h

6.2.5. sgs_part_load¶

Function

Read partition data

Syntax

u32 sgs_part_load(struct sgs_part *part, u32 u32_offset, u8 *pu8_data, u32 u32_size);

Return value
- 0: Failed.
- u32_size: Success.

Parameters

Parameter name	Description	Input/output
part	Partition information structure	Input
u32_offset	Offset within partition	Input
pu8_data	Data storage BUFF	Input
u32_size	Data read size	Input

Dependencies
- Header file: drv_part.h

6.2.6. sgs_part_load_to_xzdec¶

Function

Read partition data and perform xz decompression

Syntax

u32 sgs_part_load_to_xzdec(struct sgs_part *part, u32 u32_offset, u8 *pu8_data, u32 u32_size);

Return value
- 0: Failed.
- u32_size: Success.

Parameters

Parameter name	Description	Input/output
part	Partition information structure	Input
u32_offset	Offset within partition	Input
pu8_data	Data storage BUFF	Input
u32_size	Data read size	Input

Dependencies
- Header file: drv_part.h

6.2.7. sgs_part_program¶

Function

Write data to partition

Syntax

u32 sgs_part_program(struct sgs_part *part, u32 u32_offset, u8 *pu8_data, u32 u32_size);

Return value
- 0: Failed.
- u32_size: Success.

Parameters

Parameter name	Description	Input/output
part	Partition information structure	Input
u32_offset	Offset within partition	Input
pu8_data	Data storage BUFF	Input
u32_size	Size of data written	Input

Dependencies
- Header file: drv_part.h
Notes
- The written range data must be erased first
- Erasing is done by block, the classic value is 0x20000, for example, erase address 0x20020, size 0x800, actual erased physical address 0x20000~0x40000

6.2.8. sgs_part_erase¶

Functions

Erase data from a partition

Syntax

u32 sgs_part_erase(struct sgs_part *part, u32 u32_offset, u32 u32_size);

Return value
- 0: Failed.
- u32_size: Success.
Parameters

Parameter name Description Input/Output

part Partition information structure Input

u32_offset Offset within partition Input

u32_size Size of data to be written Input
Dependencies
- Header file: drv_part.h
Notes
- Erase is done by block, the classic value is 0x20000, for example erase address 0x20020, size 0x800, actual erased physical address 0x20000~0x40000

6.2.9. sgs_part_block_isbad¶

Function

Determine whether a certain location in the partition is a bad block

Syntax

u32 sgs_part_block_isbad(struct sgs_part *part, u32 u32_offset);

Return value
- 0: Good block.
- 1: Bad block.
Parameters

Parameter name Description Input/output

part Partition information structure Input

u32_offset Offset within partition Input
Dependencies
- Header file: drv_part.h

7. Data structure description¶

The relevant data structure is defined as follows

Data type	Definition
sgs_part	Function-related configuration
sgs_part_device	Row offset configuration

7.1. sgs_part¶

Description

Record partition information.

Definition

struct sgs_part
{
    u8                        trunk;
    u8                        backup_trunk;
    u32                       offset;
    u32                       size;
    u32                       block_size;
    const u8 *                part_name;
    struct sgs_part_device *part_dev;
};

Members

Member name	Description
trunk	Primary partition flag
backup_trunk	Backup partition flag
offset	Partition offset
size	Partition size
block_size	Partition block size
part_name	Partition name
part_dev	Partition device structure

7.2. part_dev¶

Description

Partition device structure, recording partition operation methods.

Definition

struct sgs_part_device
{
    u8    engine;
    u8    cs_select;
    u8    xzdec_en;
    u8    dev_name[8];
    u32   capacity;
    u32   erase_size;
    void *handle;
    u32 (*read_skip_bad)(void *, u32, u32, u32, u8 *);
    u32 (*read_to_xzdec_skip_bad)(void *, u32, u32, u32, u8 *);
    u32 (*write_skip_bad)(void *, u32, u32, u32, u8 *);
    u32 (*erase_skip_bad)(void *, u32, u32, u32);
    u32 (*block_isbad)(void *, u32);
};

Members

Member name	Description
engine	Controller number used
cs_select	Chip select number used
xzdec_en	Support xz decompression
dev_name[8]	Partition device name
capacity	Total physical memory size
erase_size	Size of a block to be erased
handle	Private handle
(*read_skip_bad)	Read function
(*read_to_xzdec_skip_bad)	Read data and xz decompress function
(*write_skip_bad)	Write data function
(*erase_skip_bad)	Erase data function
(*block_isbad)	Bad block judgment function

8. Test case description¶

Linux reference: mtdutils usage (open source tool, available in the Linux development community)
Rtos reference: proj/sc/system/env_util/src/env_util.c

chipname	DTR support status
iford	yes
souffle	yes
ifado	no
pcupid	no
ibopper	no
ifackel	yes
ihalo	yes
mhera	no