espressif/esp-idf
1
0
Fork 0
mirror of https://github.com/espressif/esp-idf.git synced 2026-04-27 19:13:21 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: Generate Doxygen directives for API documentation

Browse Source 
This is to resolve issue reported in https://github.com/espressif/esp-idf/issues/130.
This commit is contained in:
krzychb
2017-05-02 10:36:01 +02:00
parent a38cecefa7
commit 30edcca1fb
62 changed files with 771 additions and 2540 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/api-reference/system/base_mac_address.rst
+23 -18
View File
@@ -4,7 +4,7 @@ Base MAC address
Overview
--------
Serveral universally administered(by IEEE) MAC addresses are uniquely assigned to the networking interfaces(WiFi/BT/Ethernet).
Serveral MAC addresses (universally administered by IEEE) are uniquely assigned to the networking interfaces (WiFi/BT/Ethernet).
The final octet of each universally administered MAC address increases by one. Only the first one which is called base MAC address
of them is stored in EFUSE or external storage, the others are generated from it. Here, 'generate' means adding 0, 1, 2 and 3
(respectively) to the final octet of the base MAC address.
@@ -12,7 +12,7 @@ of them is stored in EFUSE or external storage, the others are generated from it
If the universally administered MAC addresses are not enough for all of the networking interfaces. Local administered MAC addresses
which are derived from universally administered MAC addresses are assigned to the reset of networking interfaces.
A `definition of local vs universal MAC address can be found on Wikipedia<https://en.wikipedia.org/wiki/MAC_address#Universal_vs._local>`.
A `definition of local vs universal MAC address can be found on Wikipedia <https://en.wikipedia.org/wiki/MAC_address#Universal_vs._local>`_.
The number of universally administered MAC address can be configured using ``make menuconfig``.
@@ -21,30 +21,35 @@ Base MAC address
If using the default base MAC address factory programmed by Espressif in BLK0 of EFUSE, nothing needs to be done.
If using a custom base MAC address stored in BLK3 of EFUSE, call API esp_efuse_mac_get_custom() to get the base MAC address
which is stored in BLK3 of EFUSE. If correct MAC address is returned, then call esp_base_mac_addr_set() to set the base MAC
If using a custom base MAC address stored in BLK3 of EFUSE, call API ``esp_efuse_mac_get_custom()`` to get the base MAC address
which is stored in BLK3 of EFUSE. If correct MAC address is returned, then call ``esp_base_mac_addr_set()`` to set the base MAC
address for system to generate the MAC addresses used by the networking interfaces(WiFi/BT/Ethernet).
There are 192 bits storage spaces for custom to store base MAC address in BLK3 of EFUSE. They are EFUSE_BLK3_RDATA0,
EFUSE_BLK3_RDATA1, EFUSE_BLK3_RDATA2, EFUSE_BLK3_RDATA3, EFUSE_BLK3_RDATA4 and EFUSE_BLK3_RDATA5, each of them is 32 bits
register. The format of the 192 bits storage spaces is:
------------------------------------------------------
Field |Bits |Range |Description
------------------------------------------------------
version |8 |[191:184] |1: useful. 0: useless
------------------------------------------------------
reserve |112 |[183:72] |reserved
------------------------------------------------------
mac address |64 |[71:8] |base MAC address
------------------------------------------------------
mac crc |8 |[7:0] |crc of base MAC address
------------------------------------------------------
.. highlight:: none
::
------------------------------------------------------
Field |Bits |Range |Description
------------------------------------------------------
version |8 |[191:184] |1: useful. 0: useless
------------------------------------------------------
reserve |112 |[183:72] |reserved
------------------------------------------------------
mac address |64 |[71:8] |base MAC address
------------------------------------------------------
mac crc |8 |[7:0] |crc of base MAC address
------------------------------------------------------
If using base MAC address stored in external storage, firstly get the base MAC address stored in external storage, then call
API esp_base_mac_addr_set() to set the base MAC address for system to generate the MAC addresses used by the networking
API ``esp_base_mac_addr_set()`` to set the base MAC address for system to generate the MAC addresses used by the networking
interfaces(WiFi/BT/Ethernet).
All of the steps must be done before initializing the networking interfaces(WiFi/BT/Ethernet). It is recommended to do it in
app_main() which can be referenced in example `system/base_mac_address`.
``app_main()`` which can be referenced in :example:`system/base_mac_address`.
Number of universally administered MAC address
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -74,4 +79,4 @@ Functions
---------
.. doxygenfunction:: esp_base_mac_addr_set
.. doxygenfunction:: esp_efuse_mac_get_custom
.. doxygenfunction:: esp_efuse_mac_get_custom
docs/api-reference/system/intr_alloc.rst
+1 -38
View File
@@ -83,46 +83,9 @@ It can also be useful to keep an interrupt handler in IRAM if it is called very
Refer to the :ref:`SPI flash API documentation <iram-safe-interrupt-handlers>` for more details.
Application Example
-------------------
API Reference
-------------
Header Files
^^^^^^^^^^^^
* :component_file:`esp32/include/esp_intr_alloc.h`
.. include:: /_build/inc/esp_intr_alloc.inc
Macros
^^^^^^
.. doxygendefine:: ESP_INTR_FLAG_LEVEL1
.. doxygendefine:: ESP_INTR_FLAG_LEVEL2
.. doxygendefine:: ESP_INTR_FLAG_LEVEL3
.. doxygendefine:: ESP_INTR_FLAG_LEVEL4
.. doxygendefine:: ESP_INTR_FLAG_LEVEL5
.. doxygendefine:: ESP_INTR_FLAG_LEVEL6
.. doxygendefine:: ESP_INTR_FLAG_NMI
.. doxygendefine:: ESP_INTR_FLAG_LOWMED
.. doxygendefine:: ESP_INTR_FLAG_HIGH
.. doxygendefine:: ESP_INTR_FLAG_SHARED
.. doxygendefine:: ESP_INTR_FLAG_EDGE
.. doxygendefine:: ESP_INTR_FLAG_IRAM
.. doxygendefine:: ESP_INTR_FLAG_INTRDISABLED
Functions
^^^^^^^^^
.. doxygenfunction:: esp_intr_mark_shared
.. doxygenfunction:: esp_intr_reserve
.. doxygenfunction:: esp_intr_alloc
.. doxygenfunction:: esp_intr_alloc_intrstatus
.. doxygenfunction:: esp_intr_free
.. doxygenfunction:: esp_intr_get_cpu
.. doxygenfunction:: esp_intr_get_intno
.. doxygenfunction:: esp_intr_disable
.. doxygenfunction:: esp_intr_enable
.. doxygenfunction:: esp_intr_noniram_disable
.. doxygenfunction:: esp_intr_noniram_enable
docs/api-reference/system/log.rst
+1 -51
View File
@@ -12,57 +12,7 @@ Log library is commonly used by most of esp-idf components and examples. For dem
API Reference
-------------
Header Files
^^^^^^^^^^^^
* :component_file:`log/include/esp_log.h`
Macros
^^^^^^
.. doxygendefine:: LOG_COLOR_E
.. doxygendefine:: LOG_COLOR_W
.. doxygendefine:: LOG_COLOR_I
.. doxygendefine:: LOG_COLOR_D
.. doxygendefine:: LOG_COLOR_V
.. doxygendefine:: LOG_RESET_COLOR
.. doxygendefine:: LOG_FORMAT
.. doxygendefine:: LOG_LOCAL_LEVEL
.. doxygendefine:: ESP_EARLY_LOGE
.. doxygendefine:: ESP_EARLY_LOGW
.. doxygendefine:: ESP_EARLY_LOGI
.. doxygendefine:: ESP_EARLY_LOGD
.. doxygendefine:: ESP_EARLY_LOGV
.. doxygendefine:: ESP_LOGE
.. doxygendefine:: ESP_LOGW
.. doxygendefine:: ESP_LOGI
.. doxygendefine:: ESP_LOGD
.. doxygendefine:: ESP_LOGV
Type Definitions
^^^^^^^^^^^^^^^^
.. doxygentypedef:: vprintf_like_t
Enumerations
^^^^^^^^^^^^
.. doxygenenum:: esp_log_level_t
Functions
^^^^^^^^^
.. doxygenfunction:: esp_log_level_set
.. doxygenfunction:: esp_log_set_vprintf
.. doxygenfunction:: esp_log_timestamp
.. doxygenfunction:: esp_log_write
.. include:: /_build/inc/esp_log.inc
docs/api-reference/system/mem_alloc.rst
+7 -42
View File
@@ -1,5 +1,5 @@
Memory allocation
====================
=================
Overview
--------
@@ -30,48 +30,13 @@ If a certain memory structure is only addressed in 32-bit units, for example an
useful to allocate it with the MALLOC_CAP_32BIT flag. This also allows the allocator to give out IRAM memory; something
which it can't do for a normal malloc() call. This can help to use all the available memory in the ESP32.
API Reference - Heap Allocation
-------------------------------
API Reference
-------------
.. include:: /_build/inc/esp_heap_alloc_caps.inc
Header Files
^^^^^^^^^^^^
API Reference - Heap Regions
----------------------------
* :component_file:`esp32/include/esp_heap_alloc_caps.h`
* :component_file:`freertos/include/freertos/heap_regions.h`
.. include:: /_build/inc/heap_regions.inc
Macros
^^^^^^
.. doxygendefine:: MALLOC_CAP_EXEC
.. doxygendefine:: MALLOC_CAP_32BIT
.. doxygendefine:: MALLOC_CAP_8BIT
.. doxygendefine:: MALLOC_CAP_DMA
.. doxygendefine:: MALLOC_CAP_PID2
.. doxygendefine:: MALLOC_CAP_PID3
.. doxygendefine:: MALLOC_CAP_PID4
.. doxygendefine:: MALLOC_CAP_PID5
.. doxygendefine:: MALLOC_CAP_PID6
.. doxygendefine:: MALLOC_CAP_PID7
.. doxygendefine:: MALLOC_CAP_SPISRAM
.. doxygendefine:: MALLOC_CAP_INVALID
Type Definitions
^^^^^^^^^^^^^^^^
.. doxygentypedef:: HeapRegionTagged_t
Functions
^^^^^^^^^
.. doxygenfunction:: heap_alloc_caps_init
.. doxygenfunction:: pvPortMallocCaps
.. doxygenfunction:: xPortGetFreeHeapSizeCaps
.. doxygenfunction:: xPortGetMinimumEverFreeHeapSizeCaps
.. doxygenfunction:: vPortDefineHeapRegionsTagged
.. doxygenfunction:: pvPortMallocTagged
.. doxygenfunction:: vPortFreeTagged
.. doxygenfunction:: xPortGetMinimumEverFreeHeapSizeTagged
.. doxygenfunction:: xPortGetFreeHeapSizeTagged
docs/api-reference/system/ota.rst
+3 -28
View File
@@ -2,7 +2,7 @@ Over The Air Updates (OTA)
==========================
OTA Process Overview
^^^^^^^^^^^^^^^^^^^^
--------------------
The OTA update mechanism allows a device to update itself based on data received while the normal firmware is running
(for example, over WiFi or Bluetooth.)
@@ -17,7 +17,7 @@ next boot.
.. _ota_data_partition:
OTA Data Partition
^^^^^^^^^^^^^^^^^^
------------------
An OTA data partition (type ``data``, subtype ``ota``) must be included in the :doc:`Partition Table <../../api-guides/partition-tables>`
of any project which uses the OTA functions.
@@ -46,32 +46,7 @@ End-to-end example of OTA firmware update workflow: :example:`system/ota`.
API Reference
-------------
Header Files
^^^^^^^^^^^^
.. include:: /_build/inc/esp_ota_ops.inc
* :component_file:`app_update/include/esp_ota_ops.h`
Macros
^^^^^^
.. doxygendefine:: ESP_ERR_OTA_BASE
.. doxygendefine:: ESP_ERR_OTA_PARTITION_CONFLICT
.. doxygendefine:: ESP_ERR_OTA_SELECT_INFO_INVALID
.. doxygendefine:: ESP_ERR_OTA_VALIDATE_FAILED
.. doxygendefine:: OTA_SIZE_UNKNOWN
Type Definitions
^^^^^^^^^^^^^^^^
.. doxygentypedef:: esp_ota_handle_t
Functions
^^^^^^^^^
.. doxygenfunction:: esp_ota_begin
.. doxygenfunction:: esp_ota_write
.. doxygenfunction:: esp_ota_end
.. doxygenfunction:: esp_ota_get_running_partition
.. doxygenfunction:: esp_ota_set_boot_partition
.. doxygenfunction:: esp_ota_get_boot_partition
.. doxygenfunction:: esp_ota_get_next_update_partition