Home Homebrew Rilasciato libusbhsfs v0.2.4

[Scena Switch] Rilasciato libusbhsfs v0.2.4

376
0

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()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:

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

  • Aggiornato FatFs alla release 0.14b.
  • L’intestazione GPT di backup da un’unità ora viene recuperata e utilizzata se l’intestazione GPT principale è danneggiata, purché sia disponibile.
  • Codice di registrazione del debug leggermente migliorato.
  • Riscritta la gestione del mutex in tutto il codice per utilizzare una piccola implementazione di blocco con ambito basato su macro quando possibile.
  • Rimosse le operazioni di memoria superflue utilizzando array di puntatori dinamici per gestire i contesti di unità logiche/filesystem.
  • Aggiunte chiamate splInitialize / splExit mancanti durante il controllo se un servizio è in esecuzione.
    • Inoltre, la versione dell’API Exosphère, che viene utilizzata per determinare se è necessaria la serializzazione TIPC anziché CMIF, ora viene salvata durante il primo controllo del servizio.

Risorse in questa versione

  • libusbhsfs_0.2.4-main-ead3651-src.tar.bz2: Codice sorgente completo di libusbhsfs.
  • libusbhsfs_0.2.4-main-ead3651_ISC.tar.bz2: Build con licenza ISC di libusbhsfs. Offre supporto solo per file system FAT (FAT12, FAT16, FAT32, exFAT).
  • libusbhsfs_0.2.4-main-ead3651_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.4-main-ead3651-src.tar.bz2

Download: libusbhsfs_0.2.4-main-ead3651_GPLv2.tar.bz2

Download: libusbhsfs_0.2.4-main-ead3651_ISC.tar.bz2

Download: Source code libusbhsfs v0.2.4

Fonte: github.com