{"id":13998168,"url":"https://github.com/jjkt/zmu","last_synced_at":"2025-07-23T05:32:43.793Z","repository":{"id":211544863,"uuid":"45065347","full_name":"jjkt/zmu","owner":"jjkt","description":"zmu - Emulator for Microcontroller Systems","archived":false,"fork":false,"pushed_at":"2022-07-28T16:25:16.000Z","size":1032,"stargazers_count":91,"open_issues_count":3,"forks_count":4,"subscribers_count":5,"default_branch":"master","last_synced_at":"2024-08-10T19:16:25.752Z","etag":null,"topics":["cortex-m","cortex-m0","cortex-m3","cortex-m4","cortex-m4f","emulator","microcontroller","rust"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jjkt.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}},"created_at":"2015-10-27T19:39:02.000Z","updated_at":"2024-07-22T18:38:07.000Z","dependencies_parsed_at":null,"dependency_job_id":"c5f665e4-8699-4880-b939-824f22ccffaf","html_url":"https://github.com/jjkt/zmu","commit_stats":null,"previous_names":["jjkt/zmu"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jjkt%2Fzmu","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jjkt%2Fzmu/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jjkt%2Fzmu/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jjkt%2Fzmu/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jjkt","download_url":"https://codeload.github.com/jjkt/zmu/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":227245133,"owners_count":17753239,"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":["cortex-m","cortex-m0","cortex-m3","cortex-m4","cortex-m4f","emulator","microcontroller","rust"],"created_at":"2024-08-09T19:01:26.534Z","updated_at":"2025-07-23T05:32:43.773Z","avatar_url":"https://github.com/jjkt.png","language":"Rust","funding_links":[],"categories":["Rust"],"sub_categories":[],"readme":"# zmu - Emulator for Microcontroller Systems\n\nzmu is an system level emulator for microcontrollers, aiming for high speed simulation of core and peripherals. Currently targets ARM Cortex MCUs.\n\nzmu supports Linux and Windows operating systems.\n\n## Supported features\n- Loading of ELF binaries\n- Relatively efficient Simulation\n    - Intel Core i7-2630QM @ 2.8 Ghz can simulate 40-50 Mhz Cortex-m4 in realtime\n- Architectures:\n    - arm-v6m,\n    - arm-v7m (partial support)\n    - arm-v7me (partial support)\n- Cores (in progress): Cortex-m0/m0+, Cortex-m3, Cortex-m4\n    - Pre-decoding of instructions for efficient simulation\n    - Exception and fault handling\n    - Processor sleep\n- ARM semihosting, supported semihosting extensions:\n    - open, close (streams only)\n    - FLEN\n    - ISTTY\n    - write, read\n    - seek, clock, exception -\u003e exit\n    - errno\n- ITM\n    - (TPIU) write stimulus register data to a file, in framed format\n    - STIM0 .. STIM31 supported\n- DWT\n    - Cycle counter\n- Instruction trace\n- GDB Server\n    - single stepping\n    - range stepping\n    - breakpoints\n\n## Missing / Planned features\n- Time simulation / sync to real time\n- Some instructions are not yet properly supported\n    - ~20 instructions missing: BFC, CDP, CLREX, LDMDB, ...\n    - Full v7m + DSP exensions support\n    - Full v7me + floats (m4f)\n- ARM Cortex peripherals\n    - NVIC (partial support available)\n    - MPU\n- Semihosting: filesystem access\n- System Simulation:\n    - device profiles, eg stm32 device support\n    - board profiles, external peripheral simulation\n- GDB Server:\n    - Reading/Writting memory\n    - Writting Registers\n    - Pass the port on the command line\n\n## Depedencies\n\nYou have to install RUST. Assuming Ubuntu 18.04.\n\n```sh\ncurl https://sh.rustup.rs -sSf | sh\n```\n\nFollow the install menu, then run the following command in the terminal used for compilation\n\n```sh\nsource ~/.cargo/env\n```\n\n\n## How to Compile\n\n```sh\nchmod +x buildall.sh\n./buildall.sh\n```\nThe executables are genereated in the dir ```./target/release/```.\n\n## Testing\n\nInstall support for compiling for cortex-M targets: (needed for rust based tests)\n\n```sh\nrustup target add thumbv6m-none-eabi thumbv7m-none-eabi thumbv7em-none-eabi thumbv7em-none-eabihf\n```\n\nYou need ARM compiler to compile some of the examples. Get the latest compilers from [ARM website](https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/gnu-rm/downloads). Some Linux distros (like Ubuntu) have prebuilt packages for this.\n```sh\n'sudo apt install gcc-arm-none-eabi'\n```\n\nSet the environmental variable GCC_HOME to point to the home of arm-none-eabi-gcc. The default location is /usr\n\n```sh\nexport GCC_HOME=/usr\nchmod +x testall.sh\n./testall.sh\n```\n\n## Usage\n\n- ```zmu-armv6m``` runs the zmu with support for armv6m instructions.\n- ```zmu-armv7m``` runs the zmu with support for armv7m instructions.\n\n### Run an ELF binary\n```\n$./target/release/zmu-armv6m run tests/hello_world/hello_world-cm0.elf\nhello, world\n```\n\n### Run with tracing\n```\n$./target/release/zmu-armv7m run -t tests/minimal/minimal-cm3.elf | head -3\n4906      ldr r1, [pc, #+24]               00000074  Reset_Handler         2 qvczn r0:00000000 1:00001c84 2:00000000 3:00000000 4:00000000 5:00000000 6:00000000 7:00000000 8:00000000 9:00000000 10:00000000 11:00000000 12:00000000\n4A07      ldr r2, [pc, #+28]               00000076  Reset_Handler         4 qvczn r0:00000000 1:00001c84 2:20000000 3:00000000 4:00000000 5:00000000 6:00000000 7:00000000 8:00000000 9:00000000 10:00000000 11:00000000 12:00000000\n4B07      ldr r3, [pc, #+28]               00000078  Reset_Handler         6 qvczn r0:00000000 1:00001c84 2:20000000 3:20000854 4:00000000 5:00000000 6:00000000 7:00000000 8:00000000 9:00000000 10:00000000 11:00000000 12:00000000\n```\n\n### Run with ITM trace via itmdump\n\nFollowing example uses the [itmdump](https://docs.rs/itm/0.3.1/itm/) tool and embedded rustbook examples to show how to dump itm trace prints to stdout from the zmu. To install itmdump, you need to run ```cargo install itmdump```.\n\n```\n$./target/release/zmu-armv7m run --itm /dev/stdout tests/rustbook/target/thumbv7m-none-eabi/debug/examples/itm | itmdump\nHello, world!\n```\n\n\n### \"RTFM\" examples with rust\nZmu can already run many of the [cortex-m-rtfm](https://github.com/japaric/cortex-m-rtfm) examples directly.\n\nHere are few example runs:\n\nmessage.rs\n```\n$./target/release/zmu-armv7m run ./tests/cortex-m-rtfm/target/thumbv7m-none-eabi/debug/examples/message\nfoo\nbar(0)\nbaz(1, 2)\nfoo\nbar(1)\nbaz(2, 3)\n^C\n```\n\nresource.rs\n```\n$./target/release/zmu-armv7m run ./tests/cortex-m-rtfm/target/thumbv7m-none-eabi/debug/examples/resource\nUART0: SHARED = 1\nUART1: SHARED = 2\n```\n\n### \"Hello, world\" example with Arm GCC + semihosting\n\n```c\n#include \u003cstdio.h\u003e\n#include \u003cstdlib.h\u003e\n\nint main(void)\n{\n    printf(\"hello, world\\n\");\n}\n\nvoid SystemInit(void) { }\n\nextern void initialise_monitor_handles(void);\n\nvoid _start(void)\n{\n    initialise_monitor_handles();\n    main();\n    exit(0);\n}\n\n\n__attribute__((used))\nvoid _fini(void) { }\n```\n\nCompile the code with GCC:\n```\narm-none-eabi-gcc -O2 --specs=rdimon.specs -mthumb -g -nostartfiles -T link.ld   -mcpu=cortex-m0 -lc -lrdimon main.c /usr/share/gcc-arm-embedded/samples/startup/startup_ARMCM0.S -o hello_world-cm0.elf\n```\n\nRun the emulator:\n```\n$zmu run tests/hello_world/hello_world-cm0.elf\nhello, world\n```\n\nRun the GDB Server:\n```\n$zmu run --gdb tests/hello_world/hello_world-cm0.elf\nStarting GDB Server on port 9001 ...\n```\n\nOn a separate terminal start the gdb client:\n```\n$ gdb-multiarch tests/hello_world/hello_world-cm0.elf\nGNU gdb (Debian 13.1-3) 13.1\nCopyright (C) 2023 Free Software Foundation, Inc.\nLicense GPLv3+: GNU GPL version 3 or later \u003chttp://gnu.org/licenses/gpl.html\u003e\nThis is free software: you are free to change and redistribute it.\nThere is NO WARRANTY, to the extent permitted by law.\nType \"show copying\" and \"show warranty\" for details.\nThis GDB was configured as \"x86_64-linux-gnu\".\nType \"show configuration\" for configuration details.\nFor bug reporting instructions, please see:\n\u003chttps://www.gnu.org/software/gdb/bugs/\u003e.\nFind the GDB manual and other documentation resources online at:\n    \u003chttp://www.gnu.org/software/gdb/documentation/\u003e.\n\nFor help, type \"help\".\nType \"apropos word\" to search for commands related to \"word\"...\nReading symbols from tests/hello_world/hello_world-cm0.elf...\n(gdb) target remote localhost:9001\nRemote debugging using localhost:9001\nReset_Handler ()\n    at /usr/share/doc/gcc-arm-none-eabi/examples/startup/startup_ARMCM0.S:150\n150             ldr     r1, =__etext\n(gdb) b main\nBreakpoint 1 at 0x5c: file main.c, line 6.\n(gdb) c\nContinuing.\n\nBreakpoint 1, main () at main.c:6\n6           printf(\"hello, world\\n\");\n(gdb)\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjjkt%2Fzmu","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjjkt%2Fzmu","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjjkt%2Fzmu/lists"}