v811_spc009/vendor/huanglong/uapi/flash/include/uapi_flash.h

/*
 * Copyright (c) Hisilicon Technologies Co., Ltd. 2020-2020. All rights reserved.
 * Description: IAPI head file for flash
 * Author: Hisilicon
 * Create: 2020-10-15
 */
#ifndef __UAPI_FLASH__H__
#define __UAPI_FLASH__H__

#include "td_type.h"

#ifdef __cplusplus
#if __cplusplus
extern "C" {
#endif
#endif /* __cplusplus */

#define FLASH_NAME_LEN 32 /* Flash Name max length */

#define INVALID_FD (-1)

/* Read and write without OOB, for example: kernel/uboot/ubi/cramfs.. */
#define UAPI_FLASH_RW_FLAG_RAW (0x0)
/* Read and write with OOB, example: yaffs2 file system image */
#define UAPI_FLASH_RW_FLAG_WITH_OOB (0x1)
/* Erase before write */
#define UAPI_FLASH_RW_FLAG_ERASE_FIRST (0x2)

/* This macro for return value when nand flash have bad block or valid length
 * less partition length.
 * CNcomment: 当nand有坏块时,读/写/擦除时,有效长度可能小于分区大小/打开长度,此时
 *            为了不越界,读/写/擦除完有效长度后,返回该值。 CNend
 */
#define UAPI_FLASH_END_DUETO_BADBLOCK (-10)

/* flash type */
typedef enum {
    UAPI_FLASH_TYPE_AUTO = 0x0,   /* Auto flash type */
    UAPI_FLASH_TYPE_NOR_0 = 0x1,  /* SPI NOR flash type */
    UAPI_FLASH_TYPE_NAND_0 = 0x4, /* NAND flash type */
    UAPI_FLASH_TYPE_EMMC_0 = 0x8, /* eMMC flash type */
    UAPI_FLASH_TYPE_UFS_0 = 0xC,  /* UFS flash type */
    UAPI_FLASH_TYPE_MAX           /* Invalid flash type */
} uapi_flash_type;

typedef enum {
    RD = 0x01,
    WR = 0x02
} pmode_t;

/* Flash partition access permission type */
typedef enum {
    ACCESS_NONE = 0,
    ACCESS_RD = (1 << RD),
    ACCESS_WR = (1 << WR),
    ACCESS_RDWR = (ACCESS_RD | ACCESS_WR),
    ACCESS_BUTT
} uapi_flash_access_perm;

/*
 * struct uapi_flash_partinfo - Flash partition descriptions
 * @start_addr: Partiton start address
 * @part_size:  Partition size
 * @dev_name:   The device node name where this partition
 * @part_name:  The partition name of this partition
 * @perm:       The partition access permission type
 */
typedef struct {
    td_u64 start_addr;
    td_u64 part_size;
    td_char dev_name[FLASH_NAME_LEN];
    td_char part_name[FLASH_NAME_LEN];
    uapi_flash_access_perm perm;
} uapi_flash_partinfo;

/*
 * struct uapi_flash_info - flash information
 * @total_size:  flash total size
 * @part_number: flash partition number
 * @block_size:  flash block size
 * @page_size:   flash page size
 * @oob_size:    flash OOB size
 * @open_addr:   flash open address
 * @open_len:    flash open length
 * @flash_type:  flash type
 * @part_info:   partition descriptions on this flash
 */
typedef struct {
    td_u64 total_size;
    td_u64 part_number;
    td_u64 open_addr;
    td_u64 open_len;
    td_u32 block_size;
    td_u32 page_size;
    td_u32 oob_size;
    uapi_flash_type flash_type;
    uapi_flash_partinfo *part_info;
} uapi_flash_info;

/*
 * Brief: Open flash partition by type and name
 * Note: partition name for spi/nand, use '/dev/mtdx' as partition name; use
 *       '/dev/mmcblk0px' as partion name for EMMC
 * CNcomment: 非EMMC器件(如SPI/NAND),只能用/dev/mtdx作为分区名。EMMC器件只
 * 能用/dev/mmcblk0px作为分区名。
 * attention N/A
 * param[in] flash_type Flash type CNcomment: flash类型 CNend
 * param[in] partition_name Partition name CNcomment: 分区名 CNend
 * retval :td_handle        Success. CNcomment:打开成功的flash句柄 CNend
 * retval :INVALID_FD       Failed.  CNcomment:失败 CNend
 * see N/A
 */
td_handle uapi_flash_open(uapi_flash_type flash_type, const td_char *partition_name);

/*
 * Brief: Open flash partition by type and name
 * Note: partition name for spi/nand, use '/dev/mtdx' as partition name; use
 *       '/dev/mmcblk0px' as partion name for EMMC
 * CNcomment: 非EMMC器件(如SPI/NAND),只能用/dev/mtdx作为分区名。EMMC器件只
 * 能用/dev/mmcblk0px作为分区名。
 * attention N/A
 * param[in] flash_type Flash type CNcomment: flash类型 CNend
 * param[in] address    Address offset CNcomment: 地址偏移位置 CNend
 * param[in] len        Open length    CNcomment: 操作flash的长度 CNend
 * retval :td_handle        Success. CNcomment:打开成功的flash句柄 CNend
 * retval :INVALID_FD       Failed.  CNcomment:失败 CNend
 * see N/A
 */
td_handle uapi_flash_open_by_addr(uapi_flash_type flash_type, td_u64 address, td_u64 len);

/*
 * Brief: Close opend flash handle
 * Note: partition name for spi/nand, use '/dev/mtdx' as partition name; use
 *       '/dev/mmcblk0px' as partion name for EMMC
 * CNcomment: 非EMMC器件(如SPI/NAND),只能用/dev/mtdx作为分区名。EMMC器件只
 * 能用/dev/mmcblk0px作为分区名。
 * attention N/A
 * param[in] handle      Flash handle CNcomment: flash句柄 CNend
 * retval :TD_SUCCESS       Success. CNcomment:成功 CNend
 * retval :TD_FAILURE       Failed.  CNcomment:失败 CNend
 * see N/A
 */
td_s32 uapi_flash_close(td_handle handle);

/*
 * Brief: Erase Flash partition
 * CNcomment: 擦除Flash分区
 * attention N/A
 * param[in] handle     Flash handle   CNcomment: flash句柄 CNend
 * param[in] offset     Address offset CNcomment: 地址偏移位置 CNend
 * param[in] len        Erase length   CNcomment: 擦除flash的长度 CNend
 * retval :TotalErase       Erase total length. CNcomment:成功擦除的长度 CNend
 * retval :TD_FAILURE       Failed.             CNcomment:失败 CNend
 * see N/A
 */
td_s64 uapi_flash_erase(td_handle handle, td_u64 offset, td_u64 len);

/*
 * Brief:  Read data from flash
 * CNcomment: 从Flash读数据
 * attention N/A
 * param[in] handle     Flash handle   CNcomment: flash句柄 CNend
 * param[in] offset     Address offset CNcomment: 地址偏移位置 CNend
 * param[in] buf        Data buffer pointer  CNcomment: 读数据的buffer指针 CNend
 * param[in] len        Read length          CNcomment: 读flash的长度 CNend
 * param[in] flags      Read flags, OOB flag use UAPI_FLASH_RW_FLAG_WITH_OOB if data
 *                      includes OOB data
 *                      CNcomment: 读flash的标志位,可取值 UAPI_FLASH_RW_FLAG_WITH_OOB，
 *                                 表示数据内容是否带 OOB 区 CNend
 * retval :TotalRead        Read total length.  CNcomment:成功读取的长度 CNend
 * retval :TD_FAILURE       Failed.             CNcomment:失败 CNend
 * retval :UAPI_FLASH_END_DUETO_BADBLOCK
 *                      Return when bad block exist, caller need to check the read result.
 *                      CNcomment: 读Flash遇到坏块结束(读完有效长度数据后,返回该值,
 *						           由用户判断成功与否) CNend
 */
td_s64 uapi_flash_read(td_handle handle, td_u64 offset, td_u8 *buf, td_u64 len, td_u32 flags);

/*
 * Brief: Write data to flash
 * CNcomment: 写数据到Flash
 * attention  1) forbidden used the function when yaffs filesystem is using
 *            2) can use UAPI_FLASH_RW_FLAG_ERASE_FIRST manner write flah , can write over
 *               all partition one time or write with block
 *            CNcomment:   1) 不能调用该接口更新当前正使用的yaffs文件系统
 *                         2) 调用该接口写Flash时，可以使用UAPI_FLASH_RW_FLAG_ERASE_FIRST，可以
 *                            一次写完也可以一块一块的写，但是当写yaffs2时，
 *                            必须先调用EXT_Flash_Erase把要写的分区完全擦除 CNend
 * param[in] handle     Flash handle   CNcomment: flash句柄 CNend
 * param[in] offset     Address offset CNcomment: 地址偏移位置 CNend
 * param[in] buf        Data buffer pointer  CNcomment: 写数据的buffer指针 CNend
 * param[in] len        Read length          CNcomment: 写flash的长度 CNend
 * param[in] flags      Write flags, OOB flag use UAPI_FLASH_RW_FLAG_WITH_OOB if data includes OOB data
 *                      CNcomment: 写flash的标志位,可取值UAPI_FLASH_RW_FLAG_WITH_OOB，表示数据内容是否
 *                                 带 OOB 区 CNend
 * retval :TotalWrite       Write total length.  CNcomment:成功读取的长度 CNend
 * retval :TD_FAILURE       Failed.              CNcomment:失败 CNend
 * retval :UAPI_FLASH_END_DUETO_BADBLOCK
 *                          Return when bad block exist, caller need to check the read result.
 *                          CNcomment: 读Flash遇到坏块结束(读完有效长度数据后,返回该值,由用户
 *                                     判断成功与否) CNend
 */
td_s64 uapi_flash_write(td_handle handle, td_u64 offset, td_u8 *buf, td_u64 len, td_u32 flags);

/*
 * Brief: Get flash information
 * CNcomment: 获取Flash器件的信息。
 * attention N/A
 * param[in] handle     Flash handle                CNcomment: flash句柄 CNend
 * param[out] flash_info Flash information pointer  CNcomment: 存储器件信息的指针 CNend
 * retval :TD_SUCCESS       Success. CNcomment:成功 CNend
 * retval :TD_FAILURE       Failed.  CNcomment:失败 CNend
 * see N/A
 */
td_s32 uapi_flash_getinfo(td_handle handle, uapi_flash_info *flash_info);

#ifdef __cplusplus
#if __cplusplus
}
#endif
#endif /* __cplusplus */

#endif /* __UAPI_FLASH__H__ */