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).
• 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.
• 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.
• 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() e utimes() 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 con make, 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 con make, 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:
  1. Eseguire make BUILD_TYPE=ISC [all/release/debug] nella directory principale del progetto.
• Build con licenza GPLv2+:
  1. Immettere la directory libntfs-3g da questo progetto ed eseguire makepkg -i --noconfirm. Questo creerà NTFS-3G per AArch64 e lo installerà nella directory portlibs da devkitPro.
     • Se stai usando Windows, devi utilizzare msys2 per questo passaggio. Puoi usare quello fornito da devkitPro (consigliato) o installarlo da solo.
  2. Torna alla directory principale del progetto ed esegui make BUILD_TYPE=GPL [all/release/debug].

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.
• 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 v0.2.2

• A grande richiesta, il journal NTFS ora viene ricostruito per impostazione predefinita per i volumi NTFS che non sono stati smontati correttamente, il che consente alla libreria di montarli immediatamente senza dover utilizzare un PC Windows. Tieni presente che questo processo può causare incongruenze: cerca sempre di rimuovere in sicurezza i tuoi dispositivi di archiviazione.
  • Tuttavia, questa dovrebbe essere un’operazione relativamente sicura – il comportamento predefinito in NTFS-3G è cambiato alcuni anni fa.
  • Questa modifica influisce anche sul montaggio del volume EXT. Il journal EXT ora tenterà sempre di essere ripristinato – se il processo fallisce, il volume EXT non verrà montato.

Changelog v0.2.1

• Bugfix: Gli ID dei nomi di montaggio ora vengono liberati correttamente durante la distruzione dei contesti del filesystem.
• Libreria API: Aggiunta una macro del preprocessore helper per generare stringhe in base ai valori del tipo di file system supportati.
• Makefile: Il nome del ramo ora viene recuperato utilizzando rev-parse invece di symbolic-ref. Correzioni ref HEAD is not a symbolic ref non è un errore di riferimento simbolico durante la creazione della libreria quando il repository viene utilizzato come sottomodulo git.
• Makefile: branch name is now retrieved using rev-parse instead of symbolic-ref. Corretti gli errori ref HEAD is not a symbolic ref durante la creazione della libreria quando la repository viene utilizzata come sottomodulo git.

Changelog v0.2.0

• Costruito utilizzando la libreria libnx v4.0.0.
• Implementato il supporto EXT2/3/4 (solo build GPL).
  • Ciò significa che le applicazioni che utilizzano la build GPL della libreria ora devono essere collegate a libusbhsfs, NTFS-3G e lwext4. Si prega di leggere la sezione How to build dal README per sapere come creare sia NTFS-3G che lwext4 e installarli nella directory portlibs da devkitPro.
  • Si applicano alcune limitazioni. Si prega di leggere la sezione Limitazioni per ulteriori informazioni.
  • Certain limitations apply. Please read the Limitations section from the README for more information.
• Voci della directory di punti “.” e “..” ora sono filtrati nei volumi NTFS. Non vengono più visualizzati come parte dell’output di readdir().
• Pulizia del codice minore.
• L’applicazione di test di esempio ora è collegata anche a lwext4.

Changelog v0.1.0

• Costruito utilizzando libnx commit c51918a.
• Implementata l’analisi della tabella delle partizioni (MBR/GPT/VBR). La libreria ora si occupa di cercare i settori di avvio e/o le tabelle delle partizioni da sola e passa semplicemente gli LBA del volume alle librerie del file system. Ciò rende possibile montare più partizioni dalla stessa unità logica dei singoli dispositivi devoptab.
• Implementato il supporto NTFS. Grazie mille a Rhys Koedijk!
  • Devi collegare la tua applicazione sia a libusbhsfs che a NTFS-3G se desideri utilizzare il supporto NTFS. Si prega di leggere la sezione How to build dal README per sapere come creare NTFS-3G e installarlo nella directory portlibs da devkitPro.
  • Si applicano alcune limitazioni. Si prega di leggere la sezione Limitations del README per ulteriori informazioni.
  • La doppia licenza (ISC/GPLv2 +) ora viene fornita come un modo per consentire ai progetti che non sono conformi alla licenza GPLv2+ di NTFS-3G di continuare a utilizzare libusbhsfs, anche se solo con supporto FAT. Per ulteriori informazioni, leggere la sezione Licensing nel file readme.
