Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/freertos/freertos-gdb

Last synced: about 2 months ago
JSON representation

Host: GitHub
URL: https://github.com/freertos/freertos-gdb
Owner: FreeRTOS
License: mit
Created: 2022-09-30T18:46:27.000Z (about 2 years ago)
Default Branch: main
Last Pushed: 2022-11-21T18:55:34.000Z (about 2 years ago)
Last Synced: 2023-07-13T01:32:21.489Z (over 1 year ago)
Language: Python
Size: 18.6 KB
Stars: 0
Watchers: 8
Forks: 0
Open Issues: 0
Metadata Files:
- Readme: README.md
- License: LICENSE

Awesome Lists containing this project

README

# freertos-gdb
GDB extension to display FreeRTOS tasks and set task-specific breakpoints.

## Prerequisites
GDB must be built with Python 2+.

## Setup
1. In gdb, use the command ```show data-directory``` to find the path to where GDB searches for auxillary data files. We'll call this ```[data-directory]```.
2. Copy ```freertos.py``` from this repository into the folder ```[data-directory]/python/gdb/command/```.

## Commands
```freertos``` can be used to display supported subcommands.
```
(gdb) freertos
"freertos" must be followed by the name of a subcommand.
List of freertos subcommands:

freertos break -- Create a breakpoint that will only get tripped by the specific task.
freertos tasks -- Displays FreeRTOS tasks and information.
```

### Tasks Display
```freertos tasks``` reads through FreeRTOS task lists and displays information from the TCB of each task. The default data shown are:
* ID: The memory address of the task's TCB_t
* STATE: One of the following task statuses:
* 'B' - Blocked
* 'R' - Ready
* 'D' - Deleted (waiting clean up)
* 'S' - Suspended, or Blocked without a timeout
* CPU: The core a currently running task is running on.
* NAME: The descriptive string name assigned to the task on creation.
* STACK: The starting address of the task's stack.
* PRIORITY: The priority of the task. 0 is the lowest priority.
* STACK_END: The highest valid address for the stack. Only shown if ```configRECORD_STACK_HIGH_ADDRESS``` is enabled.
* CRITICAL_NESTING: The critical section nesting depth for ports that do not maintain their own count in the port layer. Only shown if ```portCRITICAL_NESTING_IN_TCB``` is enabled.
* TCB_NUM: The number of TCBs that have been created before and including this one. It allows debuggers to determine when a task has been deleted and then recreated. Only shown if ```configUSE_TRACE_FACILITY``` is enabled.
* MUTEXES: The number of FreeRTOS mutexes held by the task. Only shown if ```configUSE_MUTEXES``` is enabled.
* RUN_TIME: The amount of time the task has spent in the Running state. Only shown if ```configGENERATE_RUN_TIME_STATS``` is enabled.
```
(gdb) freertos tasks
ID STATE CPU NAME STACK MUTEXES PRIORITY
---------------------------- ------- ----- ------- ---------- --------- ----------
0x2000f5bc R 0 IDLE 0x2000f618 0 0
0x20000758 B TX 0x20000608 0 1
0x2000f758 B Tmr Svc 0x2000f7b4 0 5
0x200005a0 S Rx 0x20000450 0 2
```

### Breakpoints
```freertos break [task_name] [target_location]``` sets a special breakpoint at ```[target_location]``` that will only get stopped if ```[task_name]``` is the currently running task. The breakpoint can then be interacted with using GDB's builtin breakpoint commands for actions such as deleting, enable/disabling, etc.

```[task_name]``` should be the descriptive string name of the task, equivalent to the TCB's ```pcTaskName```.

```[target_location``` should be a location in a format recognized by the GDB's builtin break command.

This command may have undefined behavior in multiprocess environments.
```
(gdb) freertos break Rx xQueueReceive
Breakpoint 1 at 0x1bf8: file ./../../../..//Source/queue.c, line 1382.
```

## References
[Espressif's FreeRTOS GDB Extension](https://github.com/espressif/freertos-gdb)