alex/esp-idf
alex/esp-idf
1
0
Fork 0
mirror of https://github.com/espressif/esp-idf.git synced 2024-10-05 20:47:46 -04:00
Code Issues Actions 2 Packages Projects Releases Wiki Activity

efuse: Fix docs and script

Browse Source
This commit is contained in:
Konstantin Kondrashov 2018-12-11 14:39:32 +08:00 committed by bot
parent cc094ba789
commit 95b6273c7c
4 changed files with 34 additions and 35 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
components/efuse/Kconfig
View File

@ -14,11 +14,12 @@ config EFUSE_CUSTOM_TABLE_FILENAME
relative to the project root directory.
config EFUSE_VIRTUAL
bool "Emulate eFuse work"
bool "Simulate eFuse operations in RAM"
default n
help
If this option is set, all permanent changes (via eFuse) are disabled.
Log output will state changes which would be applied, but they will not be.
All read and writes operations are redirected to RAM instead of eFuse registers.
If this option is set, all permanent changes (via eFuse) are disabled.
Log output will state changes which would be applied, but they will not be.
choice EFUSE_CODE_SCHEME_SELECTOR
prompt "Coding scheme"

6
components/efuse/efuse_table_gen.py
View File

@ -174,7 +174,7 @@ class FuseTable(list):
rows = ''
rows += 'Sorted efuse table:\n'
num = 1
rows = "{0} \t{1:<30} \t{2} \t{3} \t{4}".format("#", "field_name", "efuse_block", "bit_start", "bit_count") + "\n"
rows += "{0} \t{1:<30} \t{2} \t{3} \t{4}".format("#", "field_name", "efuse_block", "bit_start", "bit_count") + "\n"
for p in sorted(self, key=lambda x:(x.efuse_block, x.bit_start)):
rows += "{0} \t{1:<30} \t{2} \t{3:^8} \t{4:^8}".format(num, p.field_name, p.efuse_block, p.bit_start, p.bit_count) + "\n"
num += 1
@ -299,7 +299,7 @@ class FuseDefinition(object):
def parse_block(self, strval):
if strval == "":
raise InputError("Field 'efuse_block' can't be left empty.")
if strval != "EFUSE_BLK0" and strval != "EFUSE_BLK1" and strval != "EFUSE_BLK2" and strval != "EFUSE_BLK3":
if strval not in ["EFUSE_BLK0", "EFUSE_BLK1", "EFUSE_BLK2", "EFUSE_BLK3"]:
raise InputError("Field 'efuse_block' should consist from EFUSE_BLK0..EFUSE_BLK3")
return strval
@ -389,13 +389,11 @@ def create_output_files(name, output_table, debug):
output = output_table.to_header(file_name)
with open(file_h_path, 'w') as f:
f.write(output)
f.close()
status("Creating efuse *.c file " + file_c_path + " ...")
output = output_table.to_c_file(file_name, debug)
with open(file_c_path, 'w') as f:
f.write(output)
f.close()
else:
print("Source files do not require updating correspond to csv file.")

2
components/efuse/include/esp_efuse.h
View File

