-
Notifications
You must be signed in to change notification settings - Fork 14
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Update README + minor script adjustments
- Loading branch information
1 parent
9aad62e
commit 4c775f5
Showing
2 changed files
with
93 additions
and
94 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,106 +1,102 @@ | ||
|  | ||
| #  | ||
|
|
||
|   [![paypal][image-1]][1] | ||
|   [](https://www.paypal.com/cgi-bin/webscr?cmd=_donations&[email protected]&lc=US&item_name=Development%20of%20PurgeNVDA&no_note=0¤cy_code=USD&bn=PP-DonationsBF:btn_donate_SM.gif:NonHostedGuest) | ||
| # PurgeNVDA | ||
| Allows macs with **NVIDIA GPUs** to optimally use both **AMD** and **NVIDIA** external graphics. | ||
|
|
||
| ## Requirements | ||
| This script requires the following specifications: | ||
| * Mac with integrated Intel GPU + discrete **NVIDIA** GPU | ||
| * **macOS 10.13.4** or later | ||
|
|
||
| For **eGPU support** please use along with [purge-wrangler.sh](https://github.com/mayankk2308/purge-wrangler/releases). | ||
|
|
||
| It is recommended that you have a backup of the system. | ||
|
|
||
| ## Usage | ||
| Please follow these steps: | ||
|
|
||
| ### Step 1 | ||
| Disable **system integrity protection** for macOS using **Terminal** in **Recovery**: | ||
| ```bash | ||
| $ csrutil disable | ||
| $ reboot | ||
| ``` | ||
|
|
||
| ### Step 2 | ||
| Boot back into macOS, then copy-paste the following into **Terminal**: | ||
| **purge-nvda.sh** is required for certain macs to configure the system further for working external GPU support, alongside [purge-wrangler.sh](https://github.com/mayankk2308/purge-wrangler). It may also serve useful for other use cases such as bad discrete GPU chipsets, etc., but is not tested or guaranteed. | ||
|
|
||
| ## Contents | ||
| A quick run-through of what's included in this document: | ||
| - [Pre-Requisites](https://github.com/mayankk2308/purge-nvda#pre-requisites) | ||
| - macOS requirements, pre-system configuration specifics, and more. | ||
| - [Installation](https://github.com/mayankk2308/purge-nvda#installation) | ||
| - Installing and running the script. | ||
| - [Script Options](https://github.com/mayankk2308/purge-nvda#script-options) | ||
| - Available capabilities and options in the script. | ||
| - [Recovery](https://github.com/mayankk2308/purge-nvda#recovery) | ||
| - Easy way to recover from an unbootable system using the script. | ||
| - [Post-Install](https://github.com/mayankk2308/purge-nvda#post-install) | ||
| - System configuration after script installation and some other things of note. | ||
| - [Troubleshooting](https://github.com/mayankk2308/purge-nvda#troubleshooting) | ||
| - Additional resources and guides for eGPUs. | ||
| - [Disclaimer](https://github.com/mayankk2308/purge-nvda#disclaimer) | ||
| - Please read the disclaimer before using this script. | ||
| - [License](https://github.com/mayankk2308/purge-nvda#license) | ||
| - By using this script, you consent to the license that the script comes bundled with. | ||
| - [Support](https://github.com/mayankk2308/purge-nvda#support) | ||
| - Support the developer if you'd like to. | ||
|
|
||
| ## Pre-Requisites | ||
| In case you are not up-to-date, please read [Apple](https://support.apple.com/en-us/HT208544)'s external GPU documentation first to see what is already supported on macOS. The following is a table that summarizes **system requirements** for using this script: | ||
|
|
||
| | Configuration | Requirement | Description | | ||
| | :-----------: | :---------: | :---------- | | ||
| | **macOS** | 10.13.4+ | Older versions of macOS require different patching mechanisms that this script does not include. Please check [eGPU.io](https://egpu.io) for more information. | | ||
| | **System Integrity Protection** | Disabled | By default, this prevents system modifications that the script would like to make, and hence must be disabled. SIP can be disabled as described in this [article](https://developer.apple.com/library/archive/documentation/Security/Conceptual/System_Integrity_Protection_Guide/ConfiguringSystemIntegrityProtection/ConfiguringSystemIntegrityProtection.html). | | ||
| | **Internal GPUs** | Intel + NVIDIA | Presence of **both** an integrated Intel GPU and discrete NVIDIA GPU is required, i.e., **iMacs are not supported**. Script may be run on iMacs for experimentation. | | ||
|
|
||
| ## Installation | ||
| **purge-nvda.sh** auto-manages itself and provides multiple installation and recovery options. Once the **pre-requisites** are satisfied, install the script by running the following in **Terminal**: | ||
| ```bash | ||
| curl -s "https://api.github.com/repos/mayankk2308/purge-nvda/releases/latest" | grep '"browser_download_url":' | sed -E 's/.*"([^"]+)".*/\1/' | xargs curl -L -s -0 > purge-nvda.sh && chmod +x purge-nvda.sh && ./purge-nvda.sh && rm purge-nvda.sh | ||
| ``` | ||
|
|
||
| Note that you may change to a different valid version in the above command. | ||
|
|
||
| Alternatively, download [purge-nvda.sh](https://github.com/mayankk2308/purge-nvda/releases). Then run the following in **Terminal**: | ||
| For future use, only the following will be required: | ||
| ```bash | ||
| $ cd Downloads | ||
| $ chmod +x purge-nvda.sh | ||
| $ ./purge-nvda.sh | ||
| purge-nvda | ||
| ``` | ||
|
|
||
| You will be prompted to enter your account password for **superuser permissions**. On first-time use, the script will auto-install itself as a binary into `/usr/local/bin/`. This enables much simpler future use. To use the script again, just type the following in **Terminal**: | ||
| ```bash | ||
| $ purge-nvda | ||
| ``` | ||
| In case the command above does not work, you can re-use the long installation command and fix the issue. | ||
|
|
||
| This is supported on **2.0.0** or later. Automatic updates are supported from **2.1.0** or later. | ||
| ### Some Notes | ||
| After using the script, sometimes you may observe that the system is unbootable. In such a case, boot into single user mode as advised in the [pre-requisites](https://github.com/mayankk2308/purge-nvda#pre-requisites) and **set mux to iGPU** to force the mux setting. This needs to be done because in some cases, the setting does not apply (after using option 1, 2, 4, or 5 while in macOS). | ||
|
|
||
| ## Options | ||
| ## Script Options | ||
| PurgeNVDA makes it super-easy to perform actions with an interactive menu, and is recommended for most users. Providing no arguments to the script defaults to the menu. | ||
|
|
||
|  | ||
|
|
||
| For advanced users that may sometimes prefer bypassing the menu, the script provides convenient arguments in an attempt to be as user-friendly as possible. | ||
|
|
||
| #### 1. Fix AMD eGPUs (`-fa|--fix-amd`) | ||
| Disables all NVIDIA GPUs to resolve AMD-NVIDIA framebuffer conflicts when an AMD eGPU is initialized on the system. | ||
|
|
||
| #### 2. Optimize NVIDIA eGPUs (`-on|--optimize-nv`) | ||
| Disables only the internal NVIDIA GPU to enable OpenCL/GL acceleration and high performance with NVIDIA eGPUs with a combination of NVRAM + NVDA kernel extension patches. | ||
|
|
||
| #### 3. Suppress NVIDIA GPUs (`-sn|--suppress-nv`) | ||
| Disables all NVIDIA GPUs at macOS-independent machine level - therefore affecting all macOS installations running on the machine. This patch does not modify any system files. | ||
|
|
||
| #### 4. Set Mux to iGPU (`-mi|--mux-igpu`) | ||
| Sets the system graphics multiplexer to the integrated Intel GPU, if available. This preference is after a system boots with its discrete GPU enabled (such that macOS may initialize its framebuffer), thus only lasts for one boot unless appropriate measures to curb dGPU activation are in place. | ||
|
|
||
| #### 5. Uninstall (`-u|--uninstall`) | ||
| Uninstalls any possible system modifications made by the script. | ||
|
|
||
| #### 6. System Status (`-s|--status`) | ||
| Shows the status of the currently installed patches on the system. | ||
|
|
||
| #### 7. Disable Hibernation (`-dh|--disable-hibernation`) | ||
| Disables hibernation mode and automatic power off as these settings may resolve wake-up failures with discrete graphics disabled. | ||
|
|
||
| #### 9. Restore Power Settings (`-rp|--restore-power`) | ||
| Restores the hibernation mode configurations to recommended settings. | ||
| | Argument | Menu | Description | | ||
| | :------: | :--: | :---------- | | ||
| | `-fa` or `--fix-amd` | AMD eGPUs | Disables the discrete NVIDIA GPU, sets the gmux to the Intel GPU, allowing any AMD framebuffers to render correctly. Any and all NVIDIA GPUs will be disabled. This patch affects all installations running on the machine and does not modify system files. | | ||
| | `-on` or `--optimize-nv` | NVIDIA eGPUs | Disables only the internal NVIDIA GPU and sets the gmux to Intel GPU to enable OpenCL/GL acceleration and high performance with NVIDIA eGPUs with a combination of NVRAM + NVDA kernel extension patches. | | ||
| | `-u` or `--uninstall` | Uninstall | Reverts and removes any system modifications made using the script. If unsuccessful, attempt using it in [Single User Mode](https://support.apple.com/en-us/HT201573) (Boot with **⌘ + S**). | | ||
| | `-sn` or `--suppress-nv` | Suppress NVIDIA GPUs | Disables all NVIDIA GPUs with fixed cold gmux - therefore affecting all macOS installations running on the machine. This patch does not modify any system files. | | ||
| | `-mi` or `--mux-igpu` | Set Mux to iGPU | Sets the system graphics multiplexer to the integrated Intel GPU, if available. This preference is after a system boots with its discrete GPU enabled (such that macOS may initialize its framebuffer), thus only lasts for one boot unless appropriate measures to curb dGPU activation are in place. | | ||
| | `-s` or `--status` | Status | Shows the currently installed patches on the system. Since the mux commands are consumed, mux status will show as inactive/disabled after the chip has been set. | | ||
| | `-dh` or `--disable-hibernation` | Disable Hibernation | Disables hibernation mode and automatic power off as these settings may resolve wake-up failures with discrete graphics disabled. | | ||
| | `-rp` or `--restore-power` | Restore Power Settings | Restores the hibernation mode configurations to factory settings. | | ||
| | `-rb` or `--reboot` | Reboot System | Prompts the user to reboot the system, and instantly does so if after user consent, useful for easy command-line reboots. | | ||
|
|
||
| ## Recovery | ||
| If you are unable to boot into macOS, boot while pressing **⌘ + S**, then enter the following commands: | ||
| ```bash | ||
| mount -uw / | ||
| purge-nvda -u | ||
| ``` | ||
| This will restore your system to a clean state as documented above. | ||
|
|
||
| #### 10. Reboot System (`-rb|--reboot`) | ||
| Reboots the system after requesting confirmation. | ||
| ## Post-Install | ||
| After installing the script, all settings as described in [pre-requisites](https://github.com/mayankk2308/purge-wrangler#pre-requisites) must persist. For instance, **system integrity protection** must remain disabled as long as the system is in the *patched* state. | ||
|
|
||
| ## Troubleshooting | ||
| If you are unable to boot into macOS, boot into Single User Mode (**CMD + S** on boot) and type in the following commands: | ||
| ```bash | ||
| $ mount -uw / | ||
| $ purge-nvda | ||
| ``` | ||
| Troubleshooting plays an important role in any kind of hack/patch. New OSes and hardware tend to bring with them new problems and challenges. The hardware chart aims to cover all variances of problems with eGPUs so far, but there can be some specific missed edge cases. The following is a list of additional resources rich in information: | ||
|
|
||
| Uninstall the script modifications and reboot. | ||
| | Resource | Description | | ||
| | :------: | :---------- | | ||
| | [eGPU.io Build Guides](https://egpu.io/build-guides/) | See builds for a variety of systems and eGPUs. If you don't find an exact match, look for similar builds. | | ||
| | [eGPU.io Troubleshooting Guide](https://egpu.io/forums/mac-setup/guide-troubleshooting-egpus-on-macos/) | Learn about some basics of eGPUs in macOS and find out what means what. This guide does not cover any Windows/Bootcamp-related efforts. | | ||
| | [eGPU.io Community](https://egpu.io/forums/) | The eGPU.io forums are a great place to post concerns and doubts about your setup. Be sure to search the forum before posting as there might be high chance your doubt has already been answered. | | ||
| | [eGPU Community on Reddit](https://www.reddit.com/r/eGPU/) | The reddit community is a wonderful place to request additional help for your new setup, and a good place to find fellow eGPU users. | | ||
|
|
||
| ## References | ||
| Due credit goes to the MacRumors members (esp. **@nsgr**) for the **NVRAM** settings that make this possible without requiring a separate **ArchLinux** installation to manually manage these values. | ||
| My username on both communities is [@mac_editor](https://egpu.io/forums/profile/mac_editor). Feel free to mention my username on eGPU.io posts - I get an email notifying me of the same. In any case, with thousands of members, the community is a welcoming place. Don't be shy! | ||
|
|
||
| ## Disclaimer | ||
| This script moves core system files associated with macOS. While any of the potential issues with its application are recoverable, please use this script at your discretion. I will not be liable for any damages to your operating system. | ||
|
|
||
| ## License | ||
| This project is available under the **MIT** license. See the license file for more information. | ||
| The bundled license allows commercial use and redistribution for any purposes. This software comes without any warranty or guaranteed support. By using the script, you **agree** to adhere to the **MIT** license. For more information, please see the [LICENSE](./LICENSE.md). | ||
|
|
||
| ## Donate | ||
| A *thank you* suffices, but for those kind souls who want to contribute: | ||
| ## Support | ||
| If you loved **purge-nvda.sh**, consider **starring** the repository or if you would like to, donate via **PayPal**: | ||
|
|
||
| [![paypal][image-1]][1] | ||
| [](https://www.paypal.com/cgi-bin/webscr?cmd=_donations&[email protected]&lc=US&item_name=Development%20of%20PurgeNVDA&no_note=0¤cy_code=USD&bn=PP-DonationsBF:btn_donate_SM.gif:NonHostedGuest) | ||
|
|
||
| [image-1]: https://www.paypalobjects.com/en_US/i/btn/btn_donate_SM.gif | ||
| [1]: https://www.paypal.com/cgi-bin/webscr?cmd=_donations&[email protected]&lc=US&item_name=mac_editor&no_note=0¤cy_code=USD&bn=PP-DonationsBF:btn_donate_SM.gif:NonHostedGuest | ||
| Thank you for using **purge-nvda.sh**. This project is currently maintained for any discovered bugs/errors. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters