api.md 9.3 KB

EasyFlash API ˵Ã÷


ËùÓÐÖ§³ÖµÄAPI½Ó¿Ú¶¼ÔÚ\easyflash\inc\easyflash.hÖÐÉùÃ÷¡£ÒÔÏÂÄÚÈݽ϶࣬½¨ÒéʹÓà CTRL+F ËÑË÷¡£

Ãû´Ê½éÉÜ£º

1¡¢Óû§Ê¹ÓýӿÚ

1.1 ³õʼ»¯

³õʼ»¯µÄEasyFlashµÄ¸÷¸ö×é¼þ£¬³õʼ»¯ºó²Å¿ÉÒÔʹÓÃÏÂÃæµÄAPI¡£

Õë¶Ô»·¾³±äÁ¿×é¼þ£¬Èç¹û flash µÚÒ»´Î³õʼ»¯£¬»á×Ô¶¯µ÷Óà ef_env_set_default £¬»Ö¸´ÒÆÖ²ÎļþÖж¨ÒåµÄĬÈÏ»·¾³±äÁ¿£¨Ïê¼ûÒÆÖ²Îĵµ£©£¬Ö®ºóÿ´ÎÆô¶¯»á×Ô¶¯¼ì²é flash ÖеĻ·¾³±äÁ¿×´Ì¬£¬flash ³öÏÖÑÏÖØËð»µÊ±Ò²»á»Ö¸´»·¾³±äÁ¿ÖÁĬÈÏ¡£Èç¹û¿ªÆôÔöÁ¿Éý¼¶¹¦ÄÜ£¬»¹»á×öÔöÁ¿Éý¼¶µÄ¼ì²é£¬°æ±¾ºÅ²»Ò»ÖÂʱִÐÐÔöÁ¿Éý¼¶¡£

EfErrCode easyflash_init(void)

1.2 »·¾³±äÁ¿

ÔÚ V4.0 ÒԺ󣬻·¾³±äÁ¿ÔÚ EasyFlash µ×²ã¶¼Êǰ´ÕÕ¶þ½øÖÆÊý¾Ý¸ñʽ½øÐд洢£¬¼´ blob ¸ñʽ £¬ÕâÑùÉϲãÖ§³Ö´«ÈëÈÎÒâÀàÐÍ¡£¶øÔÚ V4.0 ֮ǰµ×²ãʹÓõÄÊÇ×Ö·û´®¸ñʽ½øÐд洢£¬×Ö·û´®¸ñʽµÄ»·¾³±äÁ¿Ò²¿ÉÒÔת»»Îª blob ¸ñʽ£¬ËùÒÔ V4.0 ÄÜ×öµ½ÍêÈ«¼æÈÝÒÔǰµÄ API £¬ÀýÈ磺ef_get_env/ef_set_env £¬ÕâЩ API Ö»ÄÜ ¸ø×Ö·û´® ENV ʹÓá£

ÁíÍâ×Ö·û´® ENV Ò²Óг¤¶ÈµÄÏÞÖÆ£¬Ä¬ÈÏ EF_STR_ENV_VALUE_MAX_SIZE ÅäÖÃΪ 128 ×Ö½Ú£¬³¬¹ý³¤¶ÈµÄ¿ÉÄÜÎÞ·¨Ê¹Óà ef_get_env »ñÈ¡£¬Ö»ÄÜʹÓà ef_get_env_blob »ñÈ¡¡£

1.2.1 »ñÈ¡»·¾³±äÁ¿

ͨ¹ý»·¾³±äÁ¿µÄÃû×ÖÀ´»ñÈ¡Æä¶ÔÓ¦µÄÖµ¡£Ö§³ÖÁ½ÖÖ½Ó¿Ú

1.2.1.1 »ñÈ¡ blob ÀàÐÍ»·¾³±äÁ¿
size_t ef_get_env_blob(const char *key, void *value_buf, size_t buf_len, size_t *save_value_len)
²ÎÊý ÃèÊö
key »·¾³±äÁ¿Ãû³Æ
value_buf ´æ·Å»·¾³±äÁ¿µÄ»º³åÇø
buf_len ¸Ã»º³åÇøµÄ´óС
save_value_len ·µ»Ø¸Ã»·¾³±äÁ¿Êµ¼Ê´æ´¢ÔÚ flash ÖеĴóС
·µ»Ø ³É¹¦´æ·ÅÖÁ»º³åÇøÖеÄÊý¾Ý³¤¶È

ʾÀý£º

