SPINOR API¶

REVISION HISTORY¶

Revision No.	Description	Date
1.0	Initial release	11/18/2024
1.1	Update the template and add API descriptions	11/25/2025

1. Overview¶

SPINOR is a NOR flash that uses SPI for data access.

This article mainly introduces data access to SPINOR 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 five gears: 12Mhz, 54Mhz, 86Mhz, 104Mhz and 108Mhz

Supports maximum 80Mhz clock 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 |

3. Hardware connection diagram¶

4. Rtos usage reference¶

4.1. Rtos Config configuration¶

Rtos uses SPINOR, which requires configuration:

CONFIG_FSP_QSPI_SUPPORT=y
CONFIG_FLASH_SUPPORT=y
CONFIG_SSTAR_NOR=y

Enter the rtos/proj directory,make menuconfig select config as follows:

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

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

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. spinor node configuration¶

<norflash0>
    [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 SPINOR, which requires configuration:

CONFIG_FSP_QSPI_SUPPORT=y
CONFIG_FLASH_SUPPORT=y
CONFIG_SSTAR_NOR=y

Enter the kernel directory,make menuconfig select config as follows:

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

Device Drivers  --->
    [*] Sstar SoC platform drivers  --->
        <*>   SigmaStar FLASH
        <*>     SPINOR

5.2.1. dtsi node description¶

5.2.1. fsp_qspi node configuration¶

fsp-qspi0 {
    compatible = "sstar,fsp-qspi";
    reg = <0x1F201A00 0x200>, <0x1F201C00 0x200>;
    clocks = <&CLK_fsp_qspi>, <&CLK_spi_nonpm>, <&CLK_spi_synth_pll>;
    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
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. spinor node configuration¶

norflash0 {
    compatible = "sstar-norflash";
    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
sstar_part_mark_active	Mark the boot partition
sstar_part_get	Get partition information
sstar_part_get_active	Get primary partition information
sstar_part_get_nm	Obtain partition information based on partition number
sstar_part_get_nm_by_dev	Obtain partition information based on device name and partition number
sstar_part_get_dev	Retrieve partition information based on device name
sstar_part_is_support_xzdec	Determine whether xz decompression is supported
sstar_part_load	Read partition data
sstar_part_load_to_xzdec	Read partition data and perform xz decompression
sstar_part_program	Write data to the partition
sstar_part_erase	Erase partition data
sstar_part_block_isbad	Determine whether a certain location of the partition is a bad block

6.2.1. sstar_part_mark_active¶

Function

Mark the boot partition

Syntax

u8 sstar_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. sstar_part_get¶

Function

Get partition information

Syntax

u8 sstar_part_get(u8 *part_name, u8 trunk, struct sstar_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. sstar_part_get_active¶

Function

Get primary partition information

Syntax

u8 sstar_part_get_active(u8 *part_name, struct sstar_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. sstar_part_get_nm¶

Function

Obtain partition information based on partition number

Syntax

u8 sstar_part_get_nm(u8 part_id, struct sstar_part *part);

Parameters

Parameter name Description Input/Output

part_id Partition number Input

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

6.2.5. sstar_part_get_nm_by_dev¶

Function

Obtain partition information based on device name and partition number

Syntax

u8 sstar_part_get_nm_by_dev(u8 *dev_name, u8 part_id, struct sstar_part *part);

Parameters

Parameter name Description Input/Output

dev_name Device name Input

part_id Partition number Input

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

6.2.6. sstar_part_get_dev¶

Function

Retrieve partition information based on device name

Syntax

u8 sstar_part_get_dev(u8 *dev_name, struct sstar_part *part);

Parameters

Parameter name Description Input/Output

dev_name Device name Input

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

6.2.7. sstar_part_is_support_xzdec¶

Function

Determine whether xz decompression is supported

Syntax

u8 sstar_part_is_support_xzdec(struct sstar_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.8. sstar_part_load¶

Function

Read partition data

Syntax

u32 sstar_part_load(struct sstar_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.9. sstar_part_load_to_xzdec¶

Function

Read partition data and perform xz decompression

Syntax

u32 sstar_part_load_to_xzdec(struct sstar_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.10. sstar_part_program¶

Function

Write data to partition

Syntax

u32 sstar_part_program(struct sstar_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.11. sstar_part_erase¶

Functions

Erase data from a partition

Syntax

u32 sstar_part_erase(struct sstar_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.12. sstar_part_block_isbad¶

Function

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

Syntax

u32 sstar_part_block_isbad(struct sstar_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
sstar_part	Function-related configuration
sstar_part_device	Row offset configuration

7.1. sstar_part¶

Description

Record partition information.

Definition

struct sstar_part
{
    u8                        trunk;
    u8                        backup_trunk;
    u32                       offset;
    u32                       size;
    u32                       block_size;
    const u8 *                part_name;
    struct sstar_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 sstar_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

Parameter name	Description	Input/Output
part_id	Partition number	Input
part	Partition information structure	Output

Parameter name	Description	Input/Output
dev_name	Device name	Input
part_id	Partition number	Input
part	Partition information structure	Output