Biblioteca estática USB Mass Storage Class Host + Filesystem Mounter para homebrew de Nintendo Switch.
Principales características
-
Supports USB Mass Storage (UMS) devices that implement at least one USB interface descriptor with the following properties:
- bInterfaceClass: 0x08 (USB Mass Storage Class).
- bInterfaceSubClass: 0x06 (SCSI Transparent Command Set SubClass).
- bInterfaceProtocol: 0x50 (Bulk-Only Transport [BOT] Protocol).
-
Bulk-Only Transport (BOT) driver written from scratch, which implements the most common SCSI Primary Command Set (SPC) commands as well as BOT class-specific requests.
-
Supported SPC commands:
- TEST UNIT READY (0x00).
- REQUEST SENSE (0x03).
- INQUIRY (0x12).
- MODE SENSE (6) (0x1A).
- START STOP UNIT (0x1B).
- PREVENT ALLOW MEDIUM REMOVAL (0x1E).
- READ CAPACITY (10) (0x25).
- READ (10) (0x28).
- WRITE (10) (0x2A).
- MODE SENSE (10) (0x5A).
- READ (16) (0x88).
- WRITE (16) (0x8A).
- SERVICE ACTION IN (0x9E).
-
Supported SERVICE ACTION IN actions:
- READ CAPACITY (16) (0x10).
-
Supported BOT class-specific requests:
- Get Max LUN (0xFE).
- Bulk-Only Mass Storage Reset (0xFF).
-
Supported SPC commands:
- Supports UMS devices with long logical block addresses (64-bit LBAs) and variable logical block sizes (512 - 4096 bytes).
-
Background thread that takes care of starting all available logical units from each newly connected UMS device, as well as mounting the available filesystems from each one whenever possible.
-
Supported partitioning schemes:
- Super Floppy Drive (SFD) (Volume Boot Record @ LBA 0).
- Master Boot Record (MBR).
- Extended Boot Record (EBR).
- GUID Partition Table (GPT) + protective MBR.
-
Supported filesystems:
- FAT12 (via FatFs).
- FAT16 (via FatFs).
- FAT32 (via FatFs).
- exFAT (via FatFs).
- NTFS (via NTFS-3G).
- Completely possible to add support for additional filesystems, as long as their libraries are ported over to Switch.
-
Uses devoptab virtual device interface to provide a way to use standard I/O calls from libc (e.g.
fopen()
,opendir()
, etc.) on mounted filesystems from the available logical units.
-
Supported partitioning schemes:
-
Easy to use library interface:
- Provides an autoclear user event that is signaled each time a status change is detected by the background thread (new device mounted, device removed).
- Painless listing of mounted partitions using a simple struct that provides the devoptab device name, as well as other interesting information (filesystem index, filesystem type, write protection, raw logical unit capacity, etc.).
- Provides a way to safely unmount UMS devices at runtime.
-
Supports the
usbfs
service from SX OS.
Limitations
-
Bulk-Only Transport (BOT) driver:
- Up to 32 different USB Mass Storage Class interfaces can be used at the same time. Increasing this limit isn't harmful, but makes the library take up additional heap memory.
- Only a single SCSI operation can be performed at any given time per UMS device, regardless of their number of logical units. This is an official limitation of the BOT protocol. Mutexes are used to avoid multiple SCSI operations from taking place at the same time on the same UMS device.
-
Filesystem libraries:
-
FatFs:
- Up to 64 FAT volumes can be mounted at the same time across all available UMS devices. Original limit was 10, but FatFs was slightly modified to allow for more volumes to be mounted simultaneously.
-
NTFS-3G:
- Crypto operations aren't supported.
- Security contexts are always ignored.
- Only partial journaling is supported, so unexpected crashes or power loss can leave the a mounted NTFS volume in an inconsistent state. In cases where there has been heavy activity prior to the crash or power loss, it is recommended to plug the UMS device into a Windows PC and let it replay the journal properly before remounting with NTFS-3G, in order to prevent possible data loss and/or corruption.
- Symbolic links are transparent. This means that when a symbolic link in encountered, its hard link will be used instead.
-
FatFs:
-
Stack and/or heap memory consumption:
- This library is not suitable for custom sysmodules and/or service MITM projects. It allocates a 8 MiB buffer per each UMS device, which is used for command and data transfers. It also relies heavily on libnx features, which are not always compatible with sysmodule/MITM program contexts.
-
Switch-specific FS features:
- Concatenation files aren't supported.
-
usbfs
service from SX OS:- Only a single FAT volume from a single drive can be mounted.
- Relative paths aren't supported.
-
chdir()
,rename()
,dirreset()
andutimes()
aren't supported. - There are probably other limitations we don't even know about, due to the closed-source nature of this CFW.
Créditos
- DarkMatterCore: UMS device LUN/FS management, Bulk-Only Transport (BOT) driver, library interface.
- XorTroll: FS mounting system, devoptab device (un)registration, example test application.
- Rhys Koedijk: NTFS support.
- Lots of SPC/BOT docs across the Internet - these have been referenced in multiple files from the codebase.
Agradecimientos
- ChaN, for the FatFs module.
- Tuxera and NTFS-3G contributors, for the NTFS-3G library.
- Switchbrew and libnx contributors. Code from libnx was used for devoptab device management and path handling.
- blawar, for providing the updated usbfs SX OS service calls.
- Whovian9369. I literally would have dropped Switch homebrew development altogether some months ago, if not for you. Thanks, mate.
- ITotalJustice, for testing the partition table parsing algorithm.
- FennecTECH, for breaking stuff on a regular basis.
- All the Alpha Testers and Super Users from the nxdumptool Discord server, for being a constant source of ideas (and memes).
- And last but not least, my girlfriend, for always being by my side and motivating me to keep working on all my projects. I love you.
Creado por DarkMatterCore.
Que novedades incluye la versión 0.2.9
Released
-
lib:
- Implementa un sistema de población basado en callbacks, que puede utilizarse como alternativa al sistema basado en eventos disponible hasta ahora. Para más información, por favor lea la sección Cómo usar del README.
- Añade una reimplementación de usbHsEpPostBuffer() de libnx, llamada usbHsFsRequestEndpointDataXfer(), que llama a usbHsEpPostBufferAsync() con un valor de tiempo de espera codificado de 10 segundos (usando la definición USB_POSTBUFFER_TIMEOUT).
- Mejoras en la calidad de vida del gestor de registro de puertos de nxdumptool.
- Códigos de resultado de registro en notación hexadecimal sin relleno.
- Reorganizado el enum UsbHsFsMountFlags.
- Las cadenas SCSI INQUIRY ahora tienen prevalencia sobre las cadenas de descriptor de dispositivo USB, lo que afecta a las cadenas manufacturer, product_name y serial_number de los elementos UsbHsFsDevice.
- Se ha añadido la macro LIB_ASSERT y se han actualizado todas las aserciones estáticas de la base de código para utilizarla.
- Utilizar la macro NX_IGNORE_ARG donde sea necesario en toda la base de código.
-
Controlador SCSI:
- Reorganizar structs y enums.
- Añadir comentarios/referencias que faltan.
- Añadir ScsiInquiryVitalProductDataPageCode enum y reelaborar usbHsFsScsiSendInquiryCommand() para hacer posible solicitar páginas de Datos Vitales de Producto desde LUNs adjuntos.
- Actualización de la estructura ScsiInquiryStandardData para recuperar también los datos de número de serie de los LUN adjuntos.
- Añadir estructura ScsiInquiryUnitSerialNumberPageHeader.
- Actualizar usbHsFsScsiStartDriveLogicalUnit() para que lea la información del número de serie de la página VPD del número de serie de la unidad. Vuelve al número de serie devuelto por el comando estándar SCSI Inquiry si no está disponible.
- Revisión de usbHsFsScsiTransferCommand() para que maneje mejor tanto los CSWs inesperados como los valores de residuos de datos CSW.
- fs-libs: eliminar todos los scripts de compilación para NTFS-3G y lwext4, así como el Makefile fs-libs. Por favor, utilice los paquetes devkitPro pacman switch-ntfs-3g y switch-lwext4 ya disponibles. La sección Cómo instalar del README ha sido actualizada para reflejar este cambio.
- fat: las llamadas a ftruncate() en sistemas de archivos FAT ahora restauran la posición actual del archivo después del truncamiento.