| |||||||
|
FreeRTOS+Trace and FreeRTOS+CLI Demo
|
| Command String | Command Behaviour |
| trace |
The trace command is used to start and stop the trace recording.
FreeRTOS+CLI will only process the command if it is entered
with exactly one parameter.
To start a FreeRTOS+Trace recording enter: "trace start" To stop a FreeRTOS+Trace recording enter: "trace stop" Stopping a trace results in the trace buffer being automatically saved to the hard disk of the host computer. Instructions on viewing the trace are provided further down this page. |
| echo_parameters |
This demonstrates how to create and implement a command that
accepts a variable number of parameters. FreeRTOS+CLI will
not check the number of supplied parameters, and the
implementation of the command simply echos parameter back,
one at a time. For example, if the user enters:
"echo_parameters one two three four" Then the generated out will be:
The parameters were: |
| echo_3_parameters | This demonstrates how to create a command that takes an exact number of parameters. The command will not be accepted by FreeRTOS+CLI unless exactly three parameters are supplied. When the command is accepted, the implementation of the command echos all three parameters in a similar manner to the echo_parameters command detailed above. |
| task-stats | Displays a table, each row of which shows state information on a single task. Note that the displayed task stack high water mark will not show a valid value when the Windows simulator is being used. |
| run-time-stats | Displays a table, each row of which shows the amount of time a single task has spent in the running state. That is, how much execution time has been allocated to each task. Both absolute and relative values are displayed, although the absolute times have no units when using the Windows simulator. |
Demo Functionality
Two tasks and a single queue are used to generate a simple execution pattern that can be viewed in the FreeRTOS+Trace graphical interface.A low priority queue send task repeatedly sends a message to the queue. A higher priority queue receive task repeatedly attempts to read a message from the queue, blocking on the queue read operation when no messages are available. An explanation of the resultant execution pattern is provided below.
A trace monitoring task is also created that prints out a message when it determines that the status of the trace recorder has changed since it last executed.
It should be noted that, because the Windows simulator is being used, the timing information displayed while the application is running, and recorded in the trace log, have no meaningful units.
Building and executing the demo
-
Ensure Microsoft Visual C++ is installed.
The free Express version
can be used.
-
The Visual C++ solution file is called FreeRTOS_Plus_CLI_with_Trace.sln, and is
located in the \FreeRTOS-Plus\Demo_Projects_Using_FreeRTOS_Simulator\FreeRTOS_Plus_CLI_with_Trace
directory of the download. Double click the file to open Visual C++, or alternatively
open the file from within the Visual C++ IDE.
Within the solution explorer:
The RTOS project viewed in the Visual C++ IDE- The source files that implement the demo application are listed in the Demo App Source folder.
- The source files that implement the FreeRTOS+CLI functionality are listed in the FreeRTOS+/FreeRTOS+CLI folder.
- The source files that implement the FreeRTOS+Trace recorder functionality are listed in the FreeRTOS+/FreeRTOS+Trace folder.
- The source files that implement the RTOS functionality are listed in the FreeRTOS folder.
- Build then execute the project. (F7 will build the project, and F5 will execute the project).
Accessing the Command Console
The command console uses a UDP socket on IP address 127.0.0.1 and port 5001 to receive command line input, and a UDP socket on the same IP address and port 5002 for output. A UDP console program, such as the free YAT utility, can be used as a UDP interface. Note that 127.0.0.1 is the loopback IP address, so a live network connection is not required.
The required YAT terminal settings
Creating a FreeRTOS+Trace Recording
To create a trace recording:-
Test the UDP connection between the UDP terminal and the running
application by trying the "task-stats" and "run-time-stats"
commands.
- Start the trace recorder by entering the "trace start" command in the UDP terminal. Leave the recording running for approximately five to ten seconds, then end the recording by entering the "trace end" command.
Screen capture after the RTOS trace has been started and stopped from the UDP console
Viewing the Trace Recording in FreeRTOS+Trace
To open and view the trace recording:-
Download FreeRTOS+Trace
from the Percepio web site if you do not already have it installed.
-
Open the trace file from within the FreeRTOS+Trace application.
The trace file will have been saved as
FreeRTOSPlusTrace.dump in the directory that contains
the Visual Studio project.
- The trace data will be displayed in the main FreeRTOS plus trace window. Scroll the trace display down until you notice "Tx" and "Rx" markers on the left side of the screen. These are the times during which the queue send and queue receive tasks were executing respectively. Zooming in on that region will result in a display similar to the screen shot below. Note that the screen shot has all the visibility filters ticked, not all of which are available in the free FreeRTOS+Trace edition.
Viewing the recorded RTOS trace in FreeRTOS+Trace with explanatory annotation
The image above has been annotated with some green numbers to highlight points of interest. Referring to the image above:
-
At (1) the CLI task is running. In a real scenario, on real
hardware, the CLI task need only execute when there is input
to process. In this simulated environment, the TCP/IP stack cannot
be allowed to block, so the CLI task is always available to the
scheduler.
-
At (2) the Tx task (the queue send task) unblocks because it is
time for it to send another message to the queue. The Tx task
pre-empts the CLI task.
-
At (3) the Tx task calls xQueueSend() to send a message to the
queue named DemoQ. The higher priority Rx task (the queue receive task) was blocked
on the queue, waiting for a message to arrive, so now unblocks and
pre-empts the Tx task.
-
At (4) the Rx task calls xQueueReceive() again, but the queue is
once more empty so the Rx task re-enters the Blocked state (signified by the
red colour of the xQueueReceive() label in the trace view) allowing
the Tx task to enter the Running state again.
-
At (5) the Tx task calls vTaskDelayUntil() to enter the Blocked
state until once again it is time for it to send a message to
the queue.
-
At (6) the idle task is running.
Going Further
This simple example has only demonstrated the basic functionality. The FreeRTOS+Trace download contains a much more comprehensive FreeRTOS Windows simulator project, along with pre-recorded example trace log files. Visit the Percepio Website for more information.