Skip to content

Commit c8ae4f2

Browse files
cmanconcmancon
committed
First iteration on the Shared demo Readme
1 parent 4af13ed commit c8ae4f2

1 file changed

Lines changed: 139 additions & 0 deletions

File tree

  • demo/cross/shared/build/arm-cortex/freertos/ciaa-nxp

‎demo/cross/shared/build/arm-cortex/freertos/ciaa-nxp/README_en.md‎

Lines changed: 139 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,139 @@
1+
# *Shared* example
2+
3+
## Description:
4+
5+
This application deals with the shared resource problem in active object systems. Showing one of the biggest benefit of using active objects: resource encapsulation.
6+
7+
The encapsulation naturally designates the owner of the resource as the ultimate arbiter in resolving any contention and potential conflicts for the resource.
8+
9+
The *Shared* application is relatively simple and can be tested only with a couple of LEDs on your target board.
10+
11+
Still, *Shared* contains five (5) concurrent active objects that exchange events via direct event posting mechanism.
12+
13+
The application uses four timers, as well as dynamic and static events.
14+
On the other hand, this application could be used in either preemptive or cooperative environment.
15+
16+
Additionally, the *Shared* could be used to verify a new RKH port.
17+
18+
19+
## *BSP*
20+
21+
As it was said before, this application is the current *"Gold Standard"* to test the proper working of a newly developed port. For this reason, this example (or *demo*) can be compiled for multiple platforms. In this case, it's to validate the FreeRTOS port but many others can be found in the RKH/demo tree.
22+
23+
Even though this port can run in multiple hardware targets depending in FreeRTOS's compatibility, in this particular case it is used the NXP LPC4337 based CIAA board (in either educational or full version) for convenience.
24+
25+
## IDE & Compiling
26+
27+
This project was developed and tested on [MCUXpresso](https://www.nxp.com/design/software/development-software/mcuxpresso-software-and-tools-/mcuxpresso-integrated-development-environment-ide:MCUXpresso-IDE) in order to simplify the process with all the embedded tools it contains. As it's an *Eclipse IDE* after all, you can use it too provided that you make the necessary changes regarding the *toolchain* used to compile the code.
28+
29+
### Import the project
30+
31+
Just go to `File->Import` and select the `Import Projects from File System or Archive` option. Point to the `mcuxpresso` directory located where this README is located and proceed to import the project listed.
32+
33+
### Platform specific parameters
34+
35+
To differ the compiling process to one of the mentioned platforms, an environment variable is used. This variable is `BOARD`, selected for compatibility with some board-specific code.
36+
37+
To select the platform, there is no need to change the variable's value. Just **select the build configuration desired** in `Project->Build Configurations->Set Active`.
38+
39+
### RKH related memory usage
40+
41+
Next we can see a table depicting the memory usage by RKH modules for this demo including the *trace* capability. All values shown are in bytes.
42+
43+
| Module | .bss | .text | .data | .rodata |
44+
|----------------|-----:|------:|------:|--------:|
45+
| rkhfwk_bittbl | 0 | 44 | 0 | 8 |
46+
| rkhfwk_dynevt | 36 | 860 | 0 | 16 |
47+
| rkhfwk_evtpool | 80 | 344 | 0 | 16 |
48+
| rkhfwk_pubsub | 0 | 0 | 0 | 0 |
49+
| rkhfwk_rdygrp | 0 | 0 | 0 | 0 |
50+
| rkhfwk_sched | 0 | 0 | 0 | 0 |
51+
| rkhfwk_version | 0 | 0 | 0 | 8 |
52+
| rkhmempool | 0 | 760 | 0 | 12 |
53+
| rkhqueue | 12 | 776 | 0 | 12 |
54+
| rkhsm | 0 | 3016 | 0 | 16 |
55+
| rkhsma | 32 | 672 | 0 | 8 |
56+
| rkhsma_prio | 0 | 0 | 0 | 0 |
57+
| rkhsma_sync | 0 | 0 | 0 | 0 |
58+
| rkhtmr | 4 | 976 | 0 | 8 |
59+
| rkhtrc_filter | 26 | 784 | 0 | 48 |
60+
| rkhtrc_record | 2 | 812 | 0 | 0 |
61+
| rkhtrc_stream | 528 | 336 | 0 | 0 |
62+
63+
Next the same analysis without *trace*.
64+
65+
| Module | .bss | .text | .data | .rodata |
66+
|----------------|-----:|------:|------:|--------:|
67+
| rkhfwk_bittbl | 0 | 0 | 0 | 0 |
68+
| rkhfwk_dynevt | 36 | 456 | 0 | 16 |
69+
| rkhfwk_evtpool | 80 | 216 | 0 | 16 |
70+
| rkhfwk_pubsub | 0 | 0 | 0 | 0 |
71+
| rkhfwk_rdygrp | 0 | 0 | 0 | 0 |
72+
| rkhfwk_sched | 0 | 0 | 0 | 0 |
73+
| rkhfwk_version | 0 | 0 | 0 | 8 |
74+
| rkhmempool | 0 | 576 | 0 | 12 |
75+
| rkhqueue | 12 | 508 | 0 | 12 |
76+
| rkhsm | 0 | 1200 | 0 | 16 |
77+
| rkhsma | 32 | 472 | 0 | 8 |
78+
| rkhsma_prio | 0 | 0 | 0 | 0 |
79+
| rkhsma_sync | 0 | 0 | 0 | 0 |
80+
| rkhtmr | 4 | 684 | 0 | 8 |
81+
| rkhtrc_filter | 0 | 0 | 0 | 0 |
82+
| rkhtrc_record | 0 | 0 | 0 | 0 |
83+
| rkhtrc_stream | 0 | 0 | 0 | 0 |
84+
85+
You can see the small footprint added by the framework.
86+
87+
## Running/Debugging the application
88+
89+
90+
### Interface
91+
To debug the application, it is used the board included programming/debugging interface. It's based on the FTDI FT2232H, the rather well known IC that exposes a JTAG interface and a UART through USB.
92+
93+
The JTAG is managed by OpenOCD and for this, the corresponding script is provided.
94+
95+
### Starting the session in the IDE
96+
Included in the project there are two launchers (and one more as a legacy/backup) that will initiate the tools embedded in MCUXpresso (Check the [documentation](https://www.nxp.com/docs/en/quick-reference-guide/MCUXpresso_IDE_FreeRTOS_Debug_Guide.pdf) about this subject). One for each platform previously said.
97+
98+
The only difference between each launcher is an argument passed to the OpenOCD program to deal with the specific target.
99+
100+
The launchers will start an instance of OpenOCD and GDB. They will also inform to the OpenOCD that it has to be aware of the presence of FreeRTOS so we can get the full benefits of this tool. To see more details of this, please go to [OpenOCD's documentation](http://openocd.org/doc/html/GDB-and-OpenOCD.html#RTOS-Support).
101+
102+
As we configure the OpenOCD in this way, it will inform to the GDB the "presence" of the rtos threads and they will be listed independently during the debug session. But it has a drawback: it will fetch a structure that informs about the threads and if it's not created already it will crash. To prevent this, the temporary breakpoint normally set on main is removed. **If it's not removed the debug session will fail at start**. In the launchers this temporary breakpoint was moved to `vTaskStartScheduler` as it is a safe location to infer that the according structure is already created and populated.
103+
104+
In case that you need to debug the initialization or task creation process, we recommend to tailor the third debug launcher to your needs as it will not configure the OpenOCD to be RTOS-aware. This will not try to list the threads and a breakpoint can be placed on the main to debug this section of the application. Be aware that a temporary breakpoint can persist even if you change the debug configuration.
105+
106+
### Interfacing with the app and the RKH framework
107+
108+
The app will have a "console output" using semihosting through the JTAG interface. It will show the banner or "splash" information of the demo and the messages generated to inform the client-server interaction.
109+
110+
Also, if the trace capability is enabled, the according output is channelized through the UART to the COM/TTY interface. In this case you can run [Trazer](https://github.com/vortexmakes/Trazer) to interpret it.
111+
112+
In case that you are using Linux, you can launch it with:
113+
```sh
114+
./trazer -c /dev/ttyUSB1 19200 8N1
115+
```
116+
117+
This tool will allow you to store the trace in a file using the `-o` argument and you can analyse it later on in a tool like [Trace Compass](https://github.com/vortexmakes/TrazerTC).
118+
119+
### Demo workings
120+
121+
You will notice that this demo is using FreeRTOS to encapsulate each *Active Object* in a independent thread. To communicate between them, the artifacts of FreeRTOS (e.g. queues, etc) are used.
122+
123+
This is **not** the only way you can integrate RKH and FreeRTOS in a project. For example, you can dedicate a single thread to the framework and use RKH's scheduler an IPCs. This will be left to the reader to explore.
124+
125+
### Demo hardware interaction
126+
127+
As this example can be compiled either for CIAA-NXP or EDU-CIAA-NXP platforms, the means to interact with the app running differ:
128+
129+
Each Client has its own LED to show when the server is running its request. The assignment is according to the next table.
130+
131+
| Platform | Client 1 | Client 2 | Client 3 | Client 4 |
132+
|:------------:|:--------:|:--------:|:--------:|:--------:|
133+
| CIAA-NXP | DOUT4 | DOUT5 | DOUT6 | DOUT7 |
134+
| EDU-CIAA-NXP | LEDB | LED1 | LED2 | LED3 |
135+
136+
To pause the server, one has to drive the `DIN0` input or press the `TEC1` button depending if you are using the CIAA-NXP or EDU-CIAA-NXP respectively. This will generate a pause `event`.
137+
When the server is paused, this situation will be indicated lighting **all** the Client's LEDs at the same time.
138+
139+
To resume from the pause, just press or activate again the previous input.

0 commit comments

Comments
 (0)