Códigos de saída

  • Artigo

Uma aplicação de alto nível do Azure Sphere pode utilizar códigos de saída para devolver informações relacionadas com onde ocorreu o erro no código e por que motivo ocorreu. Um código de saída corresponde a um valor entre 0 e 255, em que 0 indica êxito.

Definir e utilizar códigos de saída numa aplicação

Siga estas diretrizes para definir e utilizar códigos de saída numa aplicação:

  • Crie uma variável de código de saída e inicialize-a para êxito (0) no início da aplicação.
  • Devolver um código de saída de qualquer função em que um erro tenha causado a saída da aplicação. Os códigos de saída da função podem fornecer informações detalhadas sobre erros operacionais. Por exemplo, uma função que envia uma mensagem para uma aplicação do IoT Central pode devolver um código de erro que fornece detalhes sobre onde ocorreu a falha: na construção de mensagens, ligação IoT, transmissão de mensagens, etc. Uma função diferente responsável pela inicialização de periféricos devolveria um código de saída exclusivo para indicar uma falha com um periférico específico.
  • Se um código de saída de falha (não zero) for definido ou devolvido por uma função, certifique-se de que é imediatamente propagado para que a função principal regresse. Isto fará com que a aplicação saia com o código de saída especificado. O SO do Azure Sphere reiniciará imediatamente a sua aplicação (a menos que estivesse a utilizar o depurador com uma placa de desenvolvimento ligada) e poderá utilizar relatórios de erros para diagnosticar o motivo pelo qual ocorreu uma saída.

Relatórios de erros

Quando uma aplicação de alto nível sai, o SO do Azure Sphere regista o código de saída devolvido pela sua aplicação e, posteriormente, carrega um relatório de erros que contém estas informações para o Serviço de Segurança do Azure Sphere diariamente. Ao comparar o código de saída no relatório de erros com os códigos de saída definidos na sua aplicação, pode muitas vezes determinar a localização e a causa do erro. Veja Interpretar AppExits para obter mais informações.

O RTApps não consegue devolver dados de erro diretamente ao Serviço de Segurança do Azure Sphere. Se quiser implementar o controlo de erros numa RTApp, terá de comunicar os dados de erro do RTApp para uma aplicação de alto nível com o mecanismo de comunicações entre núcleos. Veja Comunicar com uma aplicação de alto nível e Comunicar com uma aplicação em tempo real para obter detalhes.

Implementação de código de saída de exemplo

Os fragmentos seguintes mostram uma amostra de como pode incorporar códigos de saída numa aplicação de alto nível.

Em primeiro lugar, declare uma enumeração ExitCode na sua aplicação que pode utilizar para definir todos os valores de código de saída específicos. Em seguida, inicialize uma variável global exitCode para o estado de êxito (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;

As funções que contêm casos de erro que devem terminar a aplicação devem devolver uma enumeração ExitCode. Se for atingido um caso de erro que deve terminar a aplicação, devolva o código de saída específico que definiu para esse caso. No exemplo abaixo, a InitPeripheralsAndHandlers função é definida, o que inicializa um LED e um botão. Se a inicialização falhar, é devolvido o valor correspondente ExitCode definido acima.

// 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;
}

Após a inicialização, a aplicação permanece no ciclo principal, desde que a variável global exitCode continue a ser atribuída ao valor de êxito inicial. Se alguma parte da lógica de aplicação principal alguma vez definir a exitCode variável para um valor diferente de êxito, a aplicação sairá do ciclo principal e sairá com o conjunto exitCode. O SO do Azure Sphere irá capturar o evento de saída da aplicação e o código de saída correspondente num relatório de erros e, em seguida, reiniciar a aplicação.

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;
}