• Migliorati i controlli di sicurezza in tutte le funzioni interne di devoptab.
• Libreria API:
  • usbHsFsUnmountDevice() ora viene fornito come un modo per smontare manualmente/in sicurezza i dispositivi UMS in fase di esecuzione prima di scollegarli.
    • Questo è sempre stato gestito automaticamente da usbHsFsExit() se ci sono dispositivi UMS montati quando l’interfaccia della libreria è chiusa. Quindi, a seconda di ciò di cui hai bisogno, dovresti chiamare usbHsFsUnmountDevice() solo quando assolutamente necessario.
  • usbHsFsGetFileSystemMountFlags() e usbHsFsSetFileSystemMountFlags() ora vengono forniti come un modo per ottenere/impostare i flag di montaggio del filesystem.
    • Si prega di leggere include/usbhsfs.h per ulteriori informazioni su questi flag e su cosa fanno.
    • Questi flag influenzano solo il montaggio del volume NTFS in questo momento, quindi non hanno alcun effetto nelle build della libreria con licenza ISC.
    • Inoltre, queste funzioni non hanno alcun effetto sotto SX OS.
• Driver BOT:
  • Il comando SCSI di richiesta ora viene ritentato se viene ricevuto un CSW imprevisto senza dati di rilevamento.
  • Ora vengono filtrati sia i valori del qualificatore periferico che del tipo di dispositivo periferico dai dati di ricerca. Grazie a ginkuji per aver segnalato questo problema.
  • L’avvio dell’unità logica ora ritorna immediatamente se un comando SCSI opzionale non riesce e un codice di rilevamento aggiuntivo Medium Not Present viene segnalato dal dispositivo UMS.
  • Un ripristino del bus ora viene eseguito su tutti i dispositivi UMS che sono già disponibili quando viene chiamato usbHsFsInitialize(). Corregge l’avvio dell’unità logica per le unità che sono state arrestate durante una sessione precedente, ma non rimosse dalla console. Grazie a FlyingBananaTree per aver segnalato questo problema.
  • Corretti i potenziali problemi di danneggiamento della memoria che potevano verificarsi a causa del mancato aggiornamento dei riferimenti di contesto LUN/FS dopo la riallocazione dei buffer.
• Build Debug:
  • Implementata una corretta memorizzazione nella cache nel codice di registrazione del debug, rendendo le build di debug molto più veloci ora.
  • Il file di registro ora viene scaricato ogni volta che viene chiamata una funzione API pubblica che genera messaggi di registro.
• SX OS:
  • L’evento di modalità utente di cambio di stato ora viene segnalato ad ogni cambio di stato usbfs.
• Esempi di applicazione di prova:
  • Aggiornato per riflettere tutti questi cambiamenti.
  • Aggiunti altri test sul filesystem.
  • Riscritto la gestione dell’input per abbinare la nuova API pad da libnx.
  • Ora usando usbHsFsUnmountDevice() per smontare in sicurezza tutti i dispositivi UMS che sono già stati testati.

Risorse in questa versione

• libusbhsfs_0.2.2-main-e600835-src.tar.bz2: Codice sorgente completo di libusbhsfs.
• libusbhsfs_0.2.2-main-e600835_ISC.tar.bz2: Build con licenza ISC di libusbhsfs. Offre supporto solo per file system FAT (FAT12, FAT16, FAT32, exFAT).
• libusbhsfs_0.2.2-main-e600835_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.2-main-e600835-src.tar.bz2

Download: libusbhsfs_0.2.2-main-e600835_GPLv2.tar.bz2

Download: libusbhsfs_0.2.2-main-e600835_ISC.tar.bz2

Download: Source code libusbhsfs v0.2.2

Fonte: github.com