{"id":19775056,"url":"https://github.com/freertos/freertos-gdb","last_synced_at":"2025-08-24T19:41:01.046Z","repository":{"id":180825442,"uuid":"543743766","full_name":"FreeRTOS/freertos-gdb","owner":"FreeRTOS","description":null,"archived":false,"fork":false,"pushed_at":"2022-11-21T18:55:34.000Z","size":19,"stargazers_count":9,"open_issues_count":0,"forks_count":4,"subscribers_count":11,"default_branch":"main","last_synced_at":"2025-05-13T00:48:05.094Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/FreeRTOS.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2022-09-30T18:46:27.000Z","updated_at":"2025-05-06T03:54:21.000Z","dependencies_parsed_at":"2023-07-13T01:42:36.384Z","dependency_job_id":null,"html_url":"https://github.com/FreeRTOS/freertos-gdb","commit_stats":null,"previous_names":["freertos/freertos-gdb"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FreeRTOS%2Ffreertos-gdb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FreeRTOS%2Ffreertos-gdb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FreeRTOS%2Ffreertos-gdb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FreeRTOS%2Ffreertos-gdb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/FreeRTOS","download_url":"https://codeload.github.com/FreeRTOS/freertos-gdb/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253850882,"owners_count":21973672,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-12T05:14:46.014Z","updated_at":"2025-05-13T00:48:11.008Z","avatar_url":"https://github.com/FreeRTOS.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# freertos-gdb\nGDB extension to display FreeRTOS tasks and set task-specific breakpoints.\n\n## Prerequisites\nGDB must be built with Python 2+.\n\n## Setup\n1. 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]```.\n2. Copy ```freertos.py``` from this repository into the folder ```[data-directory]/python/gdb/command/```.\n\n## Commands\n```freertos``` can be used to display supported subcommands.\n```\n(gdb) freertos\n\"freertos\" must be followed by the name of a subcommand.\nList of freertos subcommands:\n\nfreertos break -- Create a breakpoint that will only get tripped by the specific task.\nfreertos tasks -- Displays FreeRTOS tasks and information.\n```\n\n### Tasks Display\n```freertos tasks``` reads through FreeRTOS task lists and displays information from the TCB of each task. The default data shown are:\n* ID: The memory address of the task's TCB_t\n* STATE: One of the following task statuses:\n  * 'B' - Blocked\n  * 'R' - Ready\n  * 'D' - Deleted (waiting clean up)\n  * 'S' - Suspended, or Blocked without a timeout\n* CPU: The core a currently running task is running on.\n* NAME: The descriptive string name assigned to the task on creation.\n* STACK: The starting address of the task's stack.\n* PRIORITY: The priority of the task. 0 is the lowest priority.\n* STACK_END: The highest valid address for the stack. Only shown if ```configRECORD_STACK_HIGH_ADDRESS``` is enabled.\n* 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.\n* 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.\n* MUTEXES: The number of FreeRTOS mutexes held by the task. Only shown if ```configUSE_MUTEXES``` is enabled.\n* RUN_TIME: The amount of time the task has spent in the Running state. Only shown if ```configGENERATE_RUN_TIME_STATS``` is enabled.\n```\n(gdb) freertos tasks \nID                            STATE    CPU    NAME     STACK         MUTEXES    PRIORITY\n----------------------------  -------  -----  -------  ----------  ---------  ----------\n0x2000f5bc \u003cxIdleTaskTCB.3\u003e   R        0      IDLE     0x2000f618          0           0\n0x20000758 \u003cucHeap+884\u003e       B               TX       0x20000608          0           1\n0x2000f758 \u003cxTimerTaskTCB.1\u003e  B               Tmr Svc  0x2000f7b4          0           5\n0x200005a0 \u003cucHeap+444\u003e       S               Rx       0x20000450          0           2\n```\n\n### Breakpoints\n```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.\n\n```[task_name]``` should be the descriptive string name of the task, equivalent to the TCB's ```pcTaskName```.\n\n```[target_location``` should be a location in a format recognized by the GDB's builtin break command.\n\nThis command may have undefined behavior in multiprocess environments.\n```\n(gdb) freertos break Rx xQueueReceive\nBreakpoint 1 at 0x1bf8: file ./../../../..//Source/queue.c, line 1382.\n```\n\n## References\n[Espressif's FreeRTOS GDB Extension](https://github.com/espressif/freertos-gdb)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffreertos%2Ffreertos-gdb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffreertos%2Ffreertos-gdb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffreertos%2Ffreertos-gdb/lists"}