{"id":7495777,"url":"https://github.com/Qubasa/perf_kernel","last_synced_at":"2025-05-02T03:30:22.844Z","repository":{"id":50660178,"uuid":"295169335","full_name":"Qubasa/perf_kernel","owner":"Qubasa","description":"Multicore x64 kernel with a focus on introspection and debugging capabilities.","archived":false,"fork":false,"pushed_at":"2024-06-27T13:33:29.000Z","size":68534,"stargazers_count":61,"open_issues_count":0,"forks_count":11,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-04-22T08:03:56.454Z","etag":null,"topics":["hpc","kernel","performance","performance-analysis","rust","smp","x86-64"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Qubasa.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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}},"created_at":"2020-09-13T14:32:30.000Z","updated_at":"2025-01-01T04:14:24.000Z","dependencies_parsed_at":"2024-08-06T06:05:56.902Z","dependency_job_id":"dc68f101-c402-4acf-a045-412c20fc8e86","html_url":"https://github.com/Qubasa/perf_kernel","commit_stats":null,"previous_names":["qubasa/perf_kernel","luis-hebendanz/perf_kernel"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Qubasa%2Fperf_kernel","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Qubasa%2Fperf_kernel/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Qubasa%2Fperf_kernel/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Qubasa%2Fperf_kernel/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Qubasa","download_url":"https://codeload.github.com/Qubasa/perf_kernel/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251980882,"owners_count":21675037,"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":["hpc","kernel","performance","performance-analysis","rust","smp","x86-64"],"created_at":"2024-04-07T01:12:58.033Z","updated_at":"2025-05-02T03:30:22.333Z","avatar_url":"https://github.com/Qubasa.png","language":"Rust","funding_links":[],"categories":["rust"],"sub_categories":[],"readme":"# Perf Kernel\n\nThis is a research multicore x86_64 kernel that supports AVX and SSE with a focus on introspection and debugging capabilities.  \n\n## Setup \u0026 Debug Build\nClone the repo with submodules:\n```bash\n$ git clone --recursive \u003curl\u003e\n```\n\nInstall the [nix package manager](https://nixos.org/download.html).  \nThe installation script requires that you have `sudo` access to `root`.\n```bash\n$ curl -L https://nixos.org/nix/install | sh\n```\nYou may ask yourself why I use this weird package manager. The answer is simple: A completely reproducable and pinned development environment that works across every Linux distribution the same. Also through nix installed packages are contained and have no side effects on your system. \n\n\nTo download all required pinned dependencies just execute:\n```bash\n$ cd \u003cproject_root\u003e\n$ nix-shell shell.nix\n```\n\nThen install some cargo dependencies:\n```bash\n$ cd \u003cproject_root\u003e\n$ cargo install --path tools/glue_gun\n$ rustup component add llvm-tools-preview rust-src\n```\n\nNow compile \u0026 run the kernel in qemu with:\n```bash\n$ cd \u003cproject_root\u003e/kernel\n$ cargo run\n```\n\n## Integrated code editor\nThis projects ships with a customized \u0026 pinned vscodium (vscode without telemetry) with all the necessary addons. Included features are:\n- in editor kernel debugging with source code breakpoints and variables window\n- rust analyzer completion support of kernel code\n- clippy linting\n- rust optimized dark theme \n\n\nOpen kernel source\n```bash\n# Open kernel source code\n$ code kernel/kernel.code-workspace\n\n# Open bootloader source code\n$ code crates/bootloader/bootloader.code-workspace\n```\n\n### Keyboard shortcuts\n- `F4` builds and runs the kernel in qemu awaiting a debugger\n- `F5` attaches debugger to running kernel\n- `F6` builds and runs the kernel normally\n\n## View assembly with radare2\n```bash\n$ cd \u003cproject_root\u003e/kernel\n$ r2 target/x86_64-os/debug/isofiles/boot/kernel.elf # View bootloader asm\n```\n```bash\n$ cd \u003cproject_root\u003e/kernel\n$ r2 target/x86_64-os/debug/perf_kernel # View kernel asm\n```\n\nLook into [crates/bootloader/linker.ld](crates/bootloader/linker.ld) to find the offset where the kernel gets mapped to.\n\n## Debug with gdb\n\nTo run the kernel in debugger await mode execute:\n```bash\n$ cargo run -- -d\n```\n\nDebugging the *bootloader* with gdb\n```bash\n$ cd \u003cproject_root\u003e/perf_kernel\n$ gdb -ex \"target remote: 1234\" -ex \"symbol-file target/x86_64-os/debug/isofiles/boot/kernel.elf\"\n```\n\nDebugging the *kernel* with gdb\n```bash\n$ cd \u003cproject_root\u003e/perf_kernel\n$ gdb -ex \"target remote: 1234\" -ex \"symbol-file target/x86_64-os/debug/perf_kernel\"\n```\n\n### Debugging a different cpu core \nIn gdb cpu cores get handled like threads. So to display all cpu cores execute: `info threads`\nTo set a breakpoint on a different core execute: `hb \u003caddress\u003e thread \u003ccpu_num\u003e`\n\n### Important\nIf you use qemu with kvm you have to use [hardware breakpoints](https://en.wikipedia.org/wiki/Breakpoint#Implementations). Those are set with `hb \u003caddress\u003e`\n\nIn qemu emulation mode just use the normal breakpoints set with `b \u003caddress\u003e`\n\n\n## Debug with qemu monitor\nConnect to [qemu monitor](https://qemu.readthedocs.io/en/latest/system/monitor.html) with\n```\n$ nc 127.0.0.1 8124\n(qemu) help\n```\n\nTo switch to a different cpu core, execute:\n```\n(qemu) cpu \u003ccore_num\u003e-1\n```\n\n## Linker map\nThe linker generates a linker map where all ELF objects are listed with their respective addresses.\nYou can find the file under `\u003cproject_root\u003e/perf_kernel/external/bootloader/target/linker.map`.\n\n\n## Debugging MMU with vmsh\n[vmsh](https://github.com/Luis-Hebendanz/vmsh/tree/kernel_inspector) is a tool that spawns a thread in a qemu process to extract the kvm filedescriptor. This enables us to read VM guest memory from the host. The [restart.sh](https://github.com/Luis-Hebendanz/perf_kernel/blob/master/perf_kernel/restart.sh) does all of this automatically and then writes the MMU state as text into `target/dump.analysis`   \n\nExcerpt:\n```\nVirt Addr         Phys Addr       Size Perms Cache  NX\n0x0            -\u003e UNMAPPED        4Kb \n0x1000         -\u003e 0x1000          4Kb  R       PCD NX \n...\n0x3000         -\u003e 0x3000          4Kb  R       PCD NX \n0x4000         -\u003e 0x4000          4Kb  W              \n0x5000         -\u003e 0x5000          4Kb  R       PCD NX \n...\n0xb7000        -\u003e 0xb7000         4Kb  R       PCD NX \n0xb8000        -\u003e 0xb8000         4Kb  W       PCD NX \n0xb9000        -\u003e 0xb9000         4Kb  R       PCD NX \n...\n0xff000        -\u003e 0xff000         4Kb  R       PCD NX \n0x100000       -\u003e 0x100000        4Kb  R              \n...\n```\n\n## ISO file\nTo create a new ISO file, `cargo run` needs to be executed. `cargo build` does not suffice, it only generates a new kernel executable file but not a new ISO file. The path to the ISO is `target/x86_64-os/debug/bootimage-perf_kernel.iso` or if build in release mode `target/x86_64-os/release/bootimage-perf_kernel.iso`. To create a bootable USB stick just flash the image onto the USB device with:\n```bash\n$ dd bs=5M if=target/x86_64-os/release/bootimage-perf_kernel.iso of=/dev/\u003cYourUSB\u003e status=progress\n```\n\n## PXE boot\nPreviously I tried to use `pixiecore` to setup PXE however there are a couple of incompatibilities because it always uses it's own IPXE build integrated into the tool.\nBut IPXE does not currently support Multibootv2 booting, that's why shell.nix builds a custom version of IPXE that can be found under `$IPXE/undionly.kpxe`\n\n\n## LLVM assembly\nIf you are interested in the LLVM assembly of your kernel then execute `cargo asm` this generates the LLVM asm in release mode under: `target/x86_64-os/release/deps/perf_kernel-*.s`\n\n## Build system\nThe build system is highly custom but well integrated into cargo. The [glue_gun](tools/glue_gun/README.md) tool goes into more detail.\n\nImportant configuration files for the build system are:\n* [.cargo/config.toml](kernel/.cargo/config.toml)\n* [Cargo.toml](kernel/Cargo.toml)\n* [x86_64-os.json](kernel/x86_64-os.json)\n* [i686-uknown-linux-gnu.json](crates/bootloader/i686-unknown-linux-gnu.json)\n* [linker.ld](crates/bootloader/linker.ld)\n* [build.rs](crates/bootloader/build.rs)\n* [rust-toolchain](rust-toolchain)\n\n## Run tests\nTo execute tests run:\n```\n$ cd \u003cproject_root\u003e/perf_kernel\n$ cargo test\n```\nRun specific test:\n```\n$ cargo test --test heap_allocator\n```\n\n## Developed on a\n* AMD Ryzen 5 3500U\n* EPYC-v1\n* AMD Family 17h Model 18h\n\n## Resources\n* https://os.phil-opp.com/\n* https://www.amd.com/system/files/TechDocs/24593.pdf\n* https://github.com/gamozolabs/chocolate_milk/\n* https://uefi.org/sites/default/files/resources/ACPI_6_3_final_Jan30.pdf\n* [Use 1Gib pages sparringly](https://forum.osdev.org/viewtopic.php?f=1\u0026t=32699)\n* [Don't touch MTRRs](https://forum.osdev.org/viewtopic.php?t=29034\u0026p=246311)\n* https://virtio-fs.gitlab.io/index.html#overview\n* https://gitlab.redox-os.org/redox-os/tfs\n* http://9p.cat-v.org/\n* https://www.linux-kvm.org/page/Tuning_Kernel\n\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FQubasa%2Fperf_kernel","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FQubasa%2Fperf_kernel","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FQubasa%2Fperf_kernel/lists"}