{"id":21300800,"url":"https://github.com/micro-os-plus/drtm","last_synced_at":"2026-01-01T21:56:56.979Z","repository":{"id":57118209,"uuid":"84873242","full_name":"micro-os-plus/drtm","owner":"micro-os-plus","description":"An xPack with the Debug Run-Time Metadata library","archived":false,"fork":false,"pushed_at":"2017-11-13T13:06:42.000Z","size":89,"stargazers_count":0,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"xpack","last_synced_at":"2025-09-30T19:43:18.382Z","etag":null,"topics":["c-plus-plus","debug","gdb","metadata","run-time","xpack"],"latest_commit_sha":null,"homepage":null,"language":"C++","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/micro-os-plus.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}},"created_at":"2017-03-13T20:50:04.000Z","updated_at":"2017-03-23T20:16:36.000Z","dependencies_parsed_at":"2022-08-23T04:40:32.697Z","dependency_job_id":null,"html_url":"https://github.com/micro-os-plus/drtm","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/micro-os-plus/drtm","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/micro-os-plus%2Fdrtm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/micro-os-plus%2Fdrtm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/micro-os-plus%2Fdrtm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/micro-os-plus%2Fdrtm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/micro-os-plus","download_url":"https://codeload.github.com/micro-os-plus/drtm/tar.gz/refs/heads/xpack","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/micro-os-plus%2Fdrtm/sbom","scorecard":{"id":642750,"data":{"date":"2025-08-11","repo":{"name":"github.com/micro-os-plus/drtm","commit":"7fef50c7b212de3d54e8c0a44eedb18577c5a973"},"scorecard":{"version":"v5.2.1-40-gf6ed084d","commit":"f6ed084d17c9236477efd66e5b258b9d4cc7b389"},"score":3,"checks":[{"name":"Dangerous-Workflow","score":-1,"reason":"no workflows found","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#dangerous-workflow"}},{"name":"Maintained","score":0,"reason":"0 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#maintained"}},{"name":"Code-Review","score":0,"reason":"Found 0/30 approved changesets -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#code-review"}},{"name":"Packaging","score":-1,"reason":"packaging workflow not detected","details":["Warn: no GitHub/GitLab publishing workflow detected."],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#packaging"}},{"name":"SAST","score":0,"reason":"no SAST tool detected","details":["Warn: no pull requests merged into dev branch"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#sast"}},{"name":"Token-Permissions","score":-1,"reason":"No tokens found","details":null,"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#token-permissions"}},{"name":"Binary-Artifacts","score":10,"reason":"no binaries found in the repo","details":null,"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#binary-artifacts"}},{"name":"Pinned-Dependencies","score":-1,"reason":"no dependencies found","details":null,"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#pinned-dependencies"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#cii-best-practices"}},{"name":"Vulnerabilities","score":10,"reason":"0 existing vulnerabilities detected","details":null,"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#vulnerabilities"}},{"name":"License","score":10,"reason":"license file detected","details":["Info: project has a license file: LICENSE:0","Info: FSF or OSI recognized license: MIT License: LICENSE:0"],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#license"}},{"name":"Signed-Releases","score":-1,"reason":"no releases found","details":null,"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#signed-releases"}},{"name":"Fuzzing","score":0,"reason":"project is not fuzzed","details":["Warn: no fuzzer integrations found"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#fuzzing"}},{"name":"Branch-Protection","score":0,"reason":"branch protection not enabled on development/release branches","details":["Warn: branch protection not enabled for branch 'xpack'"],"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#branch-protection"}},{"name":"Security-Policy","score":0,"reason":"security policy file not detected","details":["Warn: no security policy file detected","Warn: no security file to analyze","Warn: no security file to analyze","Warn: no security file to analyze"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#security-policy"}}]},"last_synced_at":"2025-08-21T11:16:10.383Z","repository_id":57118209,"created_at":"2025-08-21T11:16:10.383Z","updated_at":"2025-08-21T11:16:10.383Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28164085,"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","status":"online","status_checked_at":"2026-01-01T02:00:06.694Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["c-plus-plus","debug","gdb","metadata","run-time","xpack"],"created_at":"2024-11-21T15:31:45.462Z","updated_at":"2026-01-01T21:56:56.950Z","avatar_url":"https://github.com/micro-os-plus.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![npm (scoped)](https://img.shields.io/npm/v/@ilg/drtm.svg)](https://www.npmjs.com/package/@ilg/drtm) \n[![license](https://img.shields.io/github/license/micro-os-plus/drtm.svg)](https://github.com/micro-os-plus/drtm/blob/xpack/LICENSE) \n[![Travis](https://img.shields.io/travis/micro-os-plus/drtm.svg?label=linux)](https://travis-ci.org/micro-os-plus/drtm)\n\n## DRTM\n\nAn xPack with the **D**ebug **R**un-**T**ime **M**etadata library. \n\nThis library provies support for parsing the RTOS specific Debug Run-Time Metadata, used by thread-aware GDB servers. The Debug Run-Time Metadata is stored in the RTOS application flash space; it includes addresses of various scheduler data and offsets inside TCBs (Thread Control Blocks).\n\nThe purpose of DRTM is to improve portability of debugging tools, by removing the need to use hard-coded constants, like offsets into objects, that may vary between RTOS builds.\n\n## Thread-aware debugging overview\n\nBy default, modern cross-toolchain GDBs like `arm-none-eaby-gdb` have all the required support to display and navigate the stack trace for the current thread, including reading/writing the processor registers, even if the device specific definitions come from a custom implementation of the GDB server, like SEGGER J-Link GDBServer, or OpenOCD.\n\nGiven the available resources in today microcontrollers, most applications can now be  multi-threaded, and there are many RTOSes that implement multi-threading, like FreeRTOS or [µOS++ IIIe](http://micro-os-plus.github.io).\n\nHowever, generic GDB servers cannot have the required knowledge of RTOS internals, and are not able to recognise when multiple threads are used.\n\nTo acomplish this, the GDB servers need to be extended, either by use of plug-ins, like the J-Link GDB Server, or by adding code to the monolithic distribution, like OpenOCD.\n\nBasically, a thread-aware server should provide:\n\n- if the scheduler was started, the number of threads\n- a thread ID for each thread\n- a description string for each thread\n- the ID of the current thread\n- for all threads different than the current thread, the server should be able to read (and optionally write) all thread registers from the place where the thread context was saved.\n\n## User info\n\nNot related to a specific thread aware implementation or GDB server, in all cases it is recommended to have the debugged application built with the proper stack frames.\n\n### Compiler option `-mapcs-frame`\n\nWhen using `arm-none-eabi-gdb`, for a proper display of the stack trace and navigation amongst stack frames, the `-mapcs-frame` option must be added to the compiler command line used to build the embedded application. The purpose is to always generate a stack frame that is compliant with the ARM Procedure Call Standard for all functions, even if this is not strictly necessary for correct execution of the code.\n\nWithout this option, GDB will randomly, but quite often, display unrealistic stack traces, possibly with illegal addresses, totally useless in a debug session.\n\n## Developer info\n\nThis section is intended to developers that plan to include DRTM in their own GDB servers.\n\n### Easy install\n\nThe source files are available from [GitHub](https://github.com/micro-os-plus/drtm):\n\n```bash\n$ git clone https://github.com/micro-os-plus/drtm.git drtm.git\n```\n\nThe library is also available from the npm registry:\n\n```bash\n$ npm install @ilg/drtm\n```\n\n### Prerequisites\n\nThe source code require a modern C++ compiler, preferably GCC 5 or higher, but was also compiled with GCC 4.8. Be sure `-std=c++1y` or higher is used when compiling source files that include these templates.\n\n### No warnings\n\nSpecial care was taken to avoid compiler warnings. For this the tests were compiled with \n\n- clang `-Weverything -Wno-format-pedantic -Wno-c++98-compat -Wno-c99-extensions -Wno-c++98-compat-pedantic -Wno-documentation-unknown-command` and \n- GCC 6 `-Wall -Wextra -Wunused -Wuninitialized -Wmissing-declarations -Wconversion -Wpointer-arith -Wshadow -Wlogical-op -Wfloat-equal`\n\n### Testing\n\nAs for any xPack, the standard way to run the project tests is via `npm`:\n\n```bash\n$ cd drtm.git\n$ npm test\n```\n\nThe tests can also be executed directly, without `npm`:\n\n```bash\n$ cd drtm.git\n$ bash scripts/xmake.sh tests \n```\n\nTo clean the previous test builds, use:\n\n```bash\n$ cd drtm.git\n$ bash scripts/xmake.sh tests -- clean\n```\n\n### Templates only, no source files\n\nThe DRTM library is distributed as a set of C++ templates, that must be instantiated with classes that define the backend and memory allocator specific for the application.\n\nFor an example how to use it, please take a look at the `test/sample/main.c` file and the files in the `samples` folder.\n\n### Integration with C projects\n\nAlthough written in C++, this library can be easily integrated into a C project, using a C wrapper.\n\n### Integration details\n\nThe DRTM C++ implementation uses two templates, one for the backend (mandatory) and one for a custom allocator (optional).\n\nBoth these templates call existing functions from the application, directly or via a forwarder.\n\nSamples of these templates, that can be used as a starting point, can be found in the `samples` folder.\n\n#### The backend template\n\nThis template adapts the DRTM to the actual application, for things like reading/writing the target memory and sending messages to the output terminal or logger.\n\nThe usual implementation is a stateless class, but DRTM takes the safer path and instantiates this class, in case you need to keep state, like pointers to objects, forwarders, etc.\n\n* Variable argument functions\n\nThe `v*` versions of the output functions implement the variable argument specialisation. If similar `var_args` variants of the output/logging system functions are available, forward the calls to them. If not, use a temporary buffer, perform the formatting with `vsnprintf()` and send the final string to the output/logger (please check the sample implementation of `output_warning()` for a functional version).\n\n* Type specialisations for read/write\n\nThe minimum requirement is to have a pair a functions that read/write a byte array. If specialised functions are already available, forward the calls to them, otherwise implement the endianness conversions in the backend template, as shown in the sample implementation.\n\n* The symbols table\n\nRegardless of the actual implementation, the only way GDB can construct the list of threads is by reading specific locations in the target memory. The addresses of these locations are generally provided by the linker, as the values of some public/global symbols, so the GDB server needs a method to get the values of certain symbols from the debugged ELD.\n\nDepending on the actual implementation of the GDB server, this might be very simple or somehow tricky.\n\nThe idea is that the GDB server, as the name implies, is... a server, i.e. it responds to requests from the GDB client, so it cannot directly call the GDB client (which has the symbols loaded from the ELF file) and ask for the value of a given symbol, and a more elaborate protocol is required.\n\nThe details of this protocol, or the details of the implementation, are not relevant for DRTM. DRTM requires the value of a single symbol (`os_rtos_drtm`) and for this the backend template must include a function (`get_symbol_address()`) that must call any support available in the application to get the value of this symbol.\n\n\n#### The memory allocator template\n\nThe need to use a custom allocator instead of the standard C++ allocator is related to memory allocator consistency in multi-threaded environments. If the multi-threaded scheduler is preemptive, and the threads do need to allocate memory at any time, a synchronisation mechanism (like a mutex) should be used when accessing the memory allocator. If the allocator in the system library is not thread safe (most moderm POSIX implementations are), but is implemented at application level, then this application specific allocator must be passed to the DRTM library.\n\nAs a general recommendation, if the application uses a custom memory manager, pass it to the DRTM library as a custom allocator. If not, do not define a custom allocator but use the `std::allocator`.\n\n#### The aplication specific header\n\nIn the sample implementation, all definitions relating to the applications are grouped in the `your-application.h` file, which is included in the templates. In a real life case, either directly include all required application headers in the templates, or group these headers in a file, and include only this file in the templates.\n\n#### The template instantiations\n\nBeing a header only library, DRTM itself does not have any source files (well, except the `version.c` file, which is not actually used).\n\nAccording to current C++ specifications, templates are automatically instantiated by the compiler, when needed. To make things more clear, explicit instantiation is used in the `drtm.cpp` file, which implements the C wrapper.\n\n## Future developments\n\nThe first version (0.x) of the metadata will be a simple structure with various members, so the library will still need to use hard-coded offsets in this structure to access the data.\n \nFor version 1.x it is planed to improve the structure of the metadata, by using `id:value` pairs, in a sort of **compile-time binary JSON**, so the fixed point will be a list of numeric IDs, not offsets in a structure.\n\nThe first versions will focus on describing the metadata specific to µOS++ IIIe, but given that JSONs are generic enough to describe any data structures, it shouldn't be that difficult to describe most of the data types and memory structures in use by popular RTOSes. \n\nThe assumption is that the number of such different data structures used to manage the list of threads is relatively low and manageable, so it should be easier to add a new definition to an existing framework that is already fully functional, than to redo an implementation completely from scratch. And once the DRTM data is in, the result should be directly available to all servers that use the DRTM library (OpenOCD, J-Link, QEMU being on my TODO list).\n\n## Forum\n\nThe DRTM proposal was posted on the [project forum](https://www.element14.com/community/thread/59299/l/drtm-debug-run-time-metadata-proposal).\n\n## License\n\nThe original content is released under the [MIT License](https://opensource.org/licenses/MIT), with all rights reserved to [Liviu Ionescu](https://github.com/ilg-ul).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmicro-os-plus%2Fdrtm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmicro-os-plus%2Fdrtm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmicro-os-plus%2Fdrtm/lists"}