char value[32];
size_t len;
/* Èç¹û»·¾³±äÁ¿³¤¶Èδ֪£¬¿ÉÒÔÏÈ»ñÈ¡ Flash ÉÏ´æ´¢µÄʵ¼Ê³¤¶È£¬½«Í¨¹ý len ·µ»Ø */
ef_get_env_blob("key", NULL, 0, &len);
/* Èç¹û³¤¶ÈÒÑÖª£¬Ê¹Óà value »º³åÇø£¬´æ·Å¶ÁÈ¡»ØÀ´µÄ»·¾³±äÁ¿ÖµÊý¾Ý£¬²¢½«Êµ¼Ê³¤¶È·µ»Ø */
len = ef_get_env_blob("key", value, sizeof(value) , NULL);
1.2.1.2 »ñÈ¡×Ö·û´®ÀàÐÍ»·¾³±äÁ¿

×¢Òâ £º

  • ¸Ãº¯ÊýÒÑ·ÏÆú£¬²»ÍƼö¼ÌÐøÊ¹Ó㬿ÉÒÔʹÓÃÉÏÃæµÄº¯ÊýÌæ´ú£»
  • ¸Ãº¯Êý²»ÔÊÐíÁ¬ÐøÊ¹Óã¬Ê¹ÓÃʱÐèʹÓà strdup °ü¹ü£¬È·±£Ã¿´Î·µ»Ø»ØÀ´µÄ×Ö·û´®ÄÚ´æ¿Õ¼ä¶ÀÁ¢£»
  • ¸Ãº¯Êý²»Ö§³Ö¿ÉÖØÈ룬·µ»ØµÄֵλÓÚº¯ÊýÄÚ²¿»º³åÇø£¬³öÓÚ°²È«¿¼ÂÇ£¬Çë¼ÓËø±£»¤¡£
char *ef_get_env(const char *key)
²ÎÊý ÃèÊö
key »·¾³±äÁ¿Ãû³Æ
·µ»Ø »·¾³±äÁ¿Öµ

1.2.2 ÉèÖû·¾³±äÁ¿

ʹÓô˷½·¨¿ÉÒÔʵÏÖ¶Ô»·¾³±äÁ¿µÄÔö¼Ó¡¢Ð޸ļ°É¾³ý¹¦ÄÜ¡£

  • Ôö¼Ó £ºµ±»·¾³±äÁ¿±íÖв»´æÔÚ¸ÃÃû³ÆµÄ»·¾³±äÁ¿Ê±£¬Ôò»áÖ´ÐÐÐÂÔö²Ù×÷£»
  • ÐÞ¸Ä £ºÈë²ÎÖеĻ·¾³±äÁ¿Ãû³ÆÔÚµ±Ç°»·¾³±äÁ¿±íÖдæÔÚ£¬Ôò°Ñ¸Ã»·¾³±äÁ¿ÖµÐÞ¸ÄΪÈë²ÎÖеÄÖµ£»
  • ɾ³ý£ºµ±Èë²ÎÖеÄvalueΪNULLʱ£¬Ôò»áɾ³ýÈë²ÎÃû¶ÔÓ¦µÄ»·¾³±äÁ¿¡£
1.2.1.1 ÉèÖà blob ÀàÐÍ»·¾³±äÁ¿
EfErrCode ef_set_env_blob(const char *key, const void *value_buf, size_t buf_len)
²ÎÊý ÃèÊö
key »·¾³±äÁ¿Ãû³Æ
value_buf »·¾³±äÁ¿Öµ»º³åÇø
buf_len »º³åÇø³¤¶È£¬¼´ÖµµÄ³¤¶È
1.2.1.2 ÉèÖÃ×Ö·û´®ÀàÐÍ»·¾³±äÁ¿
EfErrCode ef_set_env(const char *key, const char *value)
²ÎÊý ÃèÊö
key »·¾³±äÁ¿Ãû³Æ
value »·¾³±äÁ¿Öµ

1.2.3 ɾ³ý»·¾³±äÁ¿

ʹÓô˷½·¨¿ÉÒÔʵÏÖ¶Ô»·¾³±äÁ¿µÄɾ³ý¹¦ÄÜ¡£

EfErrCode ef_del_env(const char *key)
²ÎÊý ÃèÊö
key »·¾³±äÁ¿Ãû³Æ

1.2.4 ÖØÖû·¾³±äÁ¿

½«ÄÚ´æÖеĻ·¾³±äÁ¿±íÖØÖÃΪĬÈÏÖµ¡£¹ØÓÚĬÈÏ»·¾³±äÁ¿µÄÉ趨·½·¨¿ÉÒԲο¼ÒÆÖ²Îĵµ¡£

