 FreeR2S advanced topics. Interesting components of FreeR2S are hooks. Hooks are the callback functions supported by FreeR2S Core, which could help us to detect and handle some faulty situations within runtime of our system. Each hook function should meet the following requirements. It should be as short as possible. It cannot be blocking, so no delays, no wait functions are allowed there. Additionally, hooks are disabled by default and should be enabled within FreeR2S config.h file in case of usage. There are four types of the hooks specified in current implementation of the FreeR2S. Idle hook called with an idle task code at the end of its execution. Tick hook called within sys-tick tick function. Malloc failed hook called in case of memory allocation issues. Stack overflow hook called in case of issues with a stack of the operating system. We will describe them one by one later on. Hook functions are defined within FreeR2S.c file with weak attribute, so we can override them within our code without any risk of error warning during completion phase. In case we would like to put our code within FreeR2S.c file, we need to include the proper header file for hardware abstraction layer library in case we would like to use an HIL functions. So as an example for STM32L4, we need to include STM32L4XX underscore HIL.h file. Let's discuss hooks one by one. We'll start with idle task hook. To use it, we need to define config use idle hook within FreeR2S config.h file. Just a reminder, idle task is automatically created by scheduler within OS kernel start function. It has the lowest possible priority. It runs if there is no other task in ready state. It can share the same priority with other tasks. With an idle task function body at the end of it, there is a call to V application idle hook. In case a config use idle hook is defined. Prototype of this function is strictly defined, so there is no arguments, no return value. This function must be as short as possible as we discussed. It should not block, should not wait for anything. So it cannot contain any endless loop-like tasks what we can see on this picture. In case we are using stm32cubemix or stm32cubidecode generators and we enabled hook functionality, an empty week function will be created within FreeR2S.c file. It contains a description as well with all of the rules concerning function role and structure and its usage. Where we may need idle task hook? Usually it is used during development phase to check whether idle task is ever executed and if yes, estimate how often versus the other tasks. Then it is usually not used in a final application, so this is only for the development. Just a short reminder concerning idle task code. Idle task code is stored in port task function within task.c file. Important message at this point is that even we will enable idle hook, it may happen that it will be not executed if other conditions checked before within this handler will be met. Those are any other tasks with higher priority will be in ready state. We will enable the automatic move of the idle task to ready state by calling task yield in case we are working in cooperative mode of the operating system. Automatic move to ready state if another task on the same priority will pop up. So once we enable config idle should yield definition. So under those conditions, it might happen that our idle hook will be not called because the idle task will be preempted before we reach this point within port task function body. How to enable idle hook? We need to define it within free RTS config.h file. If we are using STM32QBemix or STM32QB IDE code generators, please go to free RTS section and within config parameters tab, please select enabled next to use idle hook. This will perform free RTS config.h file modification during code generation. After enabling idle hook, STM32QBemix or STM32QB IDE code generators were included within free RTS.c file and empty v application idle hook function which is called within task idle code. Please have a look at task.c file port task function for more details. This generated empty function has weak attribute what means that we can define the same function in our source files without any warning error message during build process. Another type of the hook is a tick hook. It can be enabled by defining config use tick hook within free RTS config.h file. Once enabled, it will be called every time the sys tick interact is triggered. It is possible to use tick hook for periodic events like watchdog refresh, but please be careful with this as the priority of the sys tick is the lowest possible in the system and it may happen that operating system can be thrown in for some time and the work that will be not refreshed on time. Once tick hook is enabled within free RTS config.h file, its empty callback will be created in free RTS.c file by STM32QBemix or STM32QB IDE generators. This hook is called within X task increment tick from task.c module. Hook callback should not contain any blocking functions nor endless loop. In case you are using free RTS API, please use only the interrupt safe functions with suffix from ISR. In case of CMCsoS, selection of proper free RTS API functions is done automatically. Next hook we will discuss is malloc failed hook. It can be used to monitor memory allocation requests as once enabled, it will be called all the time once PVport malloc allocation function will return null instead of pointer to allocated structure. To enable this hook, it is necessary to enable config use malloc failed hook within free RTS config.h file. Then upon STM32QBemix or STM32QB IDE code generation, there is an function vapplication malloc failed hook within free RTS.c file which can be implemented by the user. Malloc failed hook should follow the same rules like other hooks. So there should be no any blocking functions inside. There should be no endless loop within callback function body. As it is generated within free RTS.c file as a weak function, it can be overwritten within our code without any warning nor error generation during the build process. Here you can see an example of implementation and test of malloc failed hook. Within its callback implemented in main.c file, there is only task underscore action call. Then within start task one function body, this is main.c file as well. There is a trial of extra memory allocation by OS pull create function call which should be taken from available hip space dedicated to operating system. As the size is much bigger than maximum space of this area, a malloc failed hook will be called as a result of its execution. Before we will switch to next hook, let's focus for a while on stack overflow protection mechanism which are available within free RTS just for introduction. During test creation, its stack memory space is filled with A5 hexadecimal data. During runtime, we can check how much stack is used by task by monitoring its high watermark. To turn on this mechanism, some additional configuration of free RTS is acquired. It is done with a free RTS config.h file or stm32cubemix or stm32cubede free RTS configuration window. Those settings are config use trace facility which should be defined to one and include UX task get stack high watermark which should be set to one as well. There is a dedicated function to perform this operation once we enable everything. It is UX task get stack high watermark with one argument to the task we would like to monitor. After a call of this function with a task handle as an argument, it returns the minimum amount of remaining stack for a given task which has been not ever used by the task. It is possible as well to turn on a dedicated hook to monitor issues with a stack overflow as well. Free RTS is able to detect operating system stack overflows events. There are two options available here. It is configurable within free RTS config.h file or within config parameters at the check for stack overflow field. Stack overflow detection option one. Stack can reach its deepest value after kernel is moving it from run to ready or blocked state. At this point kernel can check whether stack pointer remains within valid stack space. In case it is outside of the valid stack range a stack overflow hook function is called. This method is quick but it cannot guarantee catching of all stack overflows. To use this option only we need to set config check for stack overflow to one within free RTS config.h file or select option one within check for stack overflow option when using stm32 cube mix or stm32 cube IDE configurators. Stack overflow detection option two. When task is created it's stack is filled with a known value it is a five hexadecimal. When moving the task from run mode kernel can check last 20 bytes with an valid stack range to ensure that these known values has not been overwritten. Stack overflow hook function is called if any of those 20 bytes do not remain at their initial value. This method is less efficient than method one so option one but still fast. It is very likely to catch stack overflows but it is still not guaranteed to catch all of them. To use this method with combination with option one please set config check for stack overflow to two within free RTS config.h file or select option two within check for stack overflow option when using stm32 cube mix or stm32 cube IDE configurators. Like with other hooks once enabled within free RTS config.h file or free RTS config parameters tab within stm32 cube mix or stm32 cube IDE. During code generation an empty function definition will be created within free RTS.c file. It needs to follow the same rules like other hooks concerning function structure so no endless loop node blocking functions. The name of this hook is V application stack overflow hook. A part of hooks it is worth to mention that free RTS has built in mechanism to monitor state of the operating system by collecting runtime statistics. To collect those statistics we need to use a dedicated function or a straight list and this function is calling V task list within free RTS API which is collecting information about all of the tasks and put them into the table. The function triggering and the data formatting should be implemented by the user. To run this function it is needed to set two definitions now within free RTS config.h file by defining its values to one. The first one is config use trace facility and the second one is config use stats formatting functions. The second option is not always present within free RTS config.h file. This is why it could be possible that you should edit manually into this file. Another option is to use either stm32 cube mix or stm32 cube IDE configuration windows for free RTS to add those two components. Thank you for watching this video.