Uso dell'archiviazione in Azure SphereUsing storage on Azure Sphere

Questo argomento descrive come usare lo spazio di archiviazione in un dispositivo Azure Sphere.This topic describes how to use storage on an Azure Sphere device. Azure Sphere fornisce due tipi di archiviazione, ovvero lo spazio di archiviazione flash di sola lettura e lo spazio di archiviazione modificabile.Azure Sphere provides two types of storage, read-only flash storage and mutable storage.

Lo spazio di archiviazione di sola lettura viene usato per archiviare i pacchetti immagine dell'applicazione in un dispositivo, in modo che il contenuto non possa essere modificato senza aggiornare l'applicazione.Read-only storage is used to store application image packages on a device so the contents can't be modified without updating the application. Può trattarsi di qualsiasi dato, ad esempio asset dell'interfaccia utente, dati di configurazione statici, risorse binarie incluse le immagini del firmware usate per aggiornare le MCU esterne o dati di inizializzazione per lo spazio di archiviazione modificabile.This can include any data such as user interface assets, static configuration data, binary resources including firmware images used to update external MCUs, or initialization data for mutable storage. La sezione Memoria disponibile per le applicazioni fornisce altri dettagli sulla quantità di spazio di archiviazione disponibile.Memory available for applications provides additional details about the amount of storage available.

Lo spazio di archiviazione modificabile consente di archiviare dati che vengono mantenuti in caso di riavvio del dispositivo.Mutable storage stores data that persists when a device reboots. Ad esempio, se si vuole gestire l'ora di sistema con il fuso orario locale, è possibile archiviare le impostazioni di fuso orario nello spazio di archiviazione modificabile.For example, if you want to manage system time using the local time zone, you can store the time zone settings in mutable storage. Altri esempi sono le impostazioni modificabili da un utente o i dati di configurazione scaricati.Some other examples are settings a user can modify, or downloaded configuration data. L'esempio di spazio di archiviazione modificabile illustra come usare l'archiviazione modificabile in un'applicazione.The mutable storage sample shows how to use mutable storage in an application.

Uso dello spazio di archiviazione di sola letturaUsing read-only storage

È possibile usare queste funzioni Applibs per gestire lo spazio di archiviazione di sola lettura.You can use these Applibs functions to manage read-only storage. Per un esempio che usa queste funzioni, vedere Connettersi ai servizi Web mediante curl.For an example that uses these functions see Connect to web services using curl.

Requisiti di archiviazione di sola letturaRead-only storage requirements

Le applicazioni che usano l'archiviazione di sola lettura devono includere i file di intestazione appropriati.Applications that use read-only storage must include the appropriate header files.

Includere le intestazioni per lo spazio di archiviazione e unistd nel progetto:Include the storage and unistd headers in your project:

#include <unistd.h>
#include <applibs/storage.h>

Aggiungere un file a un pacchetto immagineAdd a file to an image package

Per aggiungere un file all'archiviazione di sola lettura nel dispositivo Azure Sphere, è possibile aggiungerlo al progetto come risorsa e includerlo nel pacchetto immagine dell'applicazione.To add a file to read-only storage on the Azure Sphere device, you can add it to your project as a resource and include it in the application's image package. Usare queste funzioni in CMakeLists.txt per aggiungere il file come risorsa:Use these functions in CMakeLists.txt to add the file as a resource:

  • Usare azsphere_configure_tools per configurare la versione di Azure Sphere SDK Tools.Use azsphere_configure_tools to configure the Azure Sphere SDK Tools version. Ad esempio:For example:

    azsphere_configure_tools(TOOLS_REVISION "20.04")

  • Usare azsphere_target_add_image_package per specificare il file del pacchetto immagine e tutti i file di risorse da includere durante la compilazione.Use azsphere_target_add_image_package to specify the image package file and any resources files to include when building. Ad esempio:For example:

    azsphere_target_add_image_package(${PROJECT_NAME} RESOURCE_FILES "file1.dat" "file2.dat")

I file "file1.dat" e "file2.dat" verranno ora visualizzati nel pacchetto immagine.The files "file1.dat" and "file2.dat" should now appear in the image package. Per altre informazioni su queste funzioni, vedere Usare le funzioni CMake.See Use CMake functions for more information about these functions.

Nota

I percorsi assoluti non sono supportati per RESOURCE_FILES.Absolute paths are not supported for RESOURCE_FILES.

Uso dello spazio di archiviazione modificabileUsing mutable storage

Quando si configura lo spazio di archiviazione modificabile per l'applicazione, a tale spazio viene assegnato l'ID di componente dell'applicazione e non è possibile accedervi da un'applicazione con un ID di componente diverso.When you configure mutable storage for your application, it is assigned to the component ID of the application and can't be accessed by an application that has a different component ID. Se l'ID del componente dell'applicazione viene modificato, la nuova applicazione non avrà accesso allo spazio di archiviazione modificabile dell'applicazione precedente.If the component ID of the application changes, the new application will not have access to the mutable storage of the previous application.

Se si elimina un'applicazione da un dispositivo, viene eliminato anche lo spazio di archiviazione modificabile assegnato all'applicazione.If you delete an application from a device, the mutable storage assigned to the application is also deleted. Se la stessa applicazione viene quindi caricata nuovamente nel dispositivo, lo spazio di archiviazione modificabile sarà vuoto.If the same application is then loaded back onto the device, the mutable storage will be empty. Tuttavia, se si aggiorna l'applicazione senza eliminarla, il contenuto dello spazio di archiviazione modificabile viene mantenuto.However, if you update the application without deleting it, the mutable storage contents are maintained.

