{"id":48348773,"url":"https://github.com/chgroeling/libmicroemu","last_synced_at":"2026-04-05T08:12:37.605Z","repository":{"id":260899164,"uuid":"882660153","full_name":"chgroeling/libmicroemu","owner":"chgroeling","description":"ARM Microcontroller Emulator Library","archived":false,"fork":false,"pushed_at":"2025-04-13T15:39:38.000Z","size":5585,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-13T16:38:34.297Z","etag":null,"topics":["arm","cortex-m","cortex-m4","cortex-m4f","cpp","embedded-systems","emulator","iot","simulation"],"latest_commit_sha":null,"homepage":"","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/chgroeling.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,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-11-03T12:27:36.000Z","updated_at":"2025-03-15T17:01:26.000Z","dependencies_parsed_at":null,"dependency_job_id":"63bb59b5-bbb0-494d-854d-312b09a09957","html_url":"https://github.com/chgroeling/libmicroemu","commit_stats":null,"previous_names":["chgroeling/libmicroemu"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/chgroeling/libmicroemu","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chgroeling%2Flibmicroemu","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chgroeling%2Flibmicroemu/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chgroeling%2Flibmicroemu/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chgroeling%2Flibmicroemu/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/chgroeling","download_url":"https://codeload.github.com/chgroeling/libmicroemu/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chgroeling%2Flibmicroemu/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31428726,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-05T02:22:46.605Z","status":"ssl_error","status_checked_at":"2026-04-05T02:22:33.263Z","response_time":75,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["arm","cortex-m","cortex-m4","cortex-m4f","cpp","embedded-systems","emulator","iot","simulation"],"created_at":"2026-04-05T08:12:37.031Z","updated_at":"2026-04-05T08:12:37.597Z","avatar_url":"https://github.com/chgroeling.png","language":"C++","readme":"# ARM Microcontroller Emulator Library \n_libmicroemu_ is a lightweight, embeddable library for ARM microcontroller emulation, currently supporting the ARMv7-M architecture with plans to extend to additional ARM architectures. It is designed for:\n\n- **Accelerating development** by enabling local testing of ARM programs\n- **Creating digital twins** for commissioning without physical hardware\n- **Embedding ARM emulation** seamlessly into larger projects\n\nWhile shipped with a command-line application (called _microemu_), _libmicroemu_ can be used independently, allowing for flexible integration.\n\n[![GitHub release (latest SemVer)](https://img.shields.io/github/v/release/chgroeling/libmicroemu?label=release\u0026sort=semver)](https://github.com/chgroeling/libmicroemu/releases)[![tests](https://github.com/chgroeling/libmicroemu/actions/workflows/tests.yml/badge.svg)](https://github.com/chgroeling/libmicroemu/actions/workflows/tests.yml)[![docs](https://github.com/chgroeling/libmicroemu/actions/workflows/docs.yml/badge.svg)](https://chgroeling.github.io/libmicroemu)[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n\n### Key Features\n- **Dependency-Free Core**  \n  No external libraries are needed to use _libmicroemu_.\n- **Embeddable Design**  \n  Integrate easily into any C++ project or use it as a standalone emulator.\n- **Accurate ARM Cortex-M Simulation**  \n  Emulates ARMv7-M with full exception support (e.g., UsageFault, HardFault, SysTick). Future plans include ARMv7-A and support for the NVIC.\n- **Predictable and Deterministic Behavior**  \n  The emulator ensures consistent execution by avoiding dynamic memory allocation and non-deterministic algorithms, making it suitable for applications requiring repeatable outcomes.\n- **No C++ Exceptions**  \n  The emulator is implemented without the use of C++ exceptions, providing a predictable control flow and simplifying integration into projects that avoid exception handling.\n- **Optional Command-Line Interface**  \n  The companion CLI program _microemu_ simplifies testing and debugging. It requires Conan for managing dependencies (fmt, spdlog, cxxopts), while _libmicroemu_ itself remains dependency-free.\n- **Semihosting Support**    \n  Provides built-in semihosting, enabling communication between the emulator and the host system for tasks such as file I/O and console output.\n\n## Development Status\n_libmicroemu_ is currently under active development and can already execute a significant range of ARMv7-M programs. Floating-point functionality is not natively supported in the emulator at this time, but it can be achieved by compiling programs with `-mfloat-abi=soft`, allowing software-based floating-point emulation within the binary itself.\n\n### Roadmap\n- **ARM Core Completion** – Prioritize complete ARMv7-M functionality, then expand to other architectures like ARMv7-A.\n- **Performance Optimization** – Implement performance optimizations after achieving full ARMv7-M support.\n- **Peripheral Emulation Expansion** – Limited peripheral support initially, focused on ARM core compatibility.\n- **NVIC Support** – Planned implementation for ARMv7-M interrupt controller.\n- **Hardware Floating-Point Emulation** – Planned support for native floating-point instructions.\n- **Remote Debugging Support** – Planned GDB integration for interactive debugging capabilities.\n- **Broader Configuration Options** – Further flexibility for custom peripherals and memory configurations.\n- **Vendor-Specific Chip Support** - Expand support for vendor-specific peripherals and features (e.g. STM and Renesas chips)\n- **Doxygen Documentation Improvement** – Enhance Doxygen documentation to improve usability and clarity, adding detailed descriptions for modules, functions, and configuration options to assist developers and users.\n\n## Getting Started\n### Installation\n1. **Clone the Repository:**\n    Clone the repository to your local machine and navigate into the project directory:\n\n    ```bash\n    git clone https://github.com/chgroeling/libmicroemu\n    cd libmicroemu\n    ```\n2. **Install Dependencies:**\n    _libmicroemu_ uses Conan 2 for dependency management, with profiles for different machines stored in the ./profiles directory. While Conan is primarily needed for the _microemu_ CLI, it also installs toolchains and GTest, making its use advisable. Run the following command to install dependencies and set options for building standalone components:\n\n    ```bash\n    conan install . -pr ./profiles/\u003cyour_build_profile\u003e --build=missing\n    ```\n\n    Replace \u003cyour_build_profile\u003e with the appropriate profile names for your setup.  This version uses the conan -o option for enabling _build_tests_ and _build_microemu_ when installing dependencies.\n3. **Build the Project with CMake:**\n    Create a build directory, configure the project, and compile it:\n\n    ```bash\n    cd build \u0026\u0026 cd Debug\n    cmake .\n    cmake --build .\n    ```\n4.\t**Run the Tests:**\n    To verify that everything is set up correctly, run the tests:\n\n    ```bash\n    ctest\n    ```\n\n   \n\n### Running the Emulator\nWith the build complete, you can run ARM binaries using _microemu_:\n\n```bash\n./microemu path/to/your-binary.elf\n```\n\nThe application provides logs showing register states, memory operations, and decoded instructions to assist with debugging. Use the \"--help\" command line option to learn more.\n\n### Precompiled Libraries and Releases\n_libmicroemu_ includes precompiled libraries in its releases, tagged using semantic versioning (e.g., `v1.0.0`). These binaries simplify integration and reduce build time, allowing for quick use without the need for compiling from source. Available on the [GitHub releases page](https://github.com/chgroeling/libmicroemu/releases), they include platform-specific static libraries and the _microemu_ CLI program. For custom needs, building from source remains an option to meet specific configuration requirements.\n\n## Embedding libmicroemu in Your Project\n_libmicroemu_ is designed to be easily integrated into larger C++ projects to provide ARM emulation capabilities. Below is a basic example demonstrating how to set up and execute an ELF binary using the library.\n\n### Example: Integrating libmicroemu\n```cpp\n#include \"libmicroemu/machine.h\"\n#include \u003ciostream\u003e\n#include \u003cvector\u003e\n\n// Path to the ELF file\nconstexpr static const char *kElfPath = \"coremark/prebuilt/bin/coremark.elf\";\n\nconstexpr static libmicroemu::me_adr_t kFlashSegVadr = 0x0U;\nconstexpr static libmicroemu::me_adr_t kRam1SegVadr = 0x20000000U;\n\nint main() {\n  libmicroemu::Machine machine;\n  std::cout \u003c\u003c \"Using libmicroemu version: \" \u003c\u003c machine.GetVersion() \u003c\u003c std::endl;\n\n  // Allocate memory for FLASH and RAM1 segments\n  auto flash_seg = std::vector\u003cuint8_t\u003e(0x20000u); // 128KB for FLASH\n  auto ram1_seg = std::vector\u003cuint8_t\u003e(0x40000u);  // 256KB for RAM1\n\n  // Set up memory segments\n  machine.SetFlashSegment(flash_seg.data(), flash_seg.size(), kFlashSegVadr);\n  machine.SetRam1Segment(ram1_seg.data(), ram1_seg.size(), kRam1SegVadr);\n\n  // Load the ELF file and set the entry point\n  if (machine.Load(kElfPath, true) != libmicroemu::StatusCode::kSuccess) {\n    std::cerr \u003c\u003c \"Failed to load ELF file.\" \u003c\u003c std::endl;\n    return EXIT_FAILURE;\n  }\n\n  // Execute the ELF file\n  auto res_exec = machine.Exec();\n  if (res_exec.IsErr()) {\n    std::cerr \u003c\u003c \"Failed to execute ELF file.\" \u003c\u003c std::endl;\n    return EXIT_FAILURE;\n  }\n  return 0;\n}\n```\n\n### Embedding Considerations\n- **CMake Integration**: You can include _libmicroemu_ directly in your project by adding it as a CMake subdirectory:\n  ```cmake\n  add_subdirectory(path/to/libmicroemu)\n  target_link_libraries(your_project PRIVATE libmicroemu)\n  ```\n- **Precompiled Libraries**: For convenience, precompiled versions of _libmicroemu_ are available. These can be linked to your project to save build time and simplify integration.\n- **Memory Configuration**: Ensure you allocate and set up code and RAM segments properly to emulate the ARM memory layout accurately.\n- **Integration Points**: _libmicroemu_ can be seamlessly embedded into any C++ project, supporting both development testing and deployment phases.\n- **Custom Enhancements**: Depending on your application, you can extend memory configurations, include peripheral simulation, or adapt the emulator for specific use cases.\n\n## Performance Results\nThe CoreMark benchmark for a 2K performance run yielded **162.73 CoreMarks** on the emulator (detailed report follows), roughly equivalent to a Cortex-M4 at 50 MHz. This baseline result was measured on a MacBook Air with an M1 processor. Currently, the focus is on completing ARMv7-M support, with performance optimizations planned for future updates.\n\n**Background**: CoreMark is a widely recognized benchmark used to assess the performance of microcontrollers and processors. For comparison, a typical ARM Cortex-M4 running at 100 MHz might score between 250 to 350 CoreMarks, assuming linear scaling with clock speed.\n\n```\n2K performance run parameters for coremark.\nCoreMark Size    : 666\nTotal ticks      : 2458\nTotal time (secs): 24.580000\nIterations/Sec   : 162.733930\nIterations       : 4000\nCompiler version : GCC10.3.1 20210824 (release)\nCompiler flags   : -g\nMemory location  : STACK\nseedcrc          : 0xe9f5\n[0]crclist       : 0xe714\n[0]crcmatrix     : 0x1fd7\n[0]crcstate      : 0x8e3a\n[0]crcfinal      : 0x65c5\nCorrect operation validated. See README.md for run and reporting rules.\nCoreMark 1.0 : 162.733930 / GCC10.3.1 20210824 (release) -g / STACK\n```\n## Documentation\n[Latest build - Doxygen documentation](https://chgroeling.github.io/libmicroemu)\n\n## Contributing\nContributions are welcome! Please follow the Google C++ Style Guide, and ensure all new code includes documentation and test cases.\n\n1. Fork the repository.\n2. Create a feature branch.\n3. Commit your changes.\n4. Open a pull request.\n\n## License\nThis project is licensed under the MIT License.","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchgroeling%2Flibmicroemu","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchgroeling%2Flibmicroemu","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchgroeling%2Flibmicroemu/lists"}