The idea is to replace standard input and output on the microcontroller. In our systems we have neither a screen with a console nor a keyboard. However, that doesn\u2019t mean we can\u2019t use them.<\/p>\n\n\n\n
Semihosting allows you to use your computer\u2019s resources as standard input and output<\/strong> for the microcontroller. What resources? The console and the keyboard.<\/p>\n\n\n\n All of this happens thanks to special instructions<\/strong> in the microcontroller that trigger system exceptions (e.g., the SVC instruction \u2013 SuperVisor Call). Such an exception is intercepted by appropriate functions and the hardware debugger.<\/strong> It can now redirect data from the microcontroller straight to our computer and vice versa<\/strong>.<\/p>\n\n\n\n On the PC side, this is received by the software that started debugging the code on the microcontroller. It provides the console and keyboard for use precisely through this \u201ctunnel\u201d.<\/p>\n\n\n\n Now the best part. Which microcontroller pins are used for such communication?<\/p>\n\n\n\n Exactly the same ones as in \u201cclassic\u201d debugging. These are SWCLK and SWDIO.<\/strong> Nothing more!<\/p>\n\n\n\n We don\u2019t have to change the hardware configuration.<\/strong> Heck! We don\u2019t have to \u201cwaste\u201d a UART interface just to print something to the console for debugging purposes.<\/p>\n\n\n\n This is a huge advantage of Semihosting.<\/strong> UART eats 2 pins, and SWV one \u2013 SWO. If you have a constrained project where you don\u2019t have any free pins, you already have an \u201cinterface\u201d for printing logs from the program\u2019s operation.<\/p>\n\n\n\n So let\u2019s move on to configuring this Semihosting.<\/p>\n\n\n\n As a test board I used the Discovery B-U585I-IOT02A<\/strong><\/a> kit. It\u2019s a board with the newest baby from STMicroelectronics, i.e. STM32U5<\/strong>. I recently wrote about their capabilities.<\/a><\/p>\n\n\n\n Currently I\u2019m using this platform on Live Streams<\/strong>, which I run regularly on Tuesdays at 18:00 on my YouTube<\/a><\/strong> (the content is in Polish).<\/p>\n\n\n\n Most important info! <\/strong>This method is identical for all STM32 microcontrollers (and not only them). If you have a different chip, everything will look the same.<\/p>\n\n\n\n Let\u2019s get to the specifics. How do you set up Semihosting on STM32? There are a few steps.<\/p>\n\n\n\n You need to choose the right debugger on the computer side. That will be OpenOCD.<\/strong><\/p>\n\n\n\n Unfortunately, the default ST-Link GDB does not support<\/strong> Semihosting.<\/p>\n\n\n\n You set the debugging configuration during the first debug run. If you\u2019ve already done it, under the bug icon you have Debug Configurations<\/strong><\/em>.<\/p>\n\n\n\n Now, as Debug Probe <\/strong><\/em>set ST-Link (OpenOCD).<\/strong><\/p>\n\n\n\n For the program to know how to use, for example, system exceptions in order to use Semihosting, you need to include an external library. It\u2019s a precompiled library, so you do it only at the linker stage<\/strong>.<\/p>\n\n\n\n If you enter parameters manually, then add to the linker options<\/strong><\/p>\n\n\n\n If, like me, you use STM32CubeIDE, then add it in the appropriate linker options:<\/p>\n\n\n\n Project > Properties > C\/C++ Build > Settings > MCU GCC Linker<\/strong><\/p>\n\n\n\n In Libraries<\/strong> add rdimon.<\/em><\/strong><\/p>\n\n\n\n In Miscellaneous<\/strong> enter:<\/p>\n\n\n\n STM32CubeMX generates a default syscalls.c file<\/strong>. It contains empty system call functions.<\/strong> They\u2019re there for us to use if we wanted to write something ourselves, e.g. semihosting or something similar.<\/p>\n\n\n\n We most likely won\u2019t do that ourselves. Additionally, the same functions are included externally via what we attached to the linker.<\/p>\n\n\n\n There will be a clash. That means the compiler may tell us that we have some duplicate definitions. You need to exclude this file from compilation.<\/strong><\/p>\n\n\n\n You could delete it, but\u2026 it will come back after regenerating files with CubeMX. You need to exclude it completely.<\/strong><\/p>\n\n\n\n Right-click on this file > Properties > check the box \u201cExclude resource from build\u201d<\/strong><\/p>\n\n\n\n We\u2019ve already configured everything on the microcontroller side. Now in our program it remains to call the initialization function<\/strong> for Semihosting\u2014just like we initialize any interface before using it.<\/p>\n\n\n\n This is done with the function:<\/p>\n\n\n\n It\u2019s enough to add it in main before the main loop.<\/strong> We can do this even before initializing HAL. Then we\u2019ll be able to send something to the console even before the whole HAL comes up.<\/p>\n\n\n\n So that the compiler doesn\u2019t complain that it doesn\u2019t know it, you must add its prototype<\/strong> with an extern annotation (in the rdimon library) somewhere at the top of the file.<\/p>\n\n\n\n On the microcontroller side we\u2019re done. Let\u2019s finish the PC side.<\/p>\n\n\n\n Here, similarly to STM32 you need to initialize Semihosting.<\/strong> This is done at the moment debugging starts<\/strong>, i.e. when launching the OpenOCD session. You need to give it a command so it knows that we\u2019re semihosting.<\/p>\n\n\n\n You need to go back into the debug session settings<\/strong> of your project. This time, what we\u2019re interested in is in the Startup tab. There is a field \u201cInitialization Commands\u201d.<\/strong> These commands will be executed when bringing up the debug session.<\/p>\n\n\n\n Enter here:<\/strong><\/p>\n\n\n\n You now have everything you need to use Semihosting!<\/p>\n\n\n\n We\u2019re done with the configuration, so how do we use this mechanism?<\/p>\n\n\n\n If you don\u2019t have it, you must include the <stdio.h> file in your project.<\/strong><\/p>\n\n\n\n If you did everything the way I described, then now you simply use the printf function<\/strong><\/em>. <\/p>\n\n\n\n There is only one important rule. Every message sent via Semihosting must end with the \u2018\\n\u2019 character.<\/strong><\/p>\n\n\n\n Just as if you were printing to the console on a PC, now you print from the microcontroller. Where will these strings go? To the console from which OpenOCD was launched. If you did it in STM32CubeIDE, it\u2019s the console at the bottom.<\/p>\n\n\n\n Example:<\/p>\n\n\n\n As you can see, I inserted the Semihosting code right after entering main and immediately want to print something. What will be the effect?<\/p>\n\n\n\n It works. My test string appeared in the console.<\/p>\n\n\n\n Note that among the red messages from OpenOCD we got \u201csemihosting is enabled\u201d<\/strong><\/em>. That means everything is fine.<\/p>\n\n\n\n I also said we can use our PC keyboard, right?<\/strong><\/p>\n\n\n\n The scanf(\u2026) function reads standard input, i.e. what we type into the console. It is a blocking function and waits for Enter from the keyboard.<\/p>\n\n\n\n By adding these lines to the program:<\/p>\n\n\n\n We get a program flow that requires user interaction. The program stops and waits for you to provide it with an integer in the console. Don\u2019t forget Enter! The text we type from the keyboard has a greenish-turquoise color.<\/strong><\/p>\n\n\n\n Using this approach we can not only use the console, but also files on our computer!<\/strong><\/p>\n\n\n\n The following functions are used for this:<\/p>\n\n\n\n There are more functions in stdio.h, but these are the most important.<\/p>\n\n\n\n You can provide the file path relatively\u2014then it refers to the location from which the program is run.<\/p>\n\n\n\n You can also provide it as an absolute path. You use paths from your computer. Just don\u2019t point to drive C<\/strong>, because you\u2019ll run into administrator permissions and the MCU will end up in Hard Fault<\/strong> \ud83d\ude42<\/p>\n\n\n\n Example:<\/p>\n\n\n\n The program is supposed to open a file (create it if it doesn\u2019t exist), write text, and close it. Always remember to close files after using them!<\/strong><\/p>\n\n\n\n Running such a program with the path I provided, I got a new file \ud83d\ude42<\/p>\n\n\n\n Inside, of course, was what I wrote in the microcontroller program.<\/p>\n\n\n\n I see potential here in the \u201cother direction\u201d, i.e. from a file on the PC to the microcontroller.<\/strong><\/p>\n\n\n\n You can write some algorithm on the microcontroller, and inject test data from a file on the computer! This can have huge applications.<\/p>\n\n\n\n Semihosting is a very interesting alternative to debugging via printing.<\/strong> It allows us to replace UART.<\/strong> It makes it much easier to implement things like connecting a keyboard or pulling data from a file on the computer.<\/p>\n\n\n\n I didn\u2019t mention anything about the downsides<\/strong>, and I think it has one important one.<\/strong> This solution is very slow.<\/strong> Try running printing in a loop without any delay and you\u2019ll see that there isn\u2019t such a storm of characters as, for example, with UART.<\/p>\n\n\n\n For this reason Semihosting won\u2019t be suitable where high log throughput speed is required.<\/strong> However, these will be specific use cases. There\u2019s no need to demonize this speed.<\/strong> For learning or a simple project, it may turn out that this speed is sufficient.<\/p>\n\n\n\n You can also introduce a logging level and, for example, send only more important messages or only those you currently need.<\/p>\n\n\n\n Among the advantages, I would definitely mention the minimal number of pins needed for operation.<\/strong> You could say it\u2019s zero, because you always have the debugger connected anyway.<\/p>\n\n\n\n As early as February 16 the best STM32 programming course for Beginners returns!<\/strong> This is already the fourth edition! (the course content is in Polish)<\/p>\n\n\n\n It\u2019s a complete A-to-Z program<\/strong> in which you will learn STM32 microcontroller programming. You will get to know its interfaces and you will be able to use them correctly and in a non-blocking way.<\/strong><\/p>\n\n\n\n Don\u2019t miss the chance! The next edition will probably be only in the second half of 2022.<\/p>\n\n\n\n So far, over 470 people have taken part in the course!<\/strong><\/p>\n\n\n\nRequired microcontroller pins<\/h2>\n\n\n\n
Test platform<\/h2>\n\n\n\n
![\"\"](\"https:\/\/msalamon.pl\/wp-content\/uploads\/2021\/12\/STM32U5-baner-1024x341.png\")
<\/a><\/figure>\n\n\n\nConfiguring Semihosting on STM32<\/h2>\n\n\n\n
1. The right software debugger<\/h4>\n\n\n\n
![\"\"](\"https:\/\/msalamon.pl\/wp-content\/uploads\/2022\/01\/semihosting_debug_config.jpg\")
<\/a><\/figure>\n\n\n\n![\"\"](\"https:\/\/msalamon.pl\/wp-content\/uploads\/2022\/01\/semihosting_openocd-1024x593.jpg\")
<\/a><\/figure>\n\n\n\n2. Enabling an external library via the linker<\/h4>\n\n\n\n
-l rdimon --specs=rdimon.specs<\/pre>\n\n\n\n
![\"\"](\"https:\/\/msalamon.pl\/wp-content\/uploads\/2022\/01\/semihosting_linker_lib-1024x532.jpg\")
<\/a><\/figure>\n\n\n\n-specs=rdimon.specs<\/pre>\n\n\n\n
![\"\"](\"https:\/\/msalamon.pl\/wp-content\/uploads\/2022\/01\/semihosting_linker_misc-1024x532.jpg\")
<\/a><\/figure>\n\n\n\n3. Excluding syscalls.c from compilation<\/h4>\n\n\n\n
![\"\"](\"https:\/\/msalamon.pl\/wp-content\/uploads\/2022\/01\/semihosting_syscall_exclude..jpg\")
<\/a><\/figure>\n\n\n\n4. Initialization in the microcontroller program<\/h4>\n\n\n\n
initialise_monitor_handles();<\/pre>\n\n\n\n
extern void initialise_monitor_handles(void);<\/pre>\n\n\n\n
5. Enabling semihosting when starting debugging<\/h4>\n\n\n\n
monitor arm semihosting enable<\/pre>\n\n\n\n
How to use Semihosting?<\/h2>\n\n\n\n
int main(void)\n{\n \/* USER CODE BEGIN 1 *\/\n\tinitialise_monitor_handles();\n\n\tprintf(\"Semihosting test\\n\");\n \/* USER CODE END 1 *\/<\/pre>\n\n\n\n![\"\"](\"https:\/\/msalamon.pl\/wp-content\/uploads\/2022\/01\/semihosting_printf.jpg\")
<\/a><\/figure>\n\n\n\nint main(void)\n{\n \/* USER CODE BEGIN 1 *\/\n\tint32_t Value;\n\n\tinitialise_monitor_handles();\n\n\tprintf(\"Semihosting test\\n\");\n\n\tprintf(\"Type a integer: \\n\");\n\tscanf(\"%ld\", &Value);\n\tprintf(\"You typed %ld\\n\", Value);\n\n \/* USER CODE END 1 *\/<\/pre>\n\n\n\n![\"\"](\"https:\/\/msalamon.pl\/wp-content\/uploads\/2022\/01\/semihosting_scanf.jpg\")
<\/figure>\n\n\n\nFile operations<\/h2>\n\n\n\n
\n
int main(void)\n{\n \/* USER CODE BEGIN 1 *\/\n\tFILE *FilePtr;\n\n\tinitialise_monitor_handles();\n\n\tFilePtr = fopen(\"d:\\\\semi\\\\test.txt\", \"w\");\n\n\tfprintf(FilePtr, \"Test semihosting\");\n\n\tfclose(FilePtr);\n \/* USER CODE END 1 *\/<\/pre>\n\n\n\n![\"\"](\"https:\/\/msalamon.pl\/wp-content\/uploads\/2022\/01\/semihosting_file..jpg\")
<\/figure>\n\n\n\n![\"\"](\"https:\/\/msalamon.pl\/wp-content\/uploads\/2022\/01\/semihosting_file_inside.jpg\")
<\/figure>\n\n\n\nSummary<\/h2>\n\n\n\n
STM32 Course for Beginners<\/h2>\n\n\n\n
Sign up for the waiting list at https:\/\/kursstm32.pl\/<\/a> (the content is in Polish)<\/h2>\n\n\n\n
![\"\"](\"https:\/\/msalamon.pl\/wp-content\/uploads\/2021\/02\/Kurs-STM32-roz.jpg\")
<\/a><\/figure>\n\n\n