Nano-RK

= Error Handling =

Nano-RK uses the convention that system calls return -1 upon error and 1 upon success.

NRK_OK 1

NRK_ERROR -1

=== _nrk_errno_set ===

	void _nrk_errno_set( NRK_ERRNO error_code )
	''Parameters'': NRK_ERRNO error code to set
	''Return Values:'' none

This function should be used by user defined system calls to set an error number.

=== nrk_errno_get === || uint8_t nrk_errno_get( ) || || ''Parameters'': none|| || ''Return Values:'' uint8_t error code last set for current task ||
Once a function returns failure (-1), this function can be used to get a more descriptive error code.

'''Kernel Errors'''

Kernel errors are triggered when various OS services fail. There are various flags in nrk_cfg.h that govern how the system responds to errors:

• NRK_REPORT_ERRORS * Print error messages. Usually this should be disabled in final deployments.
• NRK_HALT_ON_ERROR * Halt execution and print a single error message
• NRK_HALT_AND_LOOP_ON_ERROR * Halt execution and prints error in a loop
• NRK_LOG_ERROR * Not yet implemented. Will store error log to MMC card.
• NRK_WATCHDOG * Enable the watchdog timer in case a kernel service hangs during a deployment

{{{
#!c
// NRK_REPORT_ERRORS will cause the kernel to print out information about
// missed deadlines or reserve violations
#define NRK_REPORT_ERRORS
}}}

{{{
#!c
// NRK_HALT_ON_ERRORS will cause the kernel to freeze on errors so that
// it is easier to see debugging messages.
#define NRK_HALT_ON_ERROR
}}}

{{{
#!c
// NRK_HALT_AND_LOOP_ON_ERRORS will cause the kernel to freeze on errors but continue
// to print the panic message in a loop so that the node can be plugged into a terminal
// in order to indentify the problem.
#define NRK_HALT_AND_LOOP_ON_ERROR
}}}

*NRK ERROR: ERROR_MESSAGE

''task_id'' is the ID of the task that caused the error. 0 means the kernel had an internal error.

• "Task Stack Overflow" * The canary value in the identified task was over written. Try making the task stack size larger.
• "Reserve Error in Scheduler"
• "Task Reserve Violated" * Increase the reservation for the task, or disable a task reserve by setting it to 0
• "Scheduler Missed Wakeup" * See Timer Overflow
• "Duplicated Task ID" * There is a problem with the way the tasks are being configured
• "Unexpected Restart"
• "Idle or Kernel Stack Overflow"
• "Extra Task started, is nrk_cfg.h ok?" * Most likely NRK_MAX_TASKS in nrk_cfg.h needs to be larger
• "Low Voltage"
• "Unhandled Interrupt Vector"
• "Timer Overflow" * This is likely a problem in the kernel. It can happen if the fuses get cleared such that the ASYNC clock is now operating differently. It can also happen if NRK_SLEEP_WAKEUP_TIME in [http://www.nanork.org/nano-RK/browser/nano-RK/src/platform/firefly2_2/include/nrk_platform_time.h nrk_platform_time.h] is set too low. NRK_SLEEP_WAKEUP_TIME is the max number of ms required for the processor to wake from deep sleep.
• "Device Driver Error"
• "Failed to create Signal"
• "Failed to create Semaphore" * An internal OS related operation failed to create a semaphore. This is probably because ''NRK_MAX_RESOURCE_CNT'' needs to be increased for some functionality the application is trying to use.
• "Kernel function not implemented"
• "UNKOWN"

=== nrk_kernel_error_add ===

	void nrk_kernel_error( Kernel_Panic_ID, uint8_t task_ID )
	''Parameters'': Kernel_Panic_ID is a #define kernel panic id
	''Parameters'': uint8_t task_ID is the PID of the offending task
	''Return Values:'' none

This function is called from within kernel code to post kernel panics. This can be used by applications in cases of a hoplessly fatal error (this should rarely be the case though).

{{{
#!c
nrk_kernel_error_add( NRK_SIGNAL_CREATE_ERROR ,nrk_cur_task_TCB->task_ID);
}}}

=== Kernel Watchdog Timer ===

For final deployments, you may wish to enable extra protection against the system halting by using a watchdog timer. After including NRK_WATCHDOG in the nrk_cfg.h file, the system watchdog timer will be enabled at bootup and set each time the Nano-RK scheduler executes. Under normal operation, application tasks will be bounded by their reservations. If a part of the OS fails to exit within 8 seconds, the system will reboot. Upon restart, a watchdog kernel panic is triggered. When NRK_HALT_ON_ERROR or NRK_HALT_AND_LOOP_ON_ERROR is enabled, the watchdog timer is disabled upon an error so as to not interfere with the normal error printing operation.

{{{
#!c
// Enable the watchdog as a protective measure
// This will only activate if the scheduler fails.
#define NRK_WATCHDOG
}}}