Initial Commit

.gitignore

@@ -0,0 +1,32 @@
+# Xcode
+#
+# gitignore contributors: remember to update Global/Xcode.gitignore, Objective-C.gitignore & Swift.gitignore
+
+## User settings
+xcuserdata/
+
+## compatibility with Xcode 8 and earlier (ignoring not required starting Xcode 9)
+*.xcscmblueprint
+*.xccheckout
+
+## compatibility with Xcode 3 and earlier (ignoring not required starting Xcode 4)
+build/
+DerivedData/
+*.moved-aside
+*.pbxuser
+!default.pbxuser
+*.mode1v3
+!default.mode1v3
+*.mode2v3
+!default.mode2v3
+*.perspectivev3
+!default.perspectivev3
+
+## Gcc Patch
+/*.gcno
+
+.idea/
+.DS_Store
+._DS_Store
+__private/
+MacKernelSDK/

Docs/FAQ.md

@@ -0,0 +1,73 @@
+#  Frequently Asked Questions
+
+**Last Updated:** Jun 18, 2021
+
+## Device Support
+
+### How do I know if my card reader is supported?
+
+You can find a list of supported card readers at the [front page](../README.md).  
+If the support status says `Yes`, your card reader is supported by this driver.
+
+### What if my card reader is not listed in the table?
+
+It means that your card reader is not supported by the original Linux driver module `rtsx_pci`.  
+Since this driver is based on that module, your card reader is not and probably will not be supported by this driver.
+
+### My card reader is listed in the table but is not supported yet, when are you going to implement it?
+
+Unfortunately, I don't have an ETA at this moment.  
+However, it should be relatively easy to add support for other card readers, because the base controller class contains most of the common code and a rich set of APIs to manipulate the registers.  
+Please note that I am not paid to write this driver and I have other work to do, so I cannot dedicate all my time to this project.   
+If you would like to support me and this project, please consider a donation.
+
+### What is the roadmap of this project?
+
+Milestones:
+- 1: Base controller implementation for all supported Realtek PCIe-based card readers.
+- 2: Chip-independent Realtek SD host device implementation.
+- 3: Initial SD host driver stack implementation for macOS.
+- 4: I/O performance and stability of the driver. (<-- Right Now)
+- 5: Power management implementation.
+- 6: Support more card readers.
+
+## Installation
+
+### How do I install this driver?
+
+If you are using OpenCore, refer to the guide provided by [Dortania](https://dortania.github.io/getting-started/).  
+If you are using Clover, place the driver under the `kexts/<OS Version>` folder.  
+
+### How do I know if the driver is loaded?
+
+Run the following command in your terminal.  
+
+```(sh)
+kextstat | grep rtsx
+```
+
+If you see `science.firewolf.rtsx` in your terminal, then the driver is loaded.  
+As a bonus, you should be able to see your card reader recognized as a native one in **System Information**.
+
+### How do I dump the log produced by the driver?
+
+Make sure that you are using the DEBUG version of the driver and have added the boot argument `msgbuf=10485760`. (Note that there is an extra zero at the end of `1048576`.)
+
+Run the following command in your terminal.
+
+```(sh)
+sudo dmesg | grep RTSX > ~/Desktop/rtsx.log
+```
+
+You can now find the log on your `Desktop` folder.  
+If the log file is empty, please install the [DebugEnhancer](https://github.com/acidanthera/DebugEnhancer) and try again.
+
+### What is the difference between the DEBUG and the RELEASE version?
+
+The DEBUG version produces a massive amount of log that records accesses to some key registers and thus slows down the boot process and I/O transactions.  
+However, you are recommended to use the DEBUG version at first to ensure that the driver is working properly with your hardware.  
+You should always attach the log produced by the DEBUG version when you are asking for help on the forum and/or filing an issue on Github.  
+Once everything is fine, you may switch to the RELEASE version.
+
+The RELEASE version produces log only when there is an error and thus may not be helpful when you plan to investigate an issue.  
+However, you are recommended to use the RELEASE version after you ensure that the driver works fine with your hardware to enjoy the best performance.

LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2021, FireWolf @ FireWolf Pl.
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

README.md

@@ -0,0 +1,86 @@
+#  Realtek PCIe Card Reader Driver for macOS
+Unleash the full potential of your SDXC UHS-I cards
+
+## Introduction
+
+An unofficial macOS kernel extension for Realtek PCIe-based SD card readers.  
+It uses the Linux driver as a reference implementation but is written from scratch and carefully designed for macOS to deliver the best performance.
+
+## Features
+- No compatibility layer
+- Supports SDSC/HC/XC cards
+- Supports the default and the high speed modes
+- Supports UHS-I SDR12/25/50/104 and DDR50 modes
+- Recognizable as a built-in card reader device
+- Device-independent SD host driver stack
+
+## Limitations
+- MMC cards are not supported
+- SD Express cards are not supported
+
+## Current Status
+- **Last Updated:** Jun 18, 2021
+- **Reference:** [Linux Kernel 5.11](https://cdn.kernel.org/pub/linux/kernel/v5.x/linux-5.11.tar.xz)
+- **Driver Status:** Pre-1.0 Beta
+    - Power management is not implemented.
+    - I/O performance and the overall driver stability are of the most concern at this moment.
+
+## Supported Systems
+- macOS Big Sur  
+- macOS Catalina  
+
+#### Notes:
+- Other systems are not tested yet.
+
+## Supported Devices
+| Series |   PCI ID   |               Name               | Supported |
+|:------:|:----------:|:--------------------------------:|:---------:|
+|  5209  | 0x10EC5209 |  RTS5209 PCI Express Card Reader |  Not Yet  |
+|  5227  | 0x10EC5227 |  RTS5227 PCI Express Card Reader |  Not Yet  |
+|  5227  | 0x10EC522A |  RTS522A PCI Express Card Reader |  Not Yet  |
+|  5228  | 0x10EC5228 |  RTS5228 PCI Express Card Reader |  Not Yet  |
+|  5229  | 0x10EC5229 |  RTS5229 PCI Express Card Reader |  Not Yet  |
+|  5249  | 0x10EC5249 |  RTS5249 PCI Express Card Reader |    Yes    |
+|  5249  | 0x10EC524A |  RTS524A PCI Express Card Reader |    Yes    |
+|  5249  | 0x10EC525A |  RTS525A PCI Express Card Reader |    Yes    |
+|  5260  | 0x10EC5260 |  RTS5260 PCI Express Card Reader |  Not Yet  |
+|  5261  | 0x10EC5261 |  RTS5261 PCI Express Card Reader |  Not Yet  |
+|  8411  | 0x10EC5286 |  RTL8402 PCI Express Card Reader |  Not Yet  |
+|  8411  | 0x10EC5287 | RTL8411B PCI Express Card Reader |  Not Yet  |
+|  8411  | 0x10EC5289 |  RTL8411 PCI Express Card Reader |  Not Yet  |
+
+#### Notes:
+- By design, all listed devices are supported, and devices that have the same series share most of the controller code.
+- RTS525A has the highest priority than other chips, because that's the only chip available for me to test the driver.
+- If a device's support status is "Not Yet", its controller is not implemented yet.
+
+## Questions, Issues and Documentation
+
+### Users
+Please read [FAQs](Docs/FAQ.md) carefully before asking any questions.  
+Please use the issue template before submitting any code-level issues.
+Please clearly indicate your chip model, device ID and revision number and attach the kernel log in your issue.
+
+### Developers
+You are welcome to submit pull requests to improve this driver.  
+Please read the code documentation to understand how each class/function is related to the Linux driver code and how to add support for other listed devices.  
+A detailed port note will be available later.
+
+## Support
+Writing a driver from scratch is hard and time consuming.  
+If you would like to support my work, please consider a donation.  
+
+[![Donate](https://img.shields.io/badge/Donate-PayPal-green.svg)](https://www.paypal.com/donate/?business=M6AHXMUVSZQTS&no_recurring=0&item_name=Support+Realtek+PCIe+card+deader+driver+for+macOS&currency_code=USD)
+
+
+## References
+- [SD Physical Layer Simplified Specification](https://www.sdcard.org/downloads/pls/)
+
+## Credits
+- [Acidanthera](https://github.com/acidanthera) for [MacKernelSDK](https://github.com/acidanthera/MacKernelSDK)
+- [Realtek](https://www.realtek.com/) for the Linux [RTSX PCI](https://github.com/torvalds/linux/tree/master/drivers/misc/cardreader) driver
+- [FireWolf](https://github.com/0xFireWolf) for developing the card reader driver for macOS
+
+## License
+This project is licensed under BSD-3-Clause.  
+Copyright (C) 2021 FireWolf @ FireWolf Pl. All Rights Reserved.