EfErrCode ef_env_set_default(void)

1.2.5 ´òÓ¡»·¾³±äÁ¿

ͨ¹ýÔÚÒÆÖ²½Ó¿Ú(\easyflash\port\ef_port.c)Öж¨ÒåµÄef_print´òÓ¡·½·¨£¬À´½«FlashÖеÄËùÓл·¾³±äÁ¿Êä³ö³öÀ´¡£

void ef_print_env(void)

1.3 ÔÚÏßÉý¼¶

1.3.1 ²Á³ý±¸·ÝÇøÖеÄÓ¦ÓóÌÐò

EfErrCode ef_erase_bak_app(size_t app_size)

1.3.2 ²Á³ýÓû§µÄÓ¦ÓóÌÐò

×¢Ò⣺Çë²»ÒªÔÚÓ¦ÓóÌÐòÖе÷Óø÷½·¨

EfErrCode ef_erase_user_app(uint32_t user_app_addr, size_t user_app_size)
²ÎÊý ÃèÊö
user_app_addr Óû§Ó¦ÓóÌÐòÈë¿ÚµØÖ·
user_app_size Óû§Ó¦ÓóÌÐò´óС

1.3.3 ͨ¹ýÓû§Ö¸¶¨µÄ²Á³ý·½·¨À´²Á³ýÓ¦ÓóÌÐò

µ±Óû§µÄÓ¦ÓóÌÐòÓ뱸·ÝÇø ²»ÔÚͬһ¸ö Flash ʱ£¬ÔòÐèÒªÓû§¶îÍâÖ¸¶¨²Á³ýÓ¦ÓóÌÐòµÄ·½·¨¡£¶ø ef_erase_user_app »áʹÓÃÒÆÖ²ÎļþÖÐµÄ ef_port_erase ·½·¨½øÐвÁ³ý£¬³ý´ËÖ®ÍâµÄÆäÓ๦ÄÜ£¬Á½¸ö·½·¨¾ùÒ»Ö¡£

×¢Ò⣺Çë²»ÒªÔÚÓ¦ÓóÌÐòÖе÷Óø÷½·¨

EfErrCode ef_erase_spec_user_app(uint32_t user_app_addr, size_t app_size,
        EfErrCode (*app_erase)(uint32_t addr, size_t size));
²ÎÊý ÃèÊö
user_app_addr Óû§Ó¦ÓóÌÐòÈë¿ÚµØÖ·
user_app_size Óû§Ó¦ÓóÌÐò´óС
app_erase Óû§Ö¸¶¨Ó¦ÓóÌÐò²Áд·½·¨

1.3.4 ²Á³ýBootloader

×¢Ò⣺Çë²»ÒªÔÚBootloaderÖе÷Óø÷½·¨

EfErrCode ef_erase_bl(uint32_t bl_addr, size_t bl_size)
²ÎÊý ÃèÊö
bl_addr BootloaderÈë¿ÚµØÖ·
bl_size Bootloader´óС

1.3.5 дÊý¾Ýµ½±¸·ÝÇø

ΪÏÂÔØ³ÌÐòµ½±¸·ÝÇø¶¨ÖƵÄFlashÁ¬ÐøÐ´·½·¨¡£ ×¢Ò⣺д֮ǰÇëÏÈÈ·ÈÏFlashÒѽøÐвÁ³ý¡£

EfErrCode ef_write_data_to_bak(uint8_t *data,
                               size_t size,
                               size_t *cur_size,
                               size_t total_size)
²ÎÊý ÃèÊö
data ÐèҪдÈëµ½±¸·ÝÇøÖеÄÊý¾Ý´æ´¢µØÖ·
size ´Ë´ÎдÈëÊý¾ÝµÄ´óС£¨×Ö½Ú£©
cur_size ֮ǰÒÑдÈëµ½±¸·ÝÇøÖеÄÊý¾Ý´óС£¨×Ö½Ú£©
total_size ÐèҪдÈëµ½±¸·ÝÇøµÄÊý¾Ý×Ü´óС£¨×Ö½Ú£©

1.3.6 ´Ó±¸·Ý¿½±´Ó¦ÓóÌÐò

½«±¸·ÝÇøÒÑÏÂÔØºÃµÄÓ¦ÓóÌÐò¿½±´ÖÁÓû§Ó¦ÓóÌÐòÆðʼµØÖ·¡£ ×¢Ò⣺ 1¡¢¿½±´Ç°±ØÐë¶ÔÔ­ÓеÄÓ¦ÓóÌÐò½øÐвÁ³ý 2¡¢²»ÒªÔÚÓ¦ÓóÌÐòÖе÷Óø÷½·¨

