Shutdown Notifications

Topics
	ShutdownReasons
	Shutdown Reasons #include< ShutDownNotifications.h > .

Functions
bool	NBApproveShutdown (int reason)
	Approve action that will result in a reboot.
void	NBFaultNotify ()
	Emergency notification of a fault shutdown.

Detailed Description

#include< ShutDownNotifications.h >

The NBApproveShutdown callback function can be used by an application to put the system in a safe state before an application update, configuration update, or reboot event occurs. For example, closing active TCP sockets, ensuring Flash and/or file system write operations are complete, and putting critical peripherals in a safe state. The NBApproveShutdown() function as a weak reference to a system function that always returns true by default. If an application creates its own function using the same signature, that function will be used instead.

A reason for the reboot request is passed to the function. The system will automatically call NBapproveShutdown() for the following reasons:

#define SHUTDOWN_CODEUPDATE         (1)   // A code update is requested
#define SHUTDOWN_CONFIGURE_REBOOT   (2)   // Configuration values have been modified with a requested reboot

An application can choose to ignore the parameters or add its own. For custom reasons, the application should call NBApproveShutdown() with the appropriate reason:

// Custom reboot reason. System reasons start at 1, so pick something much larger
#define SHUTDOWN_CUSTOM_REBOOT 100
 
if( NBApproveShutdown(SHUTDOWN_CUSTOM_REBOOT))
{
  OSTimeDly(TICKS_PER_SECOND * 5);
  ForceReboot();
}

Function Documentation

NBApproveShutdown()

bool NBApproveShutdown

(

int

reason

)

#include <ShutDownNotifications.h>

Approve action that will result in a reboot.

Note

Called for application updates or configuration changes that include the reboot option

This function will be called when the configuration values have changed with the option to reboot, or for an application update (always requires a reboot).

If the process fails at some time after this notification is approved, the system may not execute a reboot. This function is satisfied as a weak reference in the NetBurner library. In order to use it in your application, create a function of the same name (callback function).

Parameters

reason

The reason for the shutdown request (ShutdownReasons )

Return values

true	Ok to proceed with the modification and reboot
false	Abort the update

NBFaultNotify()

void NBFaultNotify

(

)

#include <ShutDownNotifications.h>

Emergency notification of a fault shutdown.

Note

Called after a critical error, such as a trap or memory fault before a reboot

If the system has a critical fault of some kind it will call this function before rebooting. Since this is a sever critical fault, the function is being called in an exception context with a very small stack. It should execute whatever is necessary and return immediately with a minimal number of variables.

It is extremely limited in the actions it can perform. It cannot execute:

• Any RTOS functions
• printf family functions
• Writes to network sockets
• TCP or UDP functions
• Writes to serial ports
• RTOS delay functions
• Writes to Flash memory
• File system operations

Since this is a critical fault condition and the system is unstable, writing directly to I/O registers has the most chance of success.