🚀 B.R.O.S.Switcher - Professional GPU Hot-Swap for Linux

Binding & Releasing Orchestrator Script Switcher

⚠️ WARNING - EXPERT LEVEL TOOL

🚨 THIS SCRIPT CAN BREAK YOUR SYSTEM 🚨

If you don't understand VFIO, IOMMU, PCI bind/unbind, STOP IMMEDIATELY.
This tool is designed for systems ALREADY CONFIGURED for GPU passthrough on Linux.

REAL RISKS:

• Permanent black screen requiring forced reboot
• Crashed graphical session
• Inaccessible GPU requiring technical intervention
• Data loss from forced reboots

MANDATORY PREREQUISITES:

• IOMMU enabled and functional
• iGPU configured and tested for display
• VFIO already configured and tested
• Complete system backup
• Advanced Linux administration knowledge

You have been warned. 💥

⚠️ ALWAYS TEST ON A TEST MACHINE FIRST ⚠️

---

🎬 In a world where enthusiasts want everything: play Steam games,
train AI models, run powerful VMs and maintain a stable OS...
One question arises:
What if I could hot-swap my GPU like a pro?

Welcome to B.R.O.S.Switcher.
A professional tool designed for VERY advanced users who juggle between Linux host and Windows VMs,
without reboots, without pain, and with style.

---

🚀 Features

• 🔁 Hot-release GPU for VM passthrough (bind to vfio-pci)
• 🔄 Hot-reclaim GPU for host (bind to nvidia)
• 🧪 Real-time status display of current driver
• 🔒 Smart binding prevents errors if GPU already bound to VFIO or NVIDIA
• 🎛️ Interactive console menu for easy operation
• ✅ Automatic configuration validation
• 🛡️ Safety checks before dangerous operations

---

⚙️ MANDATORY System Prerequisites

🔥 CRITICAL - You MUST already have:

• IOMMU enabled in BIOS AND kernel
• VFIO working (vfio-pci, etc.) and TESTED
• Stable graphical session on iGPU (not NVIDIA GPU)
• Display manager: lightdm, gdm or sddm
• NVIDIA modules installed: nvidia-driver on Debian or equivalent
• Complete system backup
• Test machine for validation before production

🚨 IF YOU DON'T HAVE ALL OF THESE, DON'T USE THIS SCRIPT! 🚨

---

🔧 MANDATORY Script Configuration

⚠️ CRITICAL STEP ⚠️

You MUST customize these values in the script before any use:

GPU_BUSID="0000:01:00.0"
AUDIO_BUSID="0000:01:00.1"
GPU_VENDOR="10de"
GPU_DEVICE="2484"
AUDIO_VENDOR="10de"
AUDIO_DEVICE="228b"

🔍 How to find these values:

BusID:

lspci | grep -i nvidia

Example output:

01:00.0 VGA compatible controller: NVIDIA ...
01:00.1 Audio device: NVIDIA ...

➡️ Format BusID as follows:

GPU_BUSID="0000:01:00.0"
AUDIO_BUSID="0000:01:00.1"

Vendor / Device ID:

lspci -nn | grep -i nvidia

Example output:

01:00.0 VGA compatible controller [0300]: NVIDIA [10de:2484]
01:00.1 Audio device [0403]: NVIDIA [10de:228b]

➡️ Which gives:

GPU_VENDOR="10de"
GPU_DEVICE="2484"
AUDIO_VENDOR="10de"
AUDIO_DEVICE="228b"

🔥 WRONG CONFIG = BROKEN SYSTEM 🔥

---

📦 Installation (Optional)

⚠️ TEST ON A TEST MACHINE FIRST ⚠️

You can automate the setup with the bros-setup.sh script:

chmod +x bros-setup.sh
./bros-setup.sh

It will install useful dependencies (pciutils, lsof, etc.) and configure your system for optimal GPU switching.

---

🖥️ Usage

⚠️ BACKUP YOUR WORK FIRST ⚠️

./bros-vfio.sh

Follow the interactive menu:

=== B.R.O.S.Switcher VFIO Menu ===
1) Release GPU for VM (bind vfio-pci)
2) Reclaim GPU for host (bind nvidia)
3) Show GPU driver status
q) Quit

🚨 IN CASE OF BLACK SCREEN: Ctrl+Alt+F2 to access emergency TTY 🚨

