Disponibile un nuovo aggiornamento per la libreria libusbhsfs, le app che faranno uso di questa nuova libreria potranno utilizzare dischi rigidi esterni, proprio come avviene in SX OS.
La classe di dispositivi di archiviazione di massa USB (nota anche come USB MSC o UMS ) è un insieme di protocolli di comunicazione, definita dalla USB Implementers Forum che rende un dispositivo USB accessibile a un dispositivo di elaborazione host e consente il trasferimento di file tra l’host e il dispositivo USB.
Per un host, il dispositivo USB funge da disco rigido esterno, il set di protocolli si interfaccia con una serie di dispositivi di archiviazione.
Caratteristiche principali
- Supporta dispositivi di archiviazione di massa USB che implementano almeno un descrittore di interfaccia USB con le seguenti proprietà:
bInterfaceClass: 0x08
(USB Mass Storage Class).bInterfaceSubClass: 0x06
(SCSI Transparent Command Set SubClass).- bInterfaceProtocol: 0x50 (Bulk-Only Transport [BOT] Protocol).
- Driver BOT (Bulk-Only Transport) scritto da zero, che implementa i più comuni comandi SPC (Primary Command Set) SCSI nonché richieste specifiche della classe BOT.
- Comandi SPC supportati:
- 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).
- Azioni supportate SERVICE ACTION IN:
- READ CAPACITY (16) (0x10).
- Richieste specifiche della classe BOT supportate:
- Get Max LUN (0xFE).
- Bulk-Only Mass Storage Reset (0xFF).
- Comandi SPC supportati:
- Supporta dispositivi UMS con indirizzi di blocchi logici lunghi (LBA a 64 bit) e dimensioni di blocchi logici variabili (512 – 4096 byte).
- Thread in background che si occupa di avviare tutte le unità logiche disponibili da ogni dispositivo UMS appena connesso, oltre a montare i filesystem disponibili da ciascuno quando possibile.
- Schemi di partizionamento supportati:
- Super Floppy Drive (SFD) (Volume Boot Record @ LBA 0).
- Master Boot Record (MBR).
- Extended Boot Record (EBR).
- GUID Partition Table (GPT) + protective MBR.
- File system supportati:
- FAT12/FAT16/FAT32/exFAT (via FatFs).
- NTFS (via NTFS-3G).
- EXT2/3/4 (via lwext4).
- È completamente possibile aggiungere il supporto per file system aggiuntivi, a condizione che le loro librerie siano trasferite su Switch.
- Utilizza l’interfaccia del dispositivo virtuale devoptab per fornire un modo per utilizzare le chiamate I/O standard da libc (ad esempio
fopen()
,opendir()
, ecc..) sui filesystem montati dalle unità logiche disponibili.
- Schemi di partizionamento supportati:
- Interfaccia della libreria facile da usare:
- Fornisce un evento utente di cancellazione automatica che viene segnalato ogni volta che viene rilevata una modifica di stato dal thread in background (nuovo dispositivo montato, dispositivo rimosso).
- Elenco indolore delle partizioni montate utilizzando una semplice struttura che fornisce il nome del dispositivo devoptab, così come altre informazioni interessanti (indice del file system, tipo di file system, protezione da scrittura, capacità dell’unità logica grezza, ecc..).
- Fornisce un modo per smontare in sicurezza i dispositivi UMS in fase di esecuzione.
- Supporta il servizio
usbfs
da SX OS.
Limitazioni
- Driver Bulk-Only Transport (BOT):
- È possibile utilizzare contemporaneamente fino a 32 interfacce di archiviazione di massa USB diverse. L’aumento di questo limite non è dannoso, ma fa sì che la libreria occupi ulteriore memoria heap.
- È possibile eseguire una sola operazione SCSI alla volta per dispositivo UMS, indipendentemente dal numero di unità logiche. Questa è una limitazione ufficiale del protocollo BOT. I mutex vengono utilizzati per evitare che più operazioni SCSI vengano eseguite contemporaneamente sullo stesso dispositivo UMS.
- Librerie del file system:
- FatFs:
- È possibile montare fino a 64 volumi FAT contemporaneamente su tutti i dispositivi UMS disponibili. Il limite originale era 10, ma FatFs è stato leggermente modificato per consentire il montaggio simultaneo di più volumi.
- NTFS-3G:
- Le operazioni di crittografia non sono supportate.
- I contesti di sicurezza vengono sempre ignorati.
- Supporta solo il journaling parziale, quindi arresti anomali imprevisti o interruzioni di corrente possono lasciare il volume NTFS montato in uno stato incoerente. Nei casi in cui si è verificata un’attività pesante prima del crash o della perdita di alimentazione, si consiglia di collegare il dispositivo UMS a un PC Windows e lasciarlo riprodurre correttamente il journal prima di rimontarlo con NTFS-3G, al fine di prevenire la possibile perdita di dati e/o corruzione.
- I collegamenti simbolici sono trasparenti. Ciò significa che quando si incontra un collegamento simbolico, verrà utilizzato il suo collegamento fisico.
- lwext4:
- È possibile montare fino a 8 volumi EXT contemporaneamente su tutti i dispositivi UMS disponibili. Questo perché lwext4 utilizza un registro interno basato sullo stack di punti di montaggio e dispositivi a blocchi, e aumentare il limite può potenzialmente esaurire la memoria dello stack dal thread in cui viene eseguito libusbhsfs.
- Per il resto delle limitazioni, dai un’occhiata al README dal repository lwext4.
- FatFs:
- Consumo di memoria dello stack e/o dell’heap:
- Questa libreria non è adatta per i sysmodule personalizzati e/o progetti MITM di servizio. Assegna un buffer di 8 MiB per ogni dispositivo UMS, che viene utilizzato per i trasferimenti di comandi e dati. Inoltre si basa molto sulle funzionalità di libnx, che non sono sempre compatibili con i contesti del programma sysmodule/MITM.
- Funzionalità FS specifiche per switch:
- I file di concatenazione non sono supportati.
- Servizio
usbfs
da SX OS:- È possibile montare un solo volume FAT da una singola unità.
- I percorsi relativi non sono supportati.
chdir()
,rename()
,dirreset()
eutimes()
non sono supportati.- Probabilmente ci sono altre limitazioni di cui non siamo nemmeno a conoscenza, a causa della natura closed-source di questo CFW.
Licenze
Per questo progetto è prevista una doppia licenza a seconda del modo in cui viene costruito:
- Se la libreria viene creata utilizzando il parametro
BUILD_TYPE=ISC
conmake
, viene distribuita secondo i termini della licenza ISC. È possibile trovare una copia di questa licenza nel file LICENSE_ISC.md.- Le build con licenza ISC forniscono supporto per i filesystem FAT solo tramite FatFs, che è concesso in licenza con FatFs license.
- Se la libreria viene costruita utilizzando il parametro
BUILD_TYPE=GPL
conmake
, e distribuita secondo i termini della GNU General Public License come pubblicata dalla Free Software Foundation; o la versione 2 della licenza o (a tua scelta) qualsiasi versione successiva. È possibile trovare una copia di questa licenza nel file LICENSE_GPLv2.md. Le build con licenza GPLv2+ forniscono supporto per:- File system FAT tramite FatFs, concesso in licenza con FatFs license.
- NTFS tramite NTFS-3G, concesso in licenza con GPLv2+ license.
Come costruire
Questa sezione presume che tu abbia già installato devkitA64 e libnx. In caso contrario, seguire i passaggi su devkitPro wiki.
- Build con licenza ISC:
- Eseguire
make BUILD_TYPE=ISC [all/release/debug]
nella directory principale del progetto.
- Eseguire
- Build con licenza GPLv2+:
- Immettere la directory
libntfs-3g
da questo progetto ed eseguiremakepkg -i --noconfirm
. Questo creerà NTFS-3G per AArch64 e lo installerà nella directoryportlibs
da devkitPro.- Se stai usando Windows, devi utilizzare
msys2
per questo passaggio. Puoi usare quello fornito da devkitPro (consigliato) o installarlo da solo.
- Se stai usando Windows, devi utilizzare
- Torna alla directory principale del progetto ed esegui
make BUILD_TYPE=GPL [all/release/debug]
.
- Immettere la directory
Verrà generata una directory lib
, contenente la libreria statica costruita.
Come usare
Questa sezione presuppone che tu abbia già creato la libreria seguendo i passaggi della sezione precedente.
- Aggiornare il
Makefile
dalla tua applicazione homebrew per fare riferimento alla libreria.- Vengono generate due build differenti: una build di rilascio (
-lusbhsfs
) e una build di debug con registrazione abilitata (-lusbhsfsd
). - Se stai utilizzando una build con licenza GPLv2+, dovrai anche collegare la tua applicazione a NTFS-3G:
-lusbhsfs -lntfs-3g
. - Nel caso in cui sia necessario segnalare eventuali bug, assicurarsi di utilizzare la build di debug e fornire il relativo file di registro.
- Vengono generate due build differenti: una build di rilascio (
- Includere il file di intestazione
usbhsfs.h
da qualche parte nel codice. - Inizializza l’interfaccia host della classe di archiviazione di massa USB con
usbHsFsInitialize()
. - Recuperare un puntatore all’evento di modifica dello stato UMS in modalità utente con
usbHsFsGetStatusChangeUserEvent()
e attendere che l’evento venga segnalato (ad esempio sotto un thread diverso). - Ottieni il conteggio dei dispositivi montati con
usbHsFsGetMountedDeviceCount()
. - Elenca i dispositivi montati con
usbHsFsListMountedDevices()
. - Eseguire operazioni di I/O utilizzando i nomi di montaggio restituiti dai dispositivi elencati.
- Se, per qualche motivo, è necessario smontare in sicurezza un dispositivo UMS in fase di esecuzione prima di scollegarlo, utilizzare
usbHsFsUnmountDevice()
. - Al termine, chiudere l’interfaccia host della classe di archiviazione di massa USB con
usbHsFsExit()
.
Si prega di controllare sia il file di intestazione che si trova in /include/usbhsfs.h
e l’applicazione di prova fornita in /example
per ulteriori informazioni.
Supporto relativo al percorso
[stextbox id=’info’]Nota¹: Tutte le chiamate fsdevMount*()
da libnx (e qualsiasi wrapper attorno ad esse) possono e sovrascriveranno il dispositivo devoptab predefinito se utilizzato dopo una chiamata chdir()
riuscita utilizzando un percorso assoluto da un volume montato in un dispositivo UMS. Se si verifica una cosa del genere, e hai ancora bisogno di eseguire operazioni aggiuntive con percorsi relativi, chiama di nuovo chdir()
.[/stextbox]
[stextbox id=’info’]Nota²: Il supporto del percorso relativo non è disponibile sotto SX OS![/stextbox]
Una chiamata chdir()
che utilizza un percorso assoluto a una directory da un volume montato (ad esempio "ums0:/"
) deve essere eseguita per cambiare sia il dispositivo devoptab predefinito che la directory di lavoro corrente. Questo ti posizionerà effettivamente nella directory fornita e tutte le operazioni di I/O eseguite con i percorsi relativi funzioneranno su di essa.
La scheda SD verrà impostata come nuovo dispositivo devoptab predefinito in due diverse condizioni:
- Se il dispositivo UMS che contiene il volume impostato come dispositivo devoptab predefinito viene rimosso dalla console.
- Se l’interfaccia USB Mass Storage Class Host viene chiusa tramite
usbHsFsExit()
e un volume da un dispositivo UMS disponibile è stato impostato come dispositivo devoptab predefinito.
Per un esempio, controllare l’applicazione di prova fornita in /example
.
Changelog
- Miglioramenti aUSB manager:
- Funzioni di richiesta di controllo USB rifattorizzate per lavorare con i tipi di dati USB libnx invece dei contesti di unità/unità logica.
- Richieste di controllo
GET_DESCRIPTOR
implementate per la configurazione e i descrittori di stringa.
- Miglioramenti al driver BOT:
- Se
usbHsEpPostBuffer()
non riesce, verrà cancellato solo l’endpoint con cui la libreria sta attualmente lavorando. Inoltre, il risultato di questa operazione non influisce più sul codice di ritorno. - Se
usbHsFsRequestPostBuffer()
fallisce, la libreria ora prova a recuperare immediatamente un CSW – se riesce, un comando Request Sense verrà inviato immediatamente al dispositivo a blocchi. - Il successo del comando Mode Sense (6)/Mode Sense (10) non è più obbligatorio in
usbHsFsScsiStartDriveLogicalUnit()
. - La versione standard di SPC ora è convalidata.
- Se
- Miglioramenti agli script PKGBUILD per NTFS-3G e lwext4:
- Reso possibile costruire e installare tutte e tre le librerie usando il Makefile – per maggiori informazioni, fare riferimento alla sezione How to install dal README.
- Il percorso della libreria corretto ora viene forzato durante la creazione di NTFS-3G. Corregge i problemi in alcuni sistemi Linux. Grazie a sigmaboy per la correzione.
- Altri piccoli miglioramenti.
- Modifiche all’API della libreria:
- Aggiunti campi
vid
epid
aUsbHsFsDevice
. Utile se l’applicazione deve implementare da sola un filtro del dispositivo. - I campi
vendor_id
,product_id
eproduct_revision
inUsbHsFsDevice
sono stati sostituiti con i campi producer, product_name eserial_number
, che rappresentano le conversioni UTF-8 dei descrittori di stringa a cui fa riferimento il descrittore del dispositivo USB.- Le stringhe dai dati SCP INQUIRY sono ancora utilizzate come metodo di fallback per i campi
manufacturer
eproduct_name
se il descrittore del dispositivo USB non contiene riferimenti ai descrittori di stringa.
- Le stringhe dai dati SCP INQUIRY sono ancora utilizzate come metodo di fallback per i campi
- Aggiunti campi
- Modifiche varie:
- Rinominato
ff_rename()
da FatFs per evitare problemi risolvere i conflitti nelle applicazioni collegate a FFmpeg. Grazie a Cpasjuste per avercelo fatto sapere. - Il flag
has_journal
dal superblocco nei filesystem EXT è ora verificato prima di chiamare le funzioni relative al journal. - La versione del file system EXT viene ora recuperata solo una volta, durante il montaggio del volume.
- L’estensione API sm
AtmosphereHasService
disponibile nei CFW basati sui Custom Firmware Atmosphère e Atmosphère ora viene utilizzata per verificare se un servizio specifico è in esecuzione.- Il supporto per HOS 12.0.x / AMS 0.19.x viene fornito utilizzando la serializzazione TIPC per inviare la richiesta IPC, se necessario.
- Codice del file di registro migliorato e registrazione dei dati binari semplificata in tutta la base di codice.
- Rinominato
- Cambiamenti sotto il cofano (attualmente inutilizzati, ma potrebbero cambiare in futuro):
- Implementati comandi SCP SYNCHRONIZE CACHE (10) e SYNCHRONIZE CACHE (16).
- Contesti di unità logica e unità modificati per preparare il supporto UASP.
- Aggiunto codice extra per gestire i descrittori dell’interfaccia USB Attached SCSI Protocol (UASP) in entrambe le modalità USB 2.0 e 3.0.
Risorse in questa versione
libusbhsfs_0.2.3-main-c5d8e12-src.tar.bz2
: Codice sorgente completo di libusbhsfs.libusbhsfs_0.2.3-main-c5d8e12_ISC.tar.bz2
: Build con licenza ISC di libusbhsfs. Offre supporto solo per file system FAT (FAT12, FAT16, FAT32, exFAT).libusbhsfs_0.2.3-main-c5d8e12_GPLv2.tar.bz2
: Build con licenza GPLv2+ di libusbhsfs. Offre supporto per file system FAT (FAT12, FAT16, FAT32, exFAT), NTFS ed EXT (EXT2, EXT3, EXT4). Le applicazioni che utilizzano questa build devono essere collegate anche a NTFS-3G e lwext4.
Sia gli archivi ISC che GPLv2+ contengono anche l’applicazione di test di esempio NRO collegata a quella versione della libreria.
Download: libusbhsfs_0.2.3-main-c5d8e12-src.tar.bz2
Download: libusbhsfs_0.2.3-main-c5d8e12_GPLv2.tar.bz2
Download: libusbhsfs_0.2.3-main-c5d8e12_ISC.tar.bz2
Download: Source code libusbhsfs v0.2.3
Fonte: github.com