nvmnand.h

Go to the documentation of this file.

/*
 * Copyright (c) 2013-2022 NVIDIA Corporation.  All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 *
 * Redistributions of source code must retain the above copyright notice,
 * this list of conditions and the following disclaimer.
 *
 * Redistributions in binary form must reproduce the above copyright notice,
 * this list of conditions and the following disclaimer in the documentation
 * and/or other materials provided with the distribution.
 *
 * Neither the name of the NVIDIA Corporation nor the names of its contributors
 * may be used to endorse or promote products derived from this software
 * without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 * POSSIBILITY OF SUCH DAMAGE.
 *
 */
 
#ifndef __NV_MNAND_H__
#define __NV_MNAND_H__
 
#include <stdio.h>
#include <stdint.h>
#include <stdbool.h>
#include <assert.h>
 
#if defined(__cplusplus)
extern "C"
{
#endif
 
#define MAX_ERASE_CNT    0xFFFF
 
#ifndef SECTOR_SZ
#define SECTOR_SZ               512
#endif
 
#define  MNAND_READ_CACHE_ENABLE   (1 << 0)
#define  MNAND_WRITE_CACHE_ENABLE  (1 << 1)
 
#define MAX_FW_STR_LEN       (32U)
 
#define MAX_PRN_STR_LEN      (64U)
 
/* forward declaration */
struct __mnand_chip;
struct __mnand_operations;
 
typedef struct __mnand_block_info {
    uint16_t block_number;    /* block#, absolute */
    uint16_t block_age;       /* age (aka erase, p/e) count */
    uint16_t block_type;      /* block type */
        #define MNAND_UNKNOWN_BLOCK         (1 << 0)
        #define MNAND_MLC_BLOCK             (1 << 1)
        #define MNAND_SLC_BLOCK             (1 << 2)
        #define MNAND_UNKNOWN_BAD_BLOCK     (1 << 8)
        #define MNAND_MANF_BAD_BLOCK        (1 << 9)
        #define MNAND_RUNTIME_BAD_BLOCK     (1 << 10)
        #define MNAND_SYSTEM_BLOCK          (1 << 11)
    uint16_t valid;           /* is this entry valid? */
} mnand_block_info;
 
typedef union __mnand_life_time_element {
    uint16_t spare_blocks;    /* #spare block in this region */
    double   percentage;      /* Life time in percentage */
} mnand_life_time_element;
 
typedef struct __mnand_life_time_info {
    mnand_life_time_element life_time;
    uint8_t  life_time_type;  /* how the lifetime being presented */
        #define MNAND_LIFETIME_INVALID     (1 << 0)
        #define MNAND_LIFETIME_IN_BLOCK    (1 << 1)
        #define MNAND_LIFETIME_IN_PERCENT  (1 << 2)
} mnand_life_time_info;
 
typedef union __mnand_refresh_element {
    uint16_t block;           /* last block being refresh */
    double   percentage;      /* refresh percentage */
} mnand_refresh_element;
 
typedef struct __mnand_refresh_progress {
    mnand_refresh_element progress;
    uint8_t progress_type;    /* how the progress being presented */
        #define MNAND_RFSH_PROG_INVALID     (1 << 0)
        #define MNAND_RFSH_PROG_IN_BLOCK    (1 << 1)
        #define MNAND_RFSH_PROG_IN_PERCENT  (1 << 2)
} mnand_refresh_progress;
 
typedef struct __mnand_refresh_properties {
    uint32_t rfsh_days;               /* whole chip refreshes in given days */
    uint32_t def_rfsh_interval;       /* default refresh interval(msec) */
    uint32_t min_rfsh_interval;       /* minimum refresh interval(msec) */
    uint32_t shutdown_rfsh_interval;  /* min shutdown refresh interval(msec) */
    uint32_t rfsh_calibrate_cnt;      /* min refreshes before re-calibration */
    uint32_t rfsh_unit_time_us;       /* time for each refresh operation(UFS only) */
} mnand_refresh_properties;
 
typedef struct __mnand_ages_element {
    uint16_t min_age;         /* min. age in this region */
    uint16_t max_age;         /* max. age in this region */
    double   avg_age;         /* avg. age in this region */
    uint32_t total_age;       /* total age (if available) */
    uint8_t valid;            /* is this entry valid? */
} mnand_ages_info;
 
typedef struct __mnand_wr_info {
    uint32_t fnand;
    uint32_t fram;
    uint8_t valid;
} mnand_wr_info;
 
typedef struct mnand_ufs_write_erase_amplification {
    double slc_weaf;
    double mlc_weaf;
    uint8_t valid;
} mnand_ufs_write_erase_amplification;
 
 
typedef struct __mnand_summary_element {
    mnand_life_time_info life;/* life time information */
    mnand_ages_info ages;     /* ages information */
    mnand_wr_info wcount;
    mnand_ufs_write_erase_amplification eaf;
    uint8_t valid;            /* is this entry valid? */
} mnand_summary_element;
 
typedef struct __mnand_summary_info {
    mnand_summary_element mlc;    /* MLC region */
    mnand_summary_element slc;    /* SLC region */
    mnand_summary_element total;  /* per chip */
    int factory_bb_cnt;       /* #factory bad block, -1=invalid */
    int runtime_bb_cnt;       /* #runtime bad block, -1=invalid */
    int32_t spare_bcnt;
} mnand_summary_info;
 
typedef struct __mnand_cid_info {
    uint8_t data[16];    /* JDEC spec. 4.51, table 64, 128bit wide */
} mnand_cid_info;
 
typedef struct __mnand_csd_info {
    uint8_t data[16];    /* JDEC spec. 4.51, table 67, 128bit wide */
} mnand_csd_info;
 
typedef struct __mnand_ext_csd_info {
    uint8_t data[512];   /* JDEC spec. 4.51, table 82, 512byte wide */
} mnand_ext_csd_info;
 
typedef struct __mnand_device_desc_info {
    uint8_t data[64];   /* JESD220C spec. table 14.4, 64byte wide */
} mnand_device_desc_info;
 
typedef struct __mnand_config_desc_info {
    uint8_t data1[144];   /* JESD220C spec. table 14.10, 144byte wide */
    uint8_t data2[144];   /* JESD220C spec. table 14.10, 144byte wide */
    uint8_t data3[144];   /* JESD220C spec. table 14.10, 144byte wide */
    uint8_t data4[144];   /* JESD220C spec. table 14.10, 144byte wide */
} mnand_config_desc_info;
 
typedef struct __mnand_geo_desc_info {
    uint8_t data[72];   /* JESD220C spec. table 14.13, 72byte wide */
} mnand_geo_desc_info;
 
typedef struct __mnand_unit_desc_info {
    uint8_t data[19];   /* JESD220C spec. table 14.14, 19byte wide */
} mnand_unit_desc_info;
 
typedef struct __mnand_mmc_geo_info {
    uint64_t sec_count;
    uint64_t enh_size_mult;
    uint64_t enh_start_addr;
    uint64_t hc_wp_grp_size;
    uint64_t hc_erase_grp_size;
    uint64_t max_enh_size_mult;
    uint64_t partition_size_alignment;
    uint64_t user_capacity;
} mnand_mmc_geo_info;
 
typedef struct __mnand_ufs_geo_info {
    uint64_t total_raw_capacity;
    uint8_t  max_lu;
    uint32_t segment_size;
    uint8_t  alloc_unit_size;
    uint16_t supported_memory_types;
    uint32_t sys_code_max_alloc;
    uint16_t sys_code_cap_adj_fac;
    uint32_t non_persist_max_alloc;
    uint16_t non_persist_cap_adj_fac;
    uint32_t enhanced1_max_alloc;
    uint16_t enhanced1_cap_adj_fac;
    uint32_t enhanced2_max_alloc;
    uint16_t enhanced2_cap_adj_fac;
    uint32_t enhanced3_max_alloc;
    uint16_t enhanced3_cap_adj_fac;
    uint32_t enhanced4_max_alloc;
    uint16_t enhanced4_cap_adj_fac;
} mnand_ufs_geo_info;
 
typedef union __mnand_geo_info {
    mnand_mmc_geo_info mmc_geo_info;
    mnand_ufs_geo_info ufs_geo_info;
} mnand_geo_info;
 
typedef struct __mnand_lu_info {
    uint8_t lu_enabled;
    uint8_t memory_type;
    uint8_t logical_blk_sz;
    uint32_t  num_alloc_units;
} mnand_lu_info;
 
typedef enum __mnand_device_type {
    MNAND_CATCH_ALL = 0,   /* "catch-all", used when none matched */
    MNAND_HYNIX_F26 = 1,   /* Hynix F26 */
    MNAND_HYNIX_F20 = 2,   /* Hynix F20 */
    MNAND_HYNIX_F16 = 3,   /* Hynix F16 */
    MNAND_MICRON    = 4,   /* Samsung eMMC5.0 */
    MNAND_SAMSUNG50 = 5,   /* Samsung eMMC5.0 */
    MNAND_SAMSUNG51 = 6,   /* Samsung eMMC5.1 */
    MNAND_TOSHIBA   = 7,   /* Toshiba */
    MNAND_UFS_TOSHIBA = 8,   /* Toshiba UFS */
    MNAND_UFS_SAMSUNG = 9,   /* Samsung UFS */
    MNAND_UFS_MICRON = 10,   /* Micron UFS */
} MNAND_DEVICE_TYPE;
 
 
typedef enum __mnand_storage_type {
    MNAND_EMMC = 0,   /* eMMC storage device */
    MNAND_UFS = 1,   /* UFS storage device */
    MNAND_UNKNOWN = 2,   /* unknown storage - error */
} MNAND_STORAGE_TYPE;
 
typedef enum __mnand_eol_status {
    MNAND_EOL_OK = 0,        /* Not yet EOL */
    MNAND_EOL_DETECTED = 1,  /* EOL detected */
} MNAND_EOL_STATUS;
 
typedef enum __mnand_fw_comparison_result {
    /* Passed FW version is same as the current FW version on Device */
    MNAND_PASSED_FW_VERSION_SAME = 0,
    /* Passed FW version is greater than current FW version on Device */
    MNAND_PASSED_FW_VERSION_GREATER = 1,
    /* Passed FW version is lesser than current FW version on Device */
    MNAND_PASSED_FW_VERSION_LESSER = 2,
} MNAND_FW_COMPARE;
 
typedef enum __mnand_ffu_status {
    MNAND_FFU_STATUS_SUCCESS = 0,
    MNAND_FFU_STATUS_INSTALL_FAILED = 1,
    MNAND_FFU_STATUS_ERROR_DOWNLOADING_FIRMWARE = 2,
    MNAND_FFU_STATUS_FW_CORRUPTION_ERROR = 3,
    MNAND_FFU_STATUS_FW_VERSION_MISMATCH = 4,
    MNAND_FFU_STATUS_INTERNAL_ERROR = 5,
    MNAND_FFU_STATUS_NO_INFORMATION = 6,
    MNAND_FFU_STATUS_GENERIC_ERROR = 7,
    MNAND_FFU_STATUS_RESERVED_ERROR = 8,
} MNAND_FFU_STATUS;
 
typedef enum __mnand_status {
    MNAND_OK = 0,            /* OK */
    MNAND_ENOMEM = 1,        /* memory allocation error */
    MNAND_EIO = 2,           /* I/O error */
    MNAND_EINVAL = 3,        /* invalid operation */
    MNAND_EOPEN = 4,         /* error opening device node */
    MNAND_UNSUPPORTED = 5,   /* not supported operation */
    MNAND_UNKNOWN_ERR = 6,   /* unknown error */
    MNAND_BKOPS_EN_ERR = 7   /* BKOPS en state not set to requested value */
} MNAND_STATUS;
 
struct __mnand_chip {
    int fd;                         /* file descriptor */
    char desc[128];                  /* chip desciption, mNAND specific */
    char prn[MAX_PRN_STR_LEN];      /* Produce Name */
    char fw_version[MAX_FW_STR_LEN];/* firmware version */
    void *priv_ops;                 /* mNAND vendor specific priv operations */
    void *priv_chip_ops;            /* mNAND storage specific priv operations */
    int num_blocks;                 /* #blocks available, 0=unavailable */
    mnand_block_info *block_info;   /* block info list, indexd by num_blocks */
    int refresh_available;          /* force refresh is available */
    int ffu_available;              /* FFU is available */
    mnand_refresh_properties rfsh_properties;  /* refresh properties */
    int summary_available;          /* summary info is available */
    int smart_summary_available;    /* smart summary info is available */
    mnand_summary_info *summary;    /* summary info, not NULL when available */
    mnand_cid_info cid;             /* eMMC CID */
    mnand_csd_info csd;             /* eMMC CSD */
    mnand_ext_csd_info xcsd;        /* eMMC EXT CSD */
    mnand_device_desc_info device_desc; /* UFS Device Desccriptior */
    mnand_config_desc_info cfg_desc; /* UFS Configuration Descriptor */
    mnand_geo_desc_info geo_desc;    /* UFS Geometry Descriptor */
    mnand_unit_desc_info unit_desc; /* UFS Unit Descriptor */
    uint32_t card_status;           /* card status */
    MNAND_DEVICE_TYPE dev_type;     /* device type */
    MNAND_STORAGE_TYPE storage_type; /* storage type */
    void *priv;                     /* mNAND specific private "handle" */
};
 
typedef struct __mnand_chip mnand_chip;
 
struct __mnand_ufs_query_req {
    uint8_t opcode;   /* Query operation opcode */
    uint8_t idn;      /* Query operation idn */
    uint8_t index;    /* index - optional in some cases */
    uint8_t selector; /* index - optional in some cases */
    uint8_t buf_size; /* buf_size - buffer size in bytes pointed by buffer */
    uint8_t *buffer;  /* user buffer pointer for query data
                       * should be 4 bytes for Attribute Read/Write
                       * should be 1 byte for Flag Read
                       * size varies for Read/Write Descriptor */
    uint32_t delay;   /* delay after query command completion */
    MNAND_STATUS status; /* return status of this query request */
};
 
struct __mnand_ufs_combo_query_req {
    uint8_t num_cmds;      /* Number of Query Commands in this Combo */
    uint8_t need_cq_empty; /* Command Queue need to be empty or not */
    struct __mnand_ufs_query_req *query; /* Query Request info start ptr */
};
 
typedef struct __mnand_ufs_query_req mnand_ufs_query_req;
typedef struct __mnand_ufs_combo_query_req mnand_ufs_combo_query_req;
 
/* inline helpers */
 
static inline int mnand_is_valid_block(mnand_block_info *blk)
{
    assert(blk != NULL);
 
    return (blk->valid != 0);
}
 
static inline int mnand_is_bad_block(mnand_block_info *blk)
{
    assert(blk != NULL);
 
    return mnand_is_valid_block(blk) && ((blk->block_type &
        (MNAND_UNKNOWN_BAD_BLOCK | MNAND_MANF_BAD_BLOCK |
        MNAND_RUNTIME_BAD_BLOCK)) || (blk->block_age == MAX_ERASE_CNT)) ? 1 : 0;
}
 
static inline int mnand_is_usable_block(mnand_block_info *blk)
{
    assert(blk != NULL);
 
    return (!mnand_is_valid_block(blk) || mnand_is_bad_block(blk) ||
        (blk->block_type & MNAND_SYSTEM_BLOCK)) ? 0 : 1;
}
 
static inline int mnand_is_usable_block_with_type(mnand_block_info *blk,
    uint16_t blk_type)
{
    assert((blk != NULL) && (blk_type != 0));
 
    return (mnand_is_usable_block(blk) && (blk->block_type & blk_type)) ? 1 : 0;
}
 
static inline int mnand_is_slc_block(mnand_block_info *blk)
{
    assert(blk != NULL);
 
    return mnand_is_valid_block(blk) &&
        (blk->block_type & MNAND_SLC_BLOCK) ? 1 : 0;
}
 
static inline int mnand_is_mlc_block(mnand_block_info *blk)
{
    assert(blk != NULL);
 
    return mnand_is_valid_block(blk) &&
        (blk->block_type & MNAND_MLC_BLOCK) ? 1 : 0;
}
 
static inline int mnand_is_summary_available(mnand_chip *chip)
{
    assert(chip != NULL);
 
    return (chip->summary_available != 0);
}
 
static inline int mnand_is_smart_summary_available(mnand_chip *chip)
{
    assert(chip != NULL);
 
    return (chip->smart_summary_available != 0);
}
 
static inline int mnand_is_refresh_available(mnand_chip *chip)
{
    assert(chip != NULL);
 
    return (chip->refresh_available != 0);
}
 
static inline int mnand_is_block_info_available(mnand_chip *chip)
{
    assert(chip != NULL);
 
    return (chip->num_blocks > 0);
}
 
static inline MNAND_STORAGE_TYPE mnand_get_storage_type(mnand_chip *chip)
{
    assert(chip != NULL);
 
    return (chip->storage_type);
}
 
/* prototypes for wrapper functions */
 
MNAND_STATUS mnand_get_bkops_en(mnand_chip *chip, uint8_t *enabled);
 
MNAND_STATUS mnand_get_bkops_status(mnand_chip *chip, uint8_t *stat);
 
MNAND_STATUS mnand_set_bkops_en(mnand_chip *chip, uint8_t enable);
 
MNAND_STATUS mnand_set_bkops_start(mnand_chip *chip);
 
MNAND_STATUS mnand_enable_power_off_notification(mnand_chip *chip);
 
MNAND_STATUS mnand_send_power_off_notification(mnand_chip *chip);
 
MNAND_STATUS mnand_open(const char *devname, mnand_chip *chip);
 
MNAND_STATUS mnand_close(mnand_chip *chip);
 
MNAND_STATUS mnand_bind(int fd, mnand_chip *chip);
 
MNAND_STATUS mnand_unbind(mnand_chip *chip);
 
MNAND_STATUS mnand_update_cid(mnand_chip *chip);
 
MNAND_STATUS mnand_update_csd(mnand_chip *chip);
 
MNAND_STATUS mnand_update_xcsd(mnand_chip *chip);
 
MNAND_STATUS mnand_update_card_status(mnand_chip *chip);
 
MNAND_STATUS mnand_update_block_info(mnand_chip *chip);
 
MNAND_STATUS mnand_update_summary_info(mnand_chip *chip);
 
MNAND_STATUS mnand_update_smart_summary_info(mnand_chip *chip);
 
 
MNAND_STATUS mnand_check_eol_status(mnand_chip *chip,
    MNAND_EOL_STATUS *eol_status);
 
MNAND_STATUS mnand_send_refresh(mnand_chip *chip, uint8_t block_type,
    int num_blocks, uint32_t rfsh_unit_time_us,
    mnand_refresh_progress *progress);
 
MNAND_STATUS mnand_extract_age_info(mnand_chip *chip, int block_type,
    uint64_t *total_age, int *blk_count, double *avg_age);
 
MNAND_STATUS mnand_get_refresh_progress(mnand_chip *chip,
    double *rfsh_progress);
 
MNAND_STATUS mnand_extract_life_time_info(mnand_chip *chip,
    mnand_life_time_info *life_time_info);
 
MNAND_STATUS mnand_set_cache_en(mnand_chip *chip, uint8_t enable);
 
MNAND_STATUS mnand_flush_cache(mnand_chip *chip);
 
int mnand_read_sectors_virt(mnand_chip *chip, unsigned int start_sector,
    unsigned int sector_cnt, void *virtaddr);
 
int mnand_read_sectors_phys(mnand_chip *chip, unsigned int start_sector,
    unsigned int sector_cnt, off_t physaddr);
 
MNAND_STATUS mnand_trim_all(mnand_chip *chip);
 
MNAND_STATUS mnand_get_cache_en(mnand_chip *chip, uint8_t *enabled);
 
MNAND_STATUS mnand_switch_cmd(mnand_chip *chip, uint8_t index,
    uint8_t value, char *errmsg_prepend);
 
MNAND_STATUS mnand_get_geo_info(mnand_chip *chip, mnand_geo_info *geo_info);
 
MNAND_STATUS mnand_get_lu_info(mnand_chip *chip, uint32_t lun,
    mnand_lu_info *lu_info);
 
MNAND_STATUS mnand_get_current_lun(mnand_chip *chip, uint32_t *lun);
 
MNAND_STATUS mnand_send_combo_query_req(mnand_chip *chip,
    mnand_ufs_query_req *query_req, uint8_t num_cmds, uint8_t need_cq_empty,
    uint8_t ret_on_error);
 
MNAND_STATUS mnand_test_multi_cmd(mnand_chip *chip);
 
MNAND_STATUS mnand_ffu(mnand_chip *chip, char *fw_file);
 
MNAND_STATUS mnand_get_ffu_status(mnand_chip *chip, MNAND_FFU_STATUS *ffu_status);
 
MNAND_STATUS mnand_get_fw_version(mnand_chip *chip, char *fw_version);
 
MNAND_STATUS mnand_compare_fw_version(mnand_chip *chip, char *fw_file, MNAND_FW_COMPARE *res);
 
MNAND_STATUS mnand_is_ffu_ready(mnand_chip *chip, bool *res);
 
#if defined(__cplusplus)
}
#endif  /* __cplusplus */
 
#endif /* __NV_MNAND_H__ */