---

🧯 EMERGENCY Troubleshooting

🚨 TOTAL BLACK SCREEN 🚨

1. Ctrl+Alt+F2 to switch to TTY
2. Login with your credentials
3. Execute: sudo systemctl restart lightdm (or gdm/sddm)
4. If it doesn't work: sudo reboot

🔥 GPU STUCK 🔥

# Force return to NVIDIA driver
sudo modprobe nvidia
echo "0000:01:00.0" | sudo tee /sys/bus/pci/drivers/vfio-pci/unbind
echo "0000:01:00.0" | sudo tee /sys/bus/pci/drivers/nvidia/bind
sudo systemctl restart lightdm

Quick diagnostics

# GPU status
lspci -nnk -s 0000:01:00.0

# GPU processes
lsof | grep nvidia

# Check IOMMU
dmesg | grep -i iommu

Common errors

"IOMMU not enabled"?

1. Enable IOMMU in BIOS (Intel VT-d / AMD-Vi)
2. Add intel_iommu=on or amd_iommu=on to kernel parameters
3. Reboot

"GPU not found"?
Check your BusID with:

lspci | grep -i nvidia
lspci -nn | grep -i nvidia

"Bind failed"?
GPU might be used by a process:

sudo fuser -v /dev/nvidia*
sudo pkill -f nvidia

---

⚠️ Known Limitations

• Tested primarily on Debian 12 (Bookworm) - other distros may need adaptation
• Requires functional iGPU for display output
• GPU processes must be closed before switching
• Some proprietary drivers may resist unbinding
• No AMD GPU support yet (contributions welcome)
• May require multiple attempts depending on system load
• Display manager restart required for some operations

---

🆘 Emergency Support

If your system becomes unusable:

1. Boot in rescue/recovery mode
2. Disable the script: rm /usr/local/bin/bros-vfio.sh
3. Remove X11 config: sudo rm /etc/X11/xorg.conf.d/20-intel.conf
4. Force NVIDIA driver: sudo modprobe nvidia && sudo systemctl restart lightdm

---

🤝 Contributing

Contributions are welcome! Here's how to help:

1. Issues: Bug reports, feature requests
2. Pull Requests: Fixes, improvements, support for other distros
3. Documentation: Guides for other GPUs (AMD, Intel Arc)
4. Testing: Validation on different configurations

🗺️ Roadmap

• AMD GPU support
• GTK/Qt graphical interface
• Automatic BusID configuration
• Fedora/Arch/Ubuntu support
• Automatic recovery mode
• Detailed operation logging
• Multi-GPU configurations
• Container integration (Docker/Podman)

---

🏆 Success Stories

Successfully tested configurations:

• Debian 12 + RTX 3080 + Intel iGPU
• Windows 11 VM + Ubuntu host
• Gaming VM + AI/ML on host
• Dual-boot replacement setup

Share your config! Open an issue to document your success and help others.

---

---

B.R.O.S.Switcher - Professional GPU hot-swap for Linux power users 🚀

🎓 Credits & Community

Created by a passionate developer focused on VM technology, gaming, and advanced graphics manipulation on Linux.

Want to contribute, share your configurations, or add new features?
Open an issue, submit a PR, or reach out directly. We're building a professional community here.

💖 Support the Project

B.R.O.S.Switcher is developed voluntarily in my free time. If this tool helps with your VFIO/gaming projects, you can support its development:

☕ Buy me a coffee

Your support helps:

• 🧪 Buy hardware for testing (AMD GPUs, different configs)
• ⏰ Dedicate more time to development
• 🚀 Add new features and improvements
• 📚 Improve documentation and guides
• 🌐 Maintain project infrastructure

Thank you to everyone supporting the project! 🙏

⚠️ Use this script at your own risk. Authors are not responsible for any damage.

---

🚀 License

MIT License
Do what you want with it. Just manage your VFIO responsibly.
You're playing with the kernel, not with toys.

🚨 LEGAL DISCLAIMER 🚨
This software is provided "as is", without warranty of any kind.
Users assume all risks associated with its use.

---

Made with ❤️ (and lots of ☕) by B.R.O.S.Switcher Team

Version 2.0.0 - Professional Release
Binding & Releasing Orchestrator Script Switcher