@ -54,7 +54,7 @@ typedef enum {
typedef struct {
esp_efuse_block_t efuse_block; /**< Block of eFuse */
uint16_t bit_start; /**< Start bit [0..255] */
uint16_t bit_count; /**< Length of bit field [1..256]*/
uint16_t bit_count; /**< Length of bit field [1..-]*/
} esp_efuse_desc_t;
/**

54
docs/en/api-reference/system/efuse.rst
View File

@ -11,15 +11,15 @@ The eFuse Manager library is designed to structure access to eFuse bits and make
Hardware description
--------------------
The ESP32 has a number of eFuses which can store system and user parameters. Each eFuse this is one bit wich can programmed to 1, after this it can never be reverted to 0.
The ESP32 has a number of eFuses which can store system and user parameters. Each eFuse is a one-bit field which can be programmed to 1 after which it cannot be reverted back to 0.
Some of system parameters are using these eFuse bits directly by hardware modules and have special place (for example EFUSE_BLK0). For more details see `ESP32 Technical Reference Manual <https://www.espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf>`_ in part 20 eFuse controller. Some eFuse bits are available for user applications.
ESP32 has 4 eFuse bit blocks of 256 bits each (not all bits are available):
ESP32 has 4 eFuse blocks each of the size of 256 bits (not all bits are available):
* EFUSE_BLK0 is used entirely for system purposes;
* EFUSE_BLK1 is used for flash encrypt key. If not using that Flash Encryption feature, they can be used for another purpose;
* EFUSE_BLK2 is used for security boot key. If not using that Secure Boot feature, they can be used for another purpose;
* EFUSE_BLK3 is used for a custom MAC address, some bits are free and can be used for user applications, note that some bits are already used in idf.
* EFUSE_BLK3 can be partially reserved for the custom MAC address, or used entirely for user application. Note that some bits are already used in IDF.
Each block is divided into 8 32-bits registers.
@ -27,18 +27,18 @@ Each block is divided into 8 32-bits registers.
eFuse Manager component
-----------------------
The component has API functions for reading and writing fields. Access to the fields is carried out through the structures that describe the location of the efuse bits in the blocks. The component provides the ability to form fields of any length and from any number of individual bits. The description of the fields is made in a csv file in a table form. To generate from a tabular form (csv file) in the C-source uses the tool `efuse_table_gen.py`. The tool checks the csv file for uniqueness of field names and bit intersection, in case of using a `custom` file from the user's project directory, the utility will check with the `common` csv file.
The component has API functions for reading and writing fields. Access to the fields is carried out through the structures that describe the location of the eFuse bits in the blocks. The component provides the ability to form fields of any length and from any number of individual bits. The description of the fields is made in a CSV file in a table form. To generate from a tabular form (CSV file) in the C-source uses the tool `efuse_table_gen.py`. The tool checks the CSV file for uniqueness of field names and bit intersection, in case of using a `custom` file from the user's project directory, the utility will check with the `common` CSV file.
CSV files:
* common (`esp_efuse_table.csv`) - contains efuse fields are used inside the IDF field. C-source generation should be done manually when changing this file (run command 'make efuse_common_table' or `idf.py efuse_common_table`). Note that changes to this file can lead to incorrect IDF operation. Changes are not desirable!
* custom - (may be absent, selected through :envvar:`CONFIG_EFUSE_CUSTOM_TABLE`) contains efuse fields that are used by the user in their application. C-source generation should be done manually when changing this file (run command 'make efuse_custom_table' or `idf.py efuse_custom_table`).
* common (`esp_efuse_table.csv`) - contains eFuse fields which are used inside the IDF. C-source generation should be done manually when changing this file (run command 'make efuse_common_table' or `idf.py efuse_common_table`). Note that changes in this file can lead to incorrect operation.
* custom - (optional and can be enabled by :envvar:`CONFIG_EFUSE_CUSTOM_TABLE`) contains eFuse fields that are used by the user in their application. C-source generation should be done manually when changing this file (run command 'make efuse_custom_table' or `idf.py efuse_custom_table`).
Description CSV file
--------------------
The CSV file contains a description of the efuse fields. In the simple case, one field has one line of description.
The CSV file contains a description of the eFuse fields. In the simple case, one field has one line of description.
Table header:
::
@ -46,13 +46,13 @@ Table header:
# field_name, efuse_block(EFUSE_BLK0..EFUSE_BLK3), bit_start(0..255), bit_count(1..256), comment
Individual params in csv file the following meanings:
Individual params in CSV file the following meanings:
field_name
Name of field. The prefix `ESP_EFUSE_` will be added to the name, and this field name will be available in the code. This name will be used to access the fields. The name must be unique for all fields. If the line has an empty name, then this line is combined with the previous field. This allows you to set an arbitrary order of bits in the field, and expand the field as well (see ``MAC_FACTORY`` field in the common table).
efuse_block
Block number. It determines where the efuse bits will be placed for this field. Available EFUSE_BLK0..EFUSE_BLK3.
Block number. It determines where the eFuse bits will be placed for this field. Available EFUSE_BLK0..EFUSE_BLK3.
bit_start
Start bit number (0..255). The bit_start field can be omitted. In this case, it will be set to bit_start + bit_count from the previous record, if it has the same efuse_block. Otherwise (if efuse_block is different, or this is the first entry), an error will be generated.
@ -88,7 +88,7 @@ To generate a `common` files, use the following command 'make efuse_common_table
::
cd ~/esp/esp-idf/components/efuse/
cd $IDF_PATH/components/efuse/
./efuse_table_gen.py esp32/esp_efuse_table.csv
After generation in the folder `esp32` create:
@ -100,7 +100,7 @@ To generate a `custom` files, use the following command 'make efuse_custom_table
::
cd ~/esp/esp-idf/components/efuse/
cd $IDF_PATH/components/efuse/
./efuse_table_gen.py esp32/esp_efuse_table.csv PROJECT_PATH/main/esp_efuse_custom_table.csv
After generation in the folder PROJECT_PATH/main create:
@ -127,7 +127,7 @@ eFuse have three coding schemes:
The coding scheme affects only EFUSE_BLK1, EFUSE_BLK2 and EFUSE_BLK3 blocks. EUSE_BLK0 block always has a coding scheme ``None``.
Coding changes the number of bits that can be written into a block, the block length is constant 256, some of these bits are used for encoding and are not used.
When using a coding scheme, the length of the payload that can be written is limited (for more detailes ``20.3.1.3 System Parameter coding_scheme``):
When using a coding scheme, the length of the payload that can be written is limited (for more details ``20.3.1.3 System Parameter coding_scheme``):
* None 256 bits.
* 3/4 192 bits.
@ -140,7 +140,7 @@ You can find out the coding scheme of your chip:
* calling the function in the code :cpp:func:`esp_efuse_get_coding_scheme` for the EFUSE_BLK3 block.
eFuse tables must always comply with the coding scheme in the chip. There is an :envvar:`EFUSE_CODE_SCHEME_SELECTOR` option to select the coding type for tables in a Kconfig. When generating source files, if your tables do not follow the coding scheme, an error message will be displayed. Adjust the length or offset fields.
If your program was compiled with ``None`` encoding and ``3/4`` is used in the chip, then the ``ESP_ERR_CODING`` error may occur when calling the efuse API (the field is outside the block boundaries). If the field matches the new block boundaries, then the API will work without errors.
If your program was compiled with ``None`` encoding and ``3/4`` is used in the chip, then the ``ESP_ERR_CODING`` error may occur when calling the eFuse API (the field is outside the block boundaries). If the field matches the new block boundaries, then the API will work without errors.
Also, 3/4 coding scheme imposes restrictions on writing bits belonging to one coding unit. The whole block with a length of 256 bits is divided into 4 coding units, and in each coding unit there are 6 bytes of useful data and 2 service bytes. These 2 service bytes contain the checksum of the previous 6 data bytes.
@ -151,16 +151,16 @@ eFuse API
Access to the fields is via a pointer to the description structure. API functions have some basic operation:
* :cpp:func:`esp_efuse_read_field_blob` - returns an array of read efuse bits.
* :cpp:func:`esp_efuse_read_field_blob` - returns an array of read eFuse bits.
* :cpp:func:`esp_efuse_read_field_cnt` - returns the number of bits programmed as "1".
* :cpp:func:`esp_efuse_write_field_blob` - writes an array.
* :cpp:func:`esp_efuse_write_field_cnt` - writes a required count of bits as "1".
* :cpp:func:`esp_efuse_get_field_size` - returns the number of bits by the field name.
* :cpp:func:`esp_efuse_read_reg` - returns value of efuse register.
* :cpp:func:`esp_efuse_write_reg` - writes value to efuse register.
* :cpp:func:`esp_efuse_get_coding_scheme` - returns efuse coding scheme for blocks.
* :cpp:func:`esp_efuse_read_block` - reads key to efuse block starting at the offset and the required size.
* :cpp:func:`esp_efuse_write_block` - writes key to efuse block starting at the offset and the required size.
* :cpp:func:`esp_efuse_read_reg` - returns value of eFuse register.
* :cpp:func:`esp_efuse_write_reg` - writes value to eFuse register.
* :cpp:func:`esp_efuse_get_coding_scheme` - returns eFuse coding scheme for blocks.
* :cpp:func:`esp_efuse_read_block` - reads key to eFuse block starting at the offset and the required size.
* :cpp:func:`esp_efuse_write_block` - writes key to eFuse block starting at the offset and the required size.
For frequently used fields, special functions are made, like this :cpp:func:`esp_efuse_get_chip_ver`, :cpp:func:`esp_efuse_get_pkg_ver`.
@ -172,7 +172,7 @@ How add a new field
::
$ ./efuse_table_gen.py --info esp32/esp_efuse_table.csv
$ ./efuse_table_gen.py esp32/esp_efuse_table.csv --info
eFuse coding scheme: NONE
# field_name efuse_block bit_start bit_count
1 WR_DIS_FLASH_CRYPT_CNT EFUSE_BLK0 2 1
@ -218,7 +218,7 @@ How add a new field
41 SECURE_VERSION EFUSE_BLK3 128 32
42 MAC_CUSTOM_VER EFUSE_BLK3 184 8
Used bits in efuse table:
Used bits in eFuse table:
EFUSE_BLK0
[2 2] [7 9] [16 18] [20 27] [32 87] [96 97] [105 109] [111 111] [136 144] [188 191] [194 194] [196 196] [198 201]
@ -233,22 +233,22 @@ How add a new field
Note: Not printed ranges are free for using. (bits in EFUSE_BLK0 are reserved for Espressif)
Parsing efuse CSV input file C:/msys32/home/virtpc/esp/esp-idf/components/efuse/esp32/esp_efuse_table.csv ...
Verifying efuse table...
Parsing eFuse CSV input file $IDF_PATH/components/efuse/esp32/esp_efuse_table.csv ...
Verifying eFuse table...
The number of bits not included in square brackets is free (bits in EFUSE_BLK0 are reserved for Espressif). All fields are checked for overlapping.
2. Fill a line for field: field_name, efuse_block, bit_start, bit_count, comment.
3. Run a ``show_efuse_table`` command to check efuse table. To generate source files run ``efuse_common_table`` or ``efuse_custom_table`` command.
3. Run a ``show_efuse_table`` command to check eFuse table. To generate source files run ``efuse_common_table`` or ``efuse_custom_table`` command.
Debug efuse & Unit tests
Debug eFuse & Unit tests
------------------------
eFuse manager have option :envvar:`CONFIG_EFUSE_VIRTUAL` in Kconfig which will make an operation write is virtual. It can help to debug app and unit tests.
esptool have an useful tool for reading/writing ESP32 efuse bits - `espefuse.py <https://github.com/espressif/esptool/wiki/espefuse>`_.
esptool have an useful tool for reading/writing ESP32 eFuse bits - `espefuse.py <https://github.com/espressif/esptool/wiki/espefuse>`_.
::
@ -307,7 +307,7 @@ esptool have an useful tool for reading/writing ESP32 efuse bits - `espefuse.py
Flash voltage (VDD_SDIO) determined by GPIO12 on reset (High for 1.8V, Low/NC for 3.3V).
To get a dump for all efuse registers.
To get a dump for all eFuse registers.
::