Codici di uscitaExit codes

Un Azure Sphere applicazione di alto livello può utilizzare i codici di uscita per restituire informazioni correlate a dove nel codice si è verificato l'errore e perché si è verificato.An Azure Sphere high-level application can use exit codes to return information related to where in the code the error occurred and why it occurred. Un codice di uscita corrisponde a un valore compreso tra 0 e 255, dove 0 indica l'esito positivo.An exit code corresponds to a value between 0 and 255, where 0 indicates success.

Definire e usare i codici di uscita in un'appDefine and use exit codes in an app

Per definire e usare i codici di uscita in un'app, seguire queste linee guida:Follow these guidelines to define and use exit codes in an app:

  • Creare una variabile di codice di uscita e inizializzarla su Success (0) all'inizio dell'applicazione.Create an exit code variable and initialize it to success (0) at the start of the application.
  • Restituisce un codice di uscita da qualsiasi funzione in cui un errore ha causato la chiusura dell'applicazione.Return an exit code from any function where an error has caused the application to exit. I codici di uscita della funzione possono fornire informazioni dettagliate sugli errori operativi.The function exit codes can provide detailed information about operational errors. Ad esempio, una funzione che invia un messaggio a un'applicazione IoT Central potrebbe restituire un codice di errore che fornisce informazioni dettagliate sul punto in cui si è verificato l'errore: nella costruzione di un messaggio, nella connessione dell'intero, nella trasmissione dei messaggi e così via.For example, a function that sends a message to an IoT Central application might return an error code that provides details about where failure occurred: in message construction, IoT connection, message transmission, and so forth. Una funzione diversa responsabile dell'inizializzazione delle periferiche restituirebbe un codice di uscita univoco per indicare un errore con una periferica specifica.A different function responsible for initializing peripherals would return a unique exit code to indicate a failure with a specific peripheral.
  • Se il codice di uscita di un errore (diverso da zero) viene impostato o restituito da una funzione, assicurarsi che venga immediatamente propagato per restituire la funzione principale .If a failure exit code (nonzero) is set or returned by a function, ensure it is immediately propagated back for the main function to return. Questa operazione causerà l'uscita dell'applicazione con il codice di uscita specificato.This will cause the application to exit with the given exit code. Il sistema operativo Azure Sphere riavvierà immediatamente l'applicazione (a meno che non si stia usando il debugger con una lavagna di sviluppo connessa) ed è possibile usare i report degli errori per diagnosticare il motivo di un si è verificato di uscita.The Azure Sphere OS will immediately restart your application (unless you were using the debugger with a connected development board), and you can use error reports to diagnose the reason an exit ocurred.

Report di erroriError reports

Quando si esce da un'applicazione di livello elevato, il sistema operativo Azure Sphere registra il codice di uscita restituito dall'applicazione e successivamente carica una segnalazione errori contenente queste informazioni per il servizio di sicurezza Azure Sphere giornaliero.When a high-level application exits, the Azure Sphere OS logs the exit code returned by your application, and later uploads an error report containing this information to the Azure Sphere Security Service daily. Confrontando il codice di uscita nella segnalazione errori con i codici di uscita definiti nell'applicazione, è spesso possibile determinare la posizione e la causa dell'errore.By comparing the exit code in the error report against the exit codes defined in your application, you can often determine the location and cause of the error. Per ulteriori informazioni, vedere interpretare AppExits .See Interpret AppExits for more information.

RTApps non è in grado di restituire i dati di errore direttamente al servizio di sicurezza Azure Sphere.RTApps cannot return error data directly to the Azure Sphere Security Service. Se si vuole implementare il rilevamento degli errori in un RTApp, è necessario comunicare i dati di errore da RTApp a un'app di alto livello usando il meccanismo di comunicazione tra core.If you want to implement error tracking in an RTApp, you'll need to communicate the error data from the RTApp to a high-level app using the inter-core communications mechanism. Per informazioni dettagliate, vedere comunicare con un'applicazione di alto livello e comunicare con un'applicazione in tempo reale in grado di supportare.See Communicate with a high-level application and Communicate with a real-time capable application for details.

Esempio di implementazione del codice di uscitaSample exit code implementation

I frammenti di codice seguenti mostrano un esempio di come è possibile incorporare i codici di uscita in un'applicazione di alto livello.The following snippets show a sample of how you can incorporate exit codes into a high-level application.

Dichiarare prima di ExitCode tutto un'enum nell'applicazione che è possibile usare per definire tutti i valori del codice di uscita specifici.First, declare an ExitCode enum in your application that you can use to define all of your specific exit code values. Quindi, inizializzare una exitCode variabile globale sullo stato di esito positivo (0).Then, initialize a global exitCode variable to the success state (0).

// Exit codes for this application.
typedef enum {
ExitCode_Success = 0;
ExitCode_Init_LED = 1;
ExitCode_Init_Button = 2;
} ExitCode;

// Initialize the termination state.
static volatile sig_atomic_t exitCode = ExitCode_Success;

Le funzioni che contengono casi di errore che devono terminare l'applicazione devono restituire un'enumerazione ExitCode.Functions that contain error cases that should terminate the application should return an ExitCode enum. Se viene raggiunto un caso di errore che deve terminare l'applicazione, restituire il codice di uscita specifico definito in tale caso.If an error case is reached that should terminate the application, return the specific exit code you defined for that case. Nell'esempio seguente InitPeripheralsAndHandlers viene definita la funzione, che Inizializza un LED e un pulsante.In the below example, the InitPeripheralsAndHandlers function is defined, which initializes an LED and a button. Se l'inizializzazione ha esito negativo, ExitCode viene restituito il valore corrispondente definito sopra.If either initialization fails, the corresponding ExitCode value defined above is returned.

// Initialize the peripherals and handlers. Return ExitCode_Success if all resources were allocated
// successfully; otherwise another ExitCode value which indicates a specific failure.
static ExitCode InitPeripheralsAndHandler(void)
{
    // Open SAMPLE_LED as output.
    led = GPIO_OpenAsOutput(SAMPLE_LED);
    if (led == -1) {
        return ExitCode_Init_LED;
    }

    // Open SAMPLE_BUTTON as input.
    button = GPIO_OpenAsInput(SAMPLE_BUTTON);
    if (button == -1) {
        return ExitCode_Init_Button;
    }
    return ExitCode_Success;
}

Dopo l'inizializzazione, l'applicazione rimane nel ciclo principale fino a quando alla exitCode variabile globale viene comunque assegnato il valore iniziale di operazione riuscita.After initialization, the application stays in the main loop as long as the global exitCode variable is still assigned the initial success value. Se una parte della logica dell'applicazione principale imposta la exitCode variabile su un valore diverso da Success, l'applicazione si interrompe dal ciclo principale e termina con il set exitCode .If any part of the main application logic ever sets the exitCode variable to a value other than success, the application will break out of the main loop and exit with the set exitCode. Il sistema operativo Azure Sphere acquisirà l'evento di uscita dell'app e il codice di uscita corrispondente in una segnalazione errori, quindi riavvierà l'applicazione.The Azure Sphere OS will capture the app exit event and corresponding exit code in an error report, then restart your application.

int main(int argc, char* argv[])
{
    exitCode = InitPeripheralsAndHandler();

    while (exitCode == ExitCode_Success) {
        // Run other application functions within this loop.
        // When a function encounters an error, set a corresponding exit code and return from that function.
        // This will break out of the while loop if the exit code is not ExitCode_Success.
    }

    return exitCode;
}