Il comando azsphere device app show-quota visualizza la quantità di spazio di archiviazione modificabile attualmente in uso.The azsphere device app show-quota command displays the amount of mutable storage currently in use.

Il sistema operativo Azure Sphere dispone di meccanismi di protezione da una perdita di energia per evitare il danneggiamento dello stato di configurazione critico e dei metadati del file system.The Azure Sphere OS has power-loss protection mechanisms in place to avoid corruption of critical configuration state and file system metadata. L'API di archiviazione modificabile trae vantaggio da queste funzionalità.The mutable storage API benefits from these features. Tuttavia, il contenuto effettivo dell'archiviazione modificabile dipende dal fatto che e in quale ordine vengono scaricati i buffer, quindi non esiste alcuna garanzia che tutte le modifiche in sospeso al momento della perdita di energia vengano riflesse nel file stesso dopo il ripristino.However, the actual contents of mutable storage depends on whether, and in what order, buffers are flushed, so there is no guarantee that all pending changes at the time of power loss will be reflected in the file itself after recovery.

È possibile usare queste funzioni Applibs per gestire i dati nello spazio di archiviazione modificabile:You can use these Applibs functions to manage mutable storage data:

Requisiti dello spazio di archiviazione modificabileMutable storage requirements

Le applicazioni che usano lo spazio di archiviazione modificabile devono includere i file di intestazione appropriati e aggiungere le impostazioni dello spazio di archiviazione modificabile al manifesto dell'applicazione.Applications that use mutable storage must include the appropriate header files and add mutable storage settings to the application manifest.

File di intestazione per lo spazio di archiviazione modificabileHeader files for mutable storage

Includere le intestazioni per lo spazio di archiviazione e unistd nel progetto:Include the storage and unistd headers in your project:

#include <unistd.h>
#include <applibs/storage.h>

Manifesto dell'applicazioneApplication manifest

Per usare le API di questo argomento, è necessario aggiungere la funzionalità MutableStorage al manifesto dell'applicazione e quindi impostare il campo SizeKB.To use the APIs in this topic, you must add the MutableStorage capability to the application manifest and then set the SizeKB field. Il campo SizeKB è un intero che specifica le dimensioni dello spazio di archiviazione modificabile in kibibyte.The SizeKB field is an integer that specifies the size of your mutable storage in kibibytes. Il valore massimo è 64 e lo spazio di archiviazione viene allocato in base alla dimensione del blocco di cancellazione del dispositivo.The maximum value is 64 and the storage is allocated according to the erase block size of the device. L'allocazione avviene arrotondando per eccesso il valore di SizeKB alla dimensione del blocco successiva se il valore non è un multiplo intero della dimensione del blocco del dispositivo.The allocation is done by rounding up the SizeKB value to the next block size if the value isn't a whole multiple of the block size of the device.

Nota

Il blocco di cancellazione di MT3620 è di 8 KB, quindi tutti i valori che non sono multipli di 8 verranno arrotondati.The MT3620 has an erase block size of 8 KB, so any values that are not multiples of 8 will be rounded up. Se ad esempio si specifica il valore 12 KB nella funzionalità 'MutableStorage', si riceveranno 16 KB in un dispositivo MT3620.For example, if you specify 12 KB in the 'MutableStorage' capability, you will receive 16 KB on an MT3620.

Nell'esempio seguente, la funzionalità di archiviazione MutableStorage viene aggiunta al manifesto dell'applicazione con una dimensione di 8 KB.In the example below, the MutableStorage storage capability is added to the application manifest with a size of 8 KB.

{
  "SchemaVersion": 1,
  "Name" : "Mt3620App_Mutable_Storage",
  "ComponentId" : "9f4fee77-0c2c-4433-827b-e778024a04c3",
  "EntryPoint": "/bin/app",
  "CmdArgs": [],
   "Capabilities": {
    "AllowedConnections": [],
    "AllowedTcpServerPorts": [],
    "AllowedUdpServerPorts": [],
    "MutableStorage": { "SizeKB": 8 },
    "Gpio": [],
    "Uart": [],
    "WifiConfig": false,
    "NetworkConfig": false,
    "SystemTime": false
  }
}

Scrivere dati permanentiWrite persistent data

Per scrivere dati nello spazio di archiviazione permanente, iniziare chiamando la funzione Applibs Storage_OpenMutableFile per recuperare un descrittore di file per un file di dati permanente.To write data to persistent storage, start by calling the Applibs function Storage_OpenMutableFile to retrieve a file descriptor for a persistent data file. Chiamare poi la funzione write per scrivere i dati nel file di dati permanente.Next call the write function to write the data to the persistent data file. Se la quantità di dati che si tenta di scrivere supera l'allocazione dello spazio di archiviazione modificabile, la funzione di scrittura potrebbe avere esito positivo. Verranno scritti però solo i dati che rientrano nello spazio di archiviazione allocato.If the amount of data you attempt to write exceeds your mutable storage allocation, the write function might succeed; however, the only data written will be the portion that doesn't exceed the storage allocation. Per assicurarsi che tutti i dati vengano scritti, è necessario controllare il valore restituito dalla chiamata della funzione write.To ensure all the data is written you must check the return value of the write function call.

Leggere dati permanentiRead persistent data

Per leggere dati dallo spazio di archiviazione permanente, chiamare Storage_OpenMutableFile per recuperare un descrittore di file per il file di dati permanente e quindi chiamare la funzione read per leggere i dati.To read data from persistent storage call Storage_OpenMutableFile to retrieve a file descriptor for the persistent data file, and then call the read function to read the data.

Eliminare dati permanentiDelete persistent data

Per eliminare dati dallo spazio di archiviazione permanente, chiamare Storage_DeleteMutableFile.To delete data from persistent storage call Storage_DeleteMutableFile.