{"id":44685830,"url":"https://github.com/grandbirdlizard/x3dctl","last_synced_at":"2026-03-08T17:03:31.208Z","repository":{"id":338070158,"uuid":"1153050614","full_name":"GrandBIRDLizard/X3Dctl","owner":"GrandBIRDLizard","description":"x3dctl is a lightweight Linux CLI tool for managing operating modes on AMD X3D processors, allowing users to easily switch between cache-optimized and frequency-optimized CPU behavior.","archived":false,"fork":false,"pushed_at":"2026-02-12T17:42:12.000Z","size":15,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-02-13T00:58:13.171Z","etag":null,"topics":["amd","cli","cpu","gaming","hardware-control","linux","performance","sysfs","system-utility","x3d"],"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/GrandBIRDLizard.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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-08T20:30:57.000Z","updated_at":"2026-02-12T21:46:51.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/GrandBIRDLizard/X3Dctl","commit_stats":null,"previous_names":["grandbirdlizard/x3dctl"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/GrandBIRDLizard/X3Dctl","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GrandBIRDLizard%2FX3Dctl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GrandBIRDLizard%2FX3Dctl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GrandBIRDLizard%2FX3Dctl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GrandBIRDLizard%2FX3Dctl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/GrandBIRDLizard","download_url":"https://codeload.github.com/GrandBIRDLizard/X3Dctl/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GrandBIRDLizard%2FX3Dctl/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29471152,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-15T05:26:30.465Z","status":"ssl_error","status_checked_at":"2026-02-15T05:26:21.858Z","response_time":118,"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":["amd","cli","cpu","gaming","hardware-control","linux","performance","sysfs","system-utility","x3d"],"created_at":"2026-02-15T06:02:15.486Z","updated_at":"2026-03-06T05:57:35.645Z","avatar_url":"https://github.com/GrandBIRDLizard.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cimg width=\"1408\" height=\"538\" alt=\"X3Dctl_logo_final_butcltleft\" src=\"https://github.com/user-attachments/assets/4ae01d22-af40-4112-a47a-4791f61a98e1\" /\u003e\n\n\nx3dctl is a lightweight command-line utility for controlling AMD X3D CPU operating modes on Linux systems.\n\nIt provides a safe, deterministic interface for:\n\n- Switching global X3D operating modes\n- Applying CCD-aware CPU affinity policies to applications\n- Steering GPU IRQ affinity based on selected mode\n\nx3dctl does not run a daemon and performs no background polling.  \nAll behavior is explicit and command-driven, with no background overhead.\n\n---\n\n## Features\n\n## Mode Control (System-Level)\n\n## Toggle AMD X3D CPU operating modes\n```bash\nx3dctl toggle\n``` \n\n## Explicit cache and frequency mode switching\n```bash\nx3dctl gaming\nx3dctl performance\n```\n\n## Deterministic GPU IRQ Steering\n\n - In gaming mode, GPU IRQs are steered to the frequency CCD.\n - In performance mode, GPU IRQs are restored to the full CPU mask.\n - Unrestricted profile in x3dctl.conf inherits current global steering policy.\n - IRQ steering can be disabled for testing:   \n   ```bash\n   x3dctl --no-irq gaming\n   ```\n\n## Application Launch With CCD-Aware Affinity:\n```bash\nx3dctl gaming steam\n```\n\n## When launching an application:\n\n1. The global X3D mode is set.\n2. CPU topology is detected (cache CCD vs frequency CCD).\n3. The launching process is pinned to the appropriate CCD.\n4. The application is executed.\n5. All child processes inherit the assigned CPU affinity.\n\n## Alternatively:\n```bash\nx3dctl run steam\n```\n\n- \u003crun\u003e applies the configured profile without changing global mode.\n- If no configuration entry exists, the default profile is \u003cgaming\u003e.\n\n## Verbose and Quiet Modes\n```bash\nx3dctl -q run \u003ccommand\u003e\nx3dctl -v gaming \u003ccommand\u003e\n```\n    \n## Documentation\n```bash\nman x3dctl\n```\n\n---\n\n## Local Build and Install\n```bash\nmake\nsudo make install\nsudo make uninstall\n```\n  \n### Install:\n\n- Installs binaries to `/usr/local/bin`.\n- Installs a restricted sudoers rule for x3dctl-helper `etc/sudoers.d`.\n- Installs a default `/etc/x3dctl.conf` if one does not already exist.\n- Installs man page to `/usr/local/share/man/man1`.\n\n### Uninstall \n- Program will clean itself from your system.\n- Remove binaries at `usr/local/bin`.\n- Remove sudoers rule for helper.\n- Program does not remove config at `/etc/x3dctl.conf` per UNIX tradition\n\n## AUR(helper):\n```bash\nhelper -S x3dctl\n```\n### This will:\n\nBuild the package\nInstall binaries to `/usr/bin`.\nInstall the man page.\nInstall the sudoers policy for x3dctl-helper.\nInstall `/etc/x3dctl.conf` (if not already present).\n\n## AUR(manual):\n```bash\ngit clone https://aur.archlinux.org/x3dctl.git\ncd x3dctl\nmakepkg -si\n```\n\n## Uninstalling(AUR):\n```bash\nsudo pacman -R x3dctl\n```\n\n### This removes:\n\n`/usr/bin/x3dctl`\n`/usr/bin/x3dctl-helper`\nMan page\nSudoers policy file\nThe configuration file will be preserved.\n\n---\n\n\n| Command     | Description                                               |\n| ----------- | --------------------------------------------------------- |\n| gaming      | Switch to cache-priority mode and steer GPU IRQs          |\n| performance | Switch to frequency-priority mode and restore IRQ routing |\n| toggle      | Switch between current modes                              |\n| status      | Display current X3D operating mode                        |\n| run         | Launch application using policy from `/etc/x3dctl.conf`   |\n\n---\n\n\n## Profile Model\n\n- Applications are mapped in:\n  `/etc/x3dctl.conf`\n\n- Format:\n  ```ini\n  application=profile\n  ```\n---\n\n- `status` displays:\n\n. Current X3D mode\n\n. GPU IRQ steering state\n\n. irqbalance service status\n\n\n### Note on irqbalance:\n\nThe irqbalance service distributes hardware interrupts across available CPUs.\nIt dynamically migrates IRQs to improve load balancing on multi-core systems.\n\nOn heterogeneous CPU designs (such as AMD X3D processors), automatic IRQ\nmigration may introduce cache-to-cache latency depending on workload and\nconfiguration.\n\nx3dctl applies deterministic GPU IRQ affinity when switching modes. If\nirqbalance is active, it may override these affinity settings.\n\nFor fully deterministic behavior, it is recommended to disable or appropriately\nconfigure irqbalance while using x3dctl.\n\nIRQ affinity changes made by x3dctl are runtime-only and do not persist across\nsystem reboots.\n\n\n### Supported profiles:\n\n\n| Profile      | CPU Affinity | Nice | Scheduler   | IO   |\n| ------------ | ------------ | ---- | ----------- | ---- |\n| gaming       | cache CCD    | -5   | SCHED_OTHER | BE/0 |\n| unrestricted | none         | -1   | SCHED_OTHER | BE/0 |\n| frequency    | freq CCD     | 0    | SCHED_OTHER | BE/0 |\n| workstation  | freq CCD     | 5    | SCHED_BATCH | BE/4 |\n\ngaming → aggressive foreground\nunrestricted → mild bias\nfrequency → neutral\nworkstation → background throughput\n\nThe unrestricted profile does not modify CPU affinity, \nallowing execution across all cores, while applying a slight priority bias.\n(some games may run better on this mode depending on workload and system usage)\n\nProfiles are enforced inside the privileged helper, \nand cannot be defined dynamically or during runtime.\nThe application key must match the executable basename. \nDirectory paths are ignored.\n\n---\n\n\n## Design Goals\n\n- Deterministic behavior\n- No background daemon\n- No polling or PID chasing\n- Mode defines system posture\n- Clear separation between system policy and process policy\n- Minimal privileged attack surface\n- Transparent configuration\n\n---\n\n\n## Requirements\n\n- Linux kernel with AMD X3D sysfs interface support\n- sudo configured for helper execution\n- GCC for building helper binary\n- Make\n\n---  \n\n\n## Stability Notice\n\n- x3dctl is currently in the 1.x release series.\n- Behavior should not change between releases.\n- CLI semantics will not evolve.\n- Backwards compatibility is guaranteed.\n- Consult Mid-long term goals for the project in the roadmap for more details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgrandbirdlizard%2Fx3dctl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgrandbirdlizard%2Fx3dctl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgrandbirdlizard%2Fx3dctl/lists"}