Merge branch 'bugfix/to_docs_from_github' into 'master'

Documentation bugfixes from the github See merge request !1501
2017-11-10 11:13:25 +08:00 · 2017-11-10 11:13:25 +08:00 · 3eedf3ed18
parent d1f6030921 bb4838314c
commit 3eedf3ed18
9 changed files with 31 additions and 33 deletions
--- a/README.md
+++ b/README.md
@ -96,7 +96,7 @@ The simplest way to use the partition table is to `make menuconfig` and choose o

 In both cases the factory app is flashed at offset 0x10000. If you `make partition_table` then it will print a summary of the partition table.

-For more details about partition tables and how to create custom variations, view the `docs/partition-tables.rst` file.
+For more details about partition tables and how to create custom variations, view the [`docs/api-guides/partition-tables.rst`](docs/api-guides/partition-tables.rst) file.

 ## Erasing Flash

--- a/components/esp32/include/esp_wifi.h
+++ b/components/esp32/include/esp_wifi.h
@ -523,11 +523,12 @@ esp_err_t esp_wifi_get_channel(uint8_t *primary, wifi_second_chan_t *second);
  * @brief     configure country info
  *
  * @attention 1. The default country is {.cc="CN", .schan=1, .nchan=13, policy=WIFI_COUNTRY_POLICY_AUTO}
-  * @attention 2. When the country policy is WIFI_COUNTRY_POLICY_AUTO, use the country info of AP to which 
-  *               the station is connected. E.g. if the configured country info is {.cc="USA", .schan=1, .nchan=11}, 
-  *               the country info of the AP to which the station is connected is {.cc="JP", .schan=1, .nchan=14},
-  *               then our country info is {.cc="JP", .schan=1, .nchan=14}. If the station disconnected
-  *               from the AP, the country info back to {.cc="USA", .schan=1, .nchan=11} again.
+  * @attention 2. When the country policy is WIFI_COUNTRY_POLICY_AUTO, the country info of the AP to which
+  *               the station is connected is used. E.g. if the configured country info is {.cc="USA", .schan=1, .nchan=11}
+  *               and the country info of the AP to which the station is connected is {.cc="JP", .schan=1, .nchan=14}
+  *               then the country info that will be used is {.cc="JP", .schan=1, .nchan=14}. If the station disconnected
+  *               from the AP the country info is set back back to the country info of the station automatically,
+  *               {.cc="USA", .schan=1, .nchan=11} in the example.
  * @attention 3. When the country policy is WIFI_COUNTRY_POLICY_MANUAL, always use the configured country info.
  * @attention 4. When the country info is changed because of configuration or because the station connects to a different
  *               external AP, the country IE in probe response/beacon of the soft-AP is changed also.
--- a/components/heap/include/esp_heap_caps.h
+++ b/components/heap/include/esp_heap_caps.h
@ -40,7 +40,7 @@
 *
 * Equivalent semantics to libc malloc(), for capability-aware memory.
 *
- * In IDF, ``malloc(p)`` is equivalent to ``heaps_caps_malloc(p, MALLOC_CAP_8BIT)``.
+ * In IDF, ``malloc(p)`` is equivalent to ``heap_caps_malloc(p, MALLOC_CAP_8BIT)``.
 *
 * @param size Size, in bytes, of the amount of memory to allocate
 * @param caps        Bitwise OR of MALLOC_CAP_* flags indicating the type
