Merge branch 'feature/apptrace_api_ext' into 'master'

esp32: Apptrace API enhancement

See merge request !1021

diff --cc docs/api-guides/app_trace.rst
index da5e4c37b424a3662bc8f3d26e3a9017dd2cf83e,0873decb2d397807fef0ac0b0d68daf9870e6c2e..c3fd79a06d53c15b64f9b19fd3e3c01cff107e65
--- 1/docs/api-guides/app_trace.rst
--- 2/docs/api-guides/app_trace.rst
+++ b/docs/api-guides/app_trace.rst
@@@ -112,8 -116,39 +116,39 @@@ Also according to his needs user may wa
          ...
      }
  
+ ``esp_apptrace_read()`` function uses memcpy to copy host data to user buffer. In some cases it can be more optimal to use ``esp_apptrace_down_buffer_get()`` and ``esp_apptrace_down_buffer_put()`` functions.
+ They allow developers to ocupy chunk of read buffer and process it in-place. The following piece of code shows how to do this.
+ 
+ .. code-block:: c
+ 
+     #include "esp_app_trace.h"
+     ...
+     char down_buf[32];
+     uint32_t *number;
+     size_t sz = 32;
+ 
+     /* config down buffer */
+     esp_apptrace_down_buffer_config(down_buf, sizeof(down_buf));
+     char *ptr = (char *)esp_apptrace_down_buffer_get(ESP_APPTRACE_DEST_TRAX, &sz, 100/*tmo in us*/);
+     if (ptr == NULL) {
+         ESP_LOGE("Failed to get buffer!");
+         return ESP_FAIL;
+     }
+     if (sz > 4) {
+         number = (uint32_t *)ptr;
+         printf("Here is the number %d", *number);
+     } else {
+         printf("No data");
+     }
+     esp_err_t res = esp_apptrace_down_buffer_put(ESP_APPTRACE_DEST_TRAX, ptr, 100/*tmo in us*/);
+     if (res != ESP_OK) {
+         /* in case of error host tracing tool (e.g. OpenOCD) will report incomplete user buffer */
+         ESP_LOGE("Failed to put buffer!");
+         return res;
+     }
+ 
  2. The next step is to build the program image and download it to the target as described in :doc:`Build and Flash <../get-started/make-project>`.
 -3. Run OpenOCD (see :doc:`Debugging <../api-guides/openocd>`).
 +3. Run OpenOCD (see :doc:`JTAG Debugging <../api-guides/jtag-debugging/index>`).
  4. Connect to OpenOCD telnet server. On Linux it can be done using the following command in terminal ``telnet <oocd_host> 4444``. If telnet session is opened on the same machine which runs OpenOCD you can use ``localhost`` as ``<oocd_host>`` in the command above.
  5. Start trace data collection using special OpenOCD command. This command will transfer tracing data and redirect them to specified file or socket (currently only files are supported as trace data destination). For description of the corresponding commands see `OpenOCD Application Level Tracing Commands`_.
  6. The final step is to process received data. Since format of data is defined by user the processing stage is out of the scope of this document. Good starting points for data processor are python scripts in ``$IDF_PATH/tools/esp_app_trace``: ``apptrace_proc.py`` (used for feature tests) and ``logtrace_proc.py`` (see more details in section `Logging to Host`_).