![]() |
||
---|---|---|
.. | ||
data | ||
main | ||
CMakeLists.txt | ||
README.md | ||
pytest_semihost_vfs.py | ||
sdkconfig.defaults |
README.md
Supported Targets | ESP32 | ESP32-C3 | ESP32-C6 | ESP32-S2 | ESP32-S3 |
---|
Semihosting VFS driver example
(See the README.md file in the upper level 'examples' directory for more information about examples.)
This example demonstrates how to use semihosting VFS driver with ESP32. Example does the following steps:
- Uses
esp_vfs_semihost_register
function to register exposed host directory in VFS, enabling C standard library and POSIX functions to be used. - Redirects
stdout
from the UART to the file on the host usingfreopen
. - Prints several messages to the redirected.
- Switches back to UART
stdout
usingfreopen
. - Opens text file on the host.
- Reads the file and prints its content on stdout.
How to use example
Hardware and tools required
This example requires a development board with JTAG interface, for example:
- ESP32-Wrover-Kit, ESP32-Ethernet-Kit for ESP32
- ESP32-S2-Kaluga for ESP32-S2
- For ESP32-C3 or ESP32-S3, any board with the built-in USB interface (USB_SERIAL_JTAG)
- ESP-Prog as an external JTAG adapter with any other development board
This example also requires OpenOCD to be set up.
Build and flash
-
Replace PORT with serial port name and run this command to build and flash the example:
idf.py -p PORT flash
See the Getting Started Guide for full steps to configure and use ESP-IDF to build projects.
-
Go to
data
subdirectory of the project and run OpenOCD.cd data openocd -f board/esp32-wrover-kit-3.3v.cfg
Note that you need to use the correct configuration file for your board after
-f
option in the above command. Please refer to the list of configuration files available for ESP32, ESP32-S2, ESP32-S3, ESP32-C3. -
With OpenOCD still running, open another console or terminal and run IDF monitor there:
idf.py monitor
(To exit the serial monitor, type
Ctrl-]
.)
Overriding the base directory for semihosting
When the example application calls esp_vfs_semihost_register("/host")
, the path /host
on the ESP target is mapped to the semihosting base directory. By default, this is the directory where OpenOCD program is started from. In the instructions above, OpenOCD is started in data
subdirectory of the example project.
When debugging with Xtensa based SoCs (ESP32, ESP32-S2, ESP32-S3) it is possible to override the semihosting base directory using an additional flag of openocd
command. For example, on Linux and macOS:
openocd -c "set ESP_SEMIHOST_BASEDIR $IDF_PATH/examples/storage/semihost_vfs/data" -f board/esp32-wrover-kit-3.3v.cfg
or on Windows:
openocd -c "set ESP_SEMIHOST_BASEDIR %IDF_PATH%/examples/storage/semihost_vfs/data" -f board/esp32-wrover-kit-3.3v.cfg
The above command will set ESP_SEMIHOST_BASEDIR
variable to examples/storage/semihost_vfs/data
subdirectory of ESP-IDF. With that, it is not necessary to run OpenOCD from that specific directory.
Note: This feature is not available for RISC-V based SoCs (ESP32-C3, ESP32-H4). To set the semihosting base directory, change into the required directory before running
openocd
command.
Example output
There are two outputs produced by example:
-
The example creates and writes
esp32_stdout.txt
file in thedata
directory of the project:W (274) example: Switched to semihosted stdout Semihosted stdout write 0 Semihosted stdout write 1 Semihosted stdout write 2 ... Semihosted stdout write 98 Semihosted stdout write 99 W (274) example: Switch to UART stdout
-
The example reads data/host_file.txt and prints its contents to the serial console:
W (274) example: Switch to semihosted stdout W (274) example: Switched back to UART stdout I (274) example: Wrote 2798 bytes ====================== HOST DATA START ========================= The following are the graphical (non-control) characters defined by ISO 8859-1 (1987). Descriptions in words aren't all that helpful, but they're the best we can do in text. A graphics file illustrating the character set should be available from the same archive as this file. Hex Description Hex Description 20 SPACE ... 7D RIGHT CURLY BRACKET FD SMALL LETTER Y WITH ACUTE 7E TILDE FE SMALL LETTER THORN (Icelandic) FF SMALL LETTER Y WITH DIAERESIS ====================== HOST DATA END ========================= I (694) example: Read 6121 bytes