diff --git a/Documentation/guides/semihosting.rst b/Documentation/guides/semihosting.rst index 9233990319f..27e05c750ce 100644 --- a/Documentation/guides/semihosting.rst +++ b/Documentation/guides/semihosting.rst @@ -2,10 +2,176 @@ Semihosting =========== -.. warning:: - Migrated from: - https://cwiki.apache.org/confluence/display/NUTTX/Semihosting +Overview +======== +NuttX supports many types of semihosting (syslog, file host sharing, poweroff, etc). +The focus of this document is syslog and file sharing, since these are the most common +features used when porting NuttX to a new platform or when testing requires files from +the host machine (i.e. to play an audio file). + +Semihosting SYSLOG +------------------ + +This feature is highly valuable, particularly during the porting process to a new chip. +It allows the developer to track events and diagnose issues during the early initialization +phase, even if the UART driver support hasn't been implemented. Furthermore, it serves as a +critical debugging tool when a physical serial port isn't available for monitoring. + +These are the steps to get semihost syslog working on stm32f4discovery board, but it could +be adapted to other boards as well: + +1. Select the stm32f4discovery board with the nsh profile: + +.. code-block:: console + + $ ./tools/configure.sh stm32f4discovery:nsh + Copy files + Select CONFIG_HOST_LINUX=y + Refreshing... + +2. Run the menuconfig to select the necessary options: + +.. code-block:: console + + $ make menuconfig + +3. Enable the debug options to be displayed over syslog semihost (we want see the memory allocations) : + +.. code-block:: text + + Build Setup ---> + Debug Options ---> + [*] Enable Debug Features + [*] Enable Error Output (NEW) + [*] Enable Warnings Output (NEW) + [*] Enable Informational Debug Output (NEW) + ... + [*] Memory Manager Debug Features + [*] Memory Manager Error Output + [*] Memory Manager Warnings Output + [*] Memory Manager Informational Output + +4. Enable the semihost syslog support: + +.. code-block:: text + + System Type ---> + [*] Semihosting SYSLOG support + +5. We need to disable the /dev/console otherwise the serial initialization will be called: + +.. code-block:: text + + RTOS Features ---> + Files and I/O ---> + [ ] Enable /dev/console (disable the /dev/console) + +6. Disable the serial driver and enable syslog buffer to speed up the output: + +.. code-block:: text + + Device Drivers ---> + [ ] Serial Driver Support ---- (disable serial driver) + + System Logging ---> + [*] Use buffered output + +7. Save and leave menuconfig. + +8. Compile the firmware: + +.. code-block:: console + + $ make -j + +9. Flash the firmware in the board: + +.. code-block:: console + + $ sudo openocd -f interface/stlink.cfg -f target/stm32f4x.cfg -c init -c "reset halt" -c "flash write_image erase nuttx.bin 0x08000000" + +10. Start the openocd server to wait for GDB connection: + +.. code-block:: console + + $ sudo openocd -f interface/stlink.cfg -f target/stm32f4x.cfg -c init -c "reset halt" + Open On-Chip Debugger 0.12.0 + Licensed under GNU GPL v2 + For bug reports, read + http://openocd.org/doc/doxygen/bugs.html + Info : auto-selecting first available session transport "hla_swd". To override use 'transport select '. + Info : The selected transport took over low-level target control. The results might differ compared to plain JTAG/SWD + Info : clock speed 2000 kHz + Info : STLINK V2J14S0 (API v2) VID:PID 0483:3748 + Info : Target voltage: 3.202097 + Info : [stm32f4x.cpu] Cortex-M4 r0p1 processor detected + Info : [stm32f4x.cpu] target has 6 breakpoints, 4 watchpoints + Info : starting gdb server for stm32f4x.cpu on 3333 + Info : Listening on port 3333 for gdb connections + [stm32f4x.cpu] halted due to breakpoint, current mode: Thread + xPSR: 0x01000000 pc: 0x08004b68 msp: 0x200016b0 + [stm32f4x.cpu] halted due to debug-request, current mode: Thread + xPSR: 0x01000000 pc: 0x0800052c msp: 0x200017f0 + Info : Listening on port 6666 for tcl connections + Info : Listening on port 4444 for telnet connections + +11. Open another terminal go to the same directory where you compiled nuttx and run GDB passing the ELF file (nuttx) + +.. code-block:: console + + $ gdb-multiarch -ex "set architecture arm" nuttx + GNU gdb (Ubuntu 15.0.50.20240403-0ubuntu1) 15.0.50.20240403-git + Copyright (C) 2024 Free Software Foundation, Inc. + ... + Reading symbols from nuttx... + The target architecture is set to "arm". + + (gdb) target extended-remote 127.0.0.1:3333 + Remote debugging using 127.0.0.1:3333 + 0x0800052c in start () + + (gdb) monitor arm semihosting enable + semihosting is enabled + + (gdb) monitor arm semihosting_fileio enable + semihosting fileio is enabled + + (gdb) monitor reset halt + [stm32f4x.cpu] halted due to debug-request, current mode: Thread + xPSR: 0x01000000 pc: 0x0800052c msp: 0x200017f0, semihosting fileio + + (gdb) c + Continuing. + mm_initialize: Heap: name=Umem, start=0x200017f0 size=124944 + mm_addregion: [Umem] Region 1: base=0x20001960 size=124576 + mm_malloc: Allocated 0x20001970, size 72 + mm_malloc: Allocated 0x200019b8, size 40 + mm_addregion: [Umem] Region 2: base=0x10000000 size=65536 + mm_malloc: Allocated 0x10000010, size 48 + mm_malloc: Allocated 0x10000040, size 48 + mm_malloc: Allocated 0x10000070, size 48 + mm_malloc: Allocated 0x100000a0, size 24 + mm_malloc: Allocated 0x100000b8, size 16 + mm_malloc: Allocated 0x100000c8, size 32 + mm_malloc: Allocated 0x100000e8, size 208 + mm_malloc: Allocated 0x100001b8, size 2056 + mm_malloc: Allocated 0x100009c0, size 48 + mm_malloc: Allocated 0x100009f0, size 896 + mm_malloc: Allocated 0x10000d70, size 32 + mm_malloc: Allocated 0x10000d90, size 16 + mm_malloc: Allocated 0x10000da0, size 2056 + mm_free: Freeing 0x100001b8 + mm_free: Freeing 0x100000e8 + mm_malloc: Allocated 0x100000e8, size 768 + mm_free: Freeing 0x100000e8 + mm_free: Freeing 0x10000d90 + mm_free: Freeing 0x10000d70 + mm_free: Freeing 0x10000da0 + mm_free: Freeing 0x100009f0 + +Semihosting files +----------------- Relevant files: @@ -19,4 +185,4 @@ Mounting: .. code-block:: bash - mount -t hostfs -o fs=/host/path /local/path \ No newline at end of file + mount -t hostfs -o fs=/host/path /local/path