RealtekCardReader 0.9.6

Realtek Card Reader Driver for macOS​

Unleash the full potential of your SDXC UHS-I cards

Introduction​

An unofficial macOS kernel extension for Realtek PCIe/USB-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

Notes:​

• RealtekCardReaderFriend is required to enable this feature as of v0.9.5.

Limitations​

• MMC cards are not supported
• SD Express cards are not supported

Current Status​

• Last Updated: Dec 27, 2021
• Reference: Linux Kernel 5.11
• Driver Status:Pre-1.0 Beta (v0.9.6)
  • USB-based RTS5129, 5139 and 5179 card readers are now supported and should be working properly.
  • I/O performance and the overall driver stability are of the most concern at this moment.
• Known Issues: Link

Supported Systems​

• macOS Monterey
• macOS Big Sur
• macOS Catalina
• macOS Mojave

Notes:​

• Other systems are not tested yet.

Supported Devices​

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.
• Other Realtek USB card readers (e.g., RTS5138) conform to the USB Attached SCSI (UAS) protocol and therefore may be supported by the native driver.

Downloads​

• Stable Releases (Recommended)
• Nightly Builds (Artifacts under each workflow run)

Boot Arguments​

Please refer to this dedicated page to see all boot arguments.

Questions, Issues and Documentation​

Users​

Please read FAQs and Known Issues 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.
Please make sure that your kernel log is complete. Issues without any details will be closed and left unanswered.

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.

Discussion​

A discussion thread is available on InsanelyMac.

Support​

Writing a driver from scratch is hard and time consuming.
If you would like to support my work, please consider a donation.

References​

• SD Physical Layer Simplified Specification

Changelog v0.9.6​

v0.9.6 Beta​

Short Story:​

• The driver is pretty stable now.
• USB-based card readers should be working properly.
• PCIe-based card readers should work even better than before.

Long Story:​

• Added support for RTS5260.
• Fixed an issue that the driver is not loaded if the USB card reader is not configured and thus does not expose its host interface.
• Addressed an issue that the driver fails to find the bulk endpoints of the USB card reader.
• Resolved an issue that the driver fails to initialize the USB card reader properly.
• Resolved an issue that the driver cannot detect whether the user has inserted/removed the card to/from the USB card reader.
• Added an option to delay the initialization of the card found during the system boots.
• Corrected the address of the USB-based card reader register that controls the SSC depth.
• Fixed an issue that System Information does not list the USB-based card reader properly.
• Resolved an issue that commands are timed out after the driver switches the bus clock of the card reader.
• Resolved an issue that USB-based card readers fail to initialize UHS-I cards properly.
• Pause the polling thread of the USB-based card reader when the host driver is processing a card event.
• Skip setting the bus power mode if the card reader is already operating at the requested mode.
• Resolved an issue that the card clock is incorrectly toggled thus fails to switch to 1.8V after the host device sends the CMD11.
• Revise the design of the host driver stack to make all data structures that are related to host requests device-independent.
• Optimize the host driver stack to avoid unnecessary bounce buffer allocations and data copies in card reader controllers.
• Minimize the amount of time the transfer buffer is ready for DMA to reduce the pressure in the low 4GB of physical memory.
• Addressed an issue that CMD17 and CMD24 fail to transfer any data from/to the card with USB-based card readers.
• Switched the mode from AutoRead2 to AutoRead3 when the host device services an inbound DMA transfer request.
• Resolved an issue that bulk pipes halted after the driver issued a DMA transfer request to USB-based card readers.
• Revise the implementation of processing block requests to fix the regression caused by the new driver stack.
• Fixed an issue that the maximum segment size for DMA transfers is incorrectly defined for PCIe-based card readers.
• Fixed a race condition introduced by the polling thread that corrupts the response sent by USB-based card readers.
• Addressed an issue that UHS-I cards running in SDR50/104 mode are not tuned thus send invalid responses to USB-based card readers.
• Parse the SD status register value so that System Information can show the speed class of the card.
• System Information now shows the information of cards inserted into USB-based card readers.

Credits​

• Acidanthera for MacKernelSDK
• Realtek for the Linux RTSX PCI/USB driver
• FireWolf for developing the card reader driver for macOS

Acknowledgments​

I would like to acknowledge the following beta testers without whom support for USB-based card readers won't be available.

• m0d16l14n1 for testing unstable, experimental builds to capture and fix a large number of issues.
• Sherlocks for testing early builds to debug the timeout issues.
• whatnameisit for testing early builds to debug the hardware initialization issues.
• gnpaone for providing multiple comprehensive bug reports.

License​

This project is licensed under BSD-3-Clause.
Copyright (C) 2021 FireWolf @ FireWolf Pl. All Rights Reserved.