EfErrCode ef_copy_app_from_bak(uint32_t user_app_addr, size_t app_size)
²ÎÊý ÃèÊö
user_app_addr Óû§Ó¦ÓóÌÐòÈë¿ÚµØÖ·
user_app_size Óû§Ó¦ÓóÌÐò´óС

1.3.7 ͨ¹ýÓû§Ö¸¶¨µÄд²Ù×÷·½·¨À´¿½±´Ó¦ÓóÌÐò

µ±Óû§µÄÓ¦ÓóÌÐòÓ뱸·ÝÇø ²»ÔÚͬһ¸ö Flash ʱ£¬ÔòÐèÒªÓû§¶îÍâÖ¸¶¨Ð´Ó¦ÓóÌÐòµÄ·½·¨¡£¶ø ef_copy_app_from_bak »áʹÓÃÒÆÖ²ÎļþÖÐµÄ ef_port_write ·½·¨½øÐÐд²Ù×÷£¬³ý´ËÖ®ÍâµÄÆäÓ๦ÄÜ£¬Á½¸ö·½·¨¾ùÒ»Ö¡£

EfErrCode ef_copy_spec_app_from_bak(uint32_t user_app_addr, size_t app_size,
        EfErrCode (*app_write)(uint32_t addr, const uint32_t *buf, size_t size))
²ÎÊý ÃèÊö
user_app_addr Óû§Ó¦ÓóÌÐòÈë¿ÚµØÖ·
user_app_size Óû§Ó¦ÓóÌÐò´óС
app_write Óû§Ö¸¶¨Ó¦ÓóÌÐòд²Ù×÷·½·¨

1.3.8 ´Ó±¸·Ý¿½±´Bootloader

½«±¸·ÝÇøÒÑÏÂÔØºÃµÄBootloader¿½±´ÖÁBootloaderÆðʼµØÖ·¡£ ×¢Ò⣺ 1¡¢¿½±´Ç°±ØÐë¶ÔÔ­ÓеÄBootloader½øÐвÁ³ý 2¡¢²»ÒªÔÚBootloaderÖе÷Óø÷½·¨

EfErrCode ef_copy_bl_from_bak(uint32_t bl_addr, size_t bl_size)
²ÎÊý ÃèÊö
bl_addr BootloaderÈë¿ÚµØÖ·
bl_size Bootloader´óС

1.4 ÈÕÖ¾´æ´¢

1.4.1 ´ÓFlashÖжÁÈ¡ÒÑ´æÔÚµÄÈÕÖ¾

EfErrCode ef_log_read(size_t index, uint32_t *log, size_t size);
²ÎÊý ÃèÊö
index ÈÕÖ¾¶ÁÈ¡µÄË÷Òý˳Ðò
log ´æ´¢´ý¶ÁÈ¡ÈÕÖ¾µÄ»º³åÇø
size ¶ÁÈ¡ÈÕÖ¾µÄ´óС

1.4.2 ÍùFlashÖб£´æÈÕÖ¾

EfErrCode ef_log_write(const uint32_t *log, size_t size);
²ÎÊý ÃèÊö
log ´æ´¢´ý±£´æµÄÈÕÖ¾
size ´ý±£´æÈÕÖ¾µÄ´óС

1.4.3 Çå¿Õ´æ´¢ÔÚFlashÖÐÈ«²¿ÈÕÖ¾

EfErrCode ef_log_clean(void);

1.4.4 »ñÈ¡ÒÑ´æ´¢ÔÚFlashÖеÄÈÕÖ¾´óС

size_t ef_log_get_used_size(void);

2¡¢ÅäÖÃ

²ÎÕÕEasyFlash ÒÆÖ²ËµÃ÷£¨\docs\zh\port.md£©ÖÐµÄ ÉèÖòÎÊý Õ½Ú

3¡¢×¢Òâ

  • дÊý¾ÝǰÎñ±Ø¼ÇµÃÏȲÁ³ý
  • ²»ÒªÔÚÓ¦ÓóÌÐò¼°BootloaderÖÐÖ´ÐвÁ³ý¼°¿½±´×ÔÉíµÄ¶¯×÷
  • Log¹¦ÄܶÔFlash²Á³ýºÍдÈëÒªÇó4¸ö×Ö½Ú¶ÔÆë£¬²Á³ýµÄ×îСµ¥Î»ÔòÐè¸ù¾ÝÓû§µÄƽ̨À´È·¶¨