@ -63,7 +63,7 @@ void *heap_caps_malloc(size_t size, uint32_t caps);
 void heap_caps_free( void *ptr);

 /**
- * @brief Reallocate memory previously allocated via heaps_caps_malloc() or heaps_caps_realloc().
+ * @brief Reallocate memory previously allocated via heap_caps_malloc() or heaps_caps_realloc().
 *
 * Equivalent semantics to libc realloc(), for capability-aware memory.
 *
--- a/docs/api-guides/app_trace.rst
+++ b/docs/api-guides/app_trace.rst
@ -9,9 +9,9 @@ IDF provides useful feature for program behaviour analysis: application level tr

 Developers can use this library to send application specific state of execution to the host and receive commands or other type of info in the opposite direction at runtime. The main use cases of this library are:

-1. Collecting application specific data. See `Application Specific Tracing`_.
-2. Lightweight logging to the host. See `Logging to Host`_.
-3. System behaviour analysis. See `System Behaviour Analysis with SEGGER SystemView`_.
+1. Collecting application specific data, see :ref:`app_trace-application-specific-tracing`
+2. Lightweight logging to the host, see :ref:`app_trace-logging-to-host`
+3. System behaviour analysis, see :ref:`app_trace-system-behaviour-analysis-with-segger-systemview`

 Tracing components when working over JTAG interface are shown in the figure below.

@ -56,6 +56,7 @@ How to use this library

 This library provides API for transferring arbitrary data between host and ESP32. When enabled in menuconfig target application tracing module is initialized automatically at the system startup, so all what the user needs to do is to call corresponding API to send, receive or flush the data.

+.. _app_trace-application-specific-tracing:

 Application Specific Tracing
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@ -307,6 +308,7 @@ Optional arguments:
 ``--no-errors``, ``-n``
    Do not print errors

+.. _app_trace-system-behaviour-analysis-with-segger-systemview:

 System Behaviour Analysis with SEGGER SystemView
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
--- a/docs/api-guides/build-system.rst
+++ b/docs/api-guides/build-system.rst
@ -89,7 +89,7 @@ This example "myProject" contains the following elements:
 - "build" directory is where build output is created. After the make process is run, this directory will contain interim object files and libraries as well as final binary output files. This directory is usually not added to source control or distributed with the project source code.

 Component directories contain a component makefile - ``component.mk``. This may contain variable definitions
-to control the build process of the component, and its integration into the overall project. See `Component Makefiles` for more details.
+to control the build process of the component, and its integration into the overall project. See `Component Makefiles`_ for more details.

 Each component may also include a ``Kconfig`` file defining the `component configuration` options that can be set via the project configuration. Some components may also include ``Kconfig.projbuild`` and ``Makefile.projbuild`` files, which are special files for `overriding parts of the project`.

@ -160,7 +160,7 @@ The minimal ``component.mk`` file is an empty file(!). If the file is empty, the
 - A sub-directory "include" will be added to the global include search path for all other components.
 - The component library will be linked into the project app.

-See `example component makefiles` for more complete component makefile examples.
+See `example component makefiles`_ for more complete component makefile examples.

 Note that there is a difference between an empty ``component.mk`` file (which invokes default component build behaviour) and no ``component.mk`` file (which means no default component build behaviour will occur.) It is possible for a component to have no `component.mk` file, if it only contains other files which influence the project configuration or build process.

@ -247,10 +247,10 @@ The following variables can be set inside ``component.mk`` to control the build
 - ``COMPONENT_EXTRA_CLEAN``: Paths, relative to the component build
  directory, of any files that are generated using custom make rules
  in the component.mk file and which need to be removed as part of
-  ``make clean``. See `Source Code Generation` for an example.
+  ``make clean``. See `Source Code Generation`_ for an example.
 - ``COMPONENT_OWNBUILDTARGET`` & ``COMPONENT_OWNCLEANTARGET``: These
  targets allow you to fully override the default build behaviour for
-  the component. See `Fully Overriding The Component Makefile` for
+  the component. See `Fully Overriding The Component Makefile`_ for
  more details.
 - ``COMPONENT_CONFIG_ONLY``: If set, this flag indicates that the component
  produces no built output at all (ie ``COMPONENT_LIBRARY`` is not built),
@ -289,7 +289,7 @@ These settings are found under the "Component Settings" menu when menuconfig is

 To create a component KConfig file, it is easiest to start with one of the KConfig files distributed with esp-idf.

-For an example, see `Adding conditional configuration`.
+For an example, see `Adding conditional configuration`_.

 Preprocessor Definitions
 ------------------------
@ -310,7 +310,7 @@ Top Level: Project Makefile
 - The project makefile includes ``$(IDF_PATH)/make/project.mk`` which contains the project-level Make logic.
 - ``project.mk`` fills in default project-level make variables and includes make variables from the project configuration. If the generated makefile containing project configuration is out of date, then it is regenerated (via targets in ``project_config.mk``) and then the make process restarts from the top.
 - ``project.mk`` builds a list of components to build, based on the default component directories or a custom list of components set in `optional project variables`.
- Each component can set some `optional project-wide component variables`. These are included via generated makefiles named ``component_project_vars.mk`` - there is one per component. These generated makefiles are included into ``project.mk``. If any are missing or out of date, they are regenerated (via a recursive make call to the component makefile) and then the make process restarts from the top.
+- Each component can set some `optional project-wide component variables`_. These are included via generated makefiles named ``component_project_vars.mk`` - there is one per component. These generated makefiles are included into ``project.mk``. If any are missing or out of date, they are regenerated (via a recursive make call to the component makefile) and then the make process restarts from the top.
 - `Makefile.projbuild` files from components are included into the make process, to add extra targets or configuration. 
 - By default, the project makefile also generates top-level build & clean targets for each component and sets up `app` and `clean` targets to invoke all of these sub-targets.
 - In order to compile each component, a recursive make is performed for the component makefile.
@ -378,7 +378,7 @@ project (not just for its own source files) then you can set

 ``Makefile.projbuild`` files are used heavily inside esp-idf, for defining project-wide build features such as ``esptool.py`` command line arguments and the ``bootloader`` "special app".

-Note that ``Makefile.projbuild`` isn't necessary for the most common component uses - such as adding include directories to the project, or LDFLAGS to the final linking step. These values can be customised via the ``component.mk`` file itself. See `Optional Project-Wide Component Variables` for details.
+Note that ``Makefile.projbuild`` isn't necessary for the most common component uses - such as adding include directories to the project, or LDFLAGS to the final linking step. These values can be customised via the ``component.mk`` file itself. See `Optional Project-Wide Component Variables`_ for details.

 Take care when setting variables or targets in this file. As the values are included into the top-level project makefile pass, they can influence or break functionality across all components!

@ -399,7 +399,7 @@ Example Component Makefiles
 ---------------------------

 Because the build environment tries to set reasonable defaults that will work most
-of the time, component.mk can be very small or even empty (see `Minimal Component Makefile`). However, overriding `component variables` is usually required for some functionality.
+of the time, component.mk can be very small or even empty (see `Minimal Component Makefile`_). However, overriding `component variables` is usually required for some functionality.

 Here are some more advanced examples of ``component.mk`` makefiles:

--- a/docs/api-reference/system/app_trace.rst
+++ b/docs/api-reference/system/app_trace.rst
@ -7,9 +7,9 @@ Overview
 IDF provides useful feature for program behaviour analysis: application level tracing. It is implemented in the corresponding library and can be enabled via menuconfig. This feature allows to transfer arbitrary data between host and ESP32 via JTAG interface with small overhead on program execution.
 Developers can use this library to send application specific state of execution to the host and receive commands or other type of info in the opposite direction at runtime. The main use cases of this library are:

-1. System behaviour analysis.
-2. Lightweight logging to the host.
-3. Collecting application specific data.
+1. Collecting application specific data, see :ref:`app_trace-application-specific-tracing`
+2. Lightweight logging to the host, see :ref:`app_trace-logging-to-host`
+3. System behaviour analysis, see :ref:`app_trace-system-behaviour-analysis-with-segger-systemview`

 API Reference
 -------------
--- a/docs/api-reference/system/heap_debug.rst
+++ b/docs/api-reference/system/heap_debug.rst
@ -54,7 +54,7 @@ Memory corruption can be one of the hardest classes of bugs to find and fix, as
 - Adding regular calls to :cpp:func:`heap_caps_check_integrity_all` or :cpp:func:`heap_caps_check_integrity_addr` in your code will help you pin down the exact time that the corruption happened. You can move these checks around to "close in on" the section of code that corrupted the heap.
 - Based on the memory address which is being corrupted, you can use :ref:`JTAG debugging <jtag-debugging-introduction>` to set a watchpoint on this address and have the CPU halt when it is written to.
 - If you don't have JTAG, but you do know roughly when the corruption happens, then you can set a watchpoint in software just beforehand via :cpp:func:`esp_set_watchpoint`. A fatal exception will occur when the watchpoint triggers. For example ``esp_set_watchpoint(0, (void *)addr, 4, ESP_WATCHPOINT_STORE``. Note that watchpoints are per-CPU and are set on the current running CPU only, so if you don't know which CPU is corrupting memory then you will need to call this function on both CPUs.
- For buffer overflows, `heap tracing`_ in ``HEAP_TRACE_ALL`` mode lets you see which callers are allocating which addresses from the heap. See `Heap Tracing To Find Heap Corruption` for more details. If you can find the function which allocates memory with an address immediately before the address which is corrupted, this will probably be the function which overflows the buffer.
+- For buffer overflows, `heap tracing`_ in ``HEAP_TRACE_ALL`` mode lets you see which callers are allocating which addresses from the heap. See `Heap Tracing To Find Heap Corruption`_ for more details. If you can find the function which allocates memory with an address immediately before the address which is corrupted, this will probably be the function which overflows the buffer.
 - Calling :cpp:func:`heap_caps_dump` or :cpp:func:`heap_caps_dump_all` can give an indication of what heap blocks are surrounding the corrupted region and may have overflowed/underflowed/etc.

 Configuration
--- a/docs/security/secure-boot.rst
+++ b/docs/security/secure-boot.rst
@ -174,7 +174,7 @@ The first stage of secure boot verification (checking the software bootloader) i

 1. Generate a random sequence of bytes from a hardware random number generator.

-2. Generate a digest from data (usually the bootloader image from flash) using a key stored in Efuse block 2. The key in Efuse can (& should) be read/write protected, which prevents software access. For full details of this algorithm see `Secure Bootloader Digest Algorithm`. The digest can only be read back by software if Efuse ABS_DONE_0 is *not* burned (ie still 0).
+2. Generate a digest from data (usually the bootloader image from flash) using a key stored in Efuse block 2. The key in Efuse can (& should) be read/write protected, which prevents software access. For full details of this algorithm see `Secure Bootloader Digest Algorithm`_. The digest can only be read back by software if Efuse ABS_DONE_0 is *not* burned (ie still 0).

 3. Generate a digest from data (usually the bootloader image from flash) using the same algorithm as step 2 and compare it to a pre-calculated digest supplied in a buffer (usually read from flash offset 0x0). The hardware returns a true/false comparison without making the digest available to software. This function is available even when Efuse ABS_DONE_0 is burned.

--- a/examples/peripherals/gpio/README.md
+++ b/examples/peripherals/gpio/README.md
@ -1,20 +1,15 @@
 # Example: GPIO

-###This test code shows how to configure gpio and how to use gpio interrupt.
+This test code shows how to configure gpio and how to use gpio interrupt.

- 
-####GPIO functions:
+## GPIO functions:

 * GPIO18: output
 * GPIO19: output
 * GPIO4:  input, pulled up, interrupt from rising edge and falling edge
 * GPIO5:  input, pulled up, interrupt from rising edge.
- 
-####Test:
+
+## Test:
 * Connect GPIO18 with GPIO4
 * Connect GPIO19 with GPIO5
 * Generate pulses on GPIO18/19, that triggers interrupt on GPIO4/5
- 
-
-
-