errf.h
Go to the documentation of this file.
/**
* @file errf.h
* @brief Error Display API
*/
#pragma once
#include <3ds/types.h>
/// Types of errors that can be thrown by err:f.
typedef enum {
ERRF_ERRTYPE_GENERIC = 0, ///< Generic fatal error. Shows miscellaneous info, including the address of the caller
ERRF_ERRTYPE_NAND_DAMAGED = 1, ///< Damaged NAND (CC_ERROR after reading CSR)
ERRF_ERRTYPE_CARD_REMOVED = 2, ///< Game content storage medium (cartridge and/or SD card) ejected. Not logged
ERRF_ERRTYPE_EXCEPTION = 3, ///< CPU or VFP exception
ERRF_ERRTYPE_FAILURE = 4, ///< Fatal error with a message instead of the caller's address
ERRF_ERRTYPE_LOG_ONLY = 5, ///< Log-level failure. Does not display the exception and does not force the system to reboot
} ERRF_ErrType;
/// Types of 'Exceptions' thrown for ERRF_ERRTYPE_EXCEPTION
typedef enum {
ERRF_EXCEPTION_PREFETCH_ABORT = 0, ///< Prefetch Abort
ERRF_EXCEPTION_DATA_ABORT = 1, ///< Data abort
ERRF_EXCEPTION_UNDEFINED = 2, ///< Undefined instruction
ERRF_EXCEPTION_VFP = 3, ///< VFP (floating point) exception.
} ERRF_ExceptionType;
typedef struct {
ERRF_ExceptionType type; ///< Type of the exception. One of the ERRF_EXCEPTION_* values.
u8 reserved[3];
u32 fsr; ///< ifsr (prefetch abort) / dfsr (data abort)
u32 far; ///< pc = ifar (prefetch abort) / dfar (data abort)
u32 fpexc;
u32 fpinst;
u32 fpinst2;
} ERRF_ExceptionInfo;
typedef struct {
ERRF_ExceptionInfo excep; ///< Exception info struct
CpuRegisters regs; ///< CPU register dump.
} ERRF_ExceptionData;
typedef struct {
ERRF_ErrType type; ///< Type, one of the ERRF_ERRTYPE_* enum
u8 revHigh; ///< High revison ID
u16 revLow; ///< Low revision ID
u32 resCode; ///< Result code
u32 pcAddr; ///< PC address at exception
u32 procId; ///< Process ID of the caller
u64 titleId; ///< Title ID of the caller
u64 appTitleId; ///< Title ID of the running application
union {
ERRF_ExceptionData exception_data; ///< Data for when type is ERRF_ERRTYPE_EXCEPTION
char failure_mesg[0x60]; ///< String for when type is ERRF_ERRTYPE_FAILURE
} data; ///< The different types of data for errors.
} ERRF_FatalErrInfo;
/// Initializes ERR:f. Unless you plan to call ERRF_Throw yourself, do not use this.
Result errfInit(void);
/// Exits ERR:f. Unless you plan to call ERRF_Throw yourself, do not use this.
void errfExit(void);
/**
* @brief Gets the current err:f API session handle.
* @return The current err:f API session handle.
*/
Handle *errfGetSessionHandle(void);
/**
* @brief Throws a system error and possibly logs it.
* @param[in] error Error to throw.
*
* ErrDisp may convert the error info to \ref ERRF_ERRTYPE_NAND_DAMAGED or \ref ERRF_ERRTYPE_CARD_REMOVED
* depending on the error code.
*
* Except with \ref ERRF_ERRTYPE_LOG_ONLY, the system will panic and will need to be rebooted.
* Fatal error information will also be logged into a file, unless the type either \ref ERRF_ERRTYPE_NAND_DAMAGED
* or \ref ERRF_ERRTYPE_CARD_REMOVED.
*
* No error will be shown if the system is asleep.
*
* On retail units with vanilla firmware, no detailed information will be displayed on screen.
*
* You may wish to use ERRF_ThrowResult() or ERRF_ThrowResultWithMessage() instead of
* constructing the ERRF_FatalErrInfo struct yourself.
*/
Result ERRF_Throw(const ERRF_FatalErrInfo* error);
/**
* @brief Throws (and logs) a system error with the given Result code.
* @param[in] failure Result code to throw.
*
* This calls \ref ERRF_Throw with error type \ref ERRF_ERRTYPE_GENERIC and fills in the required data.
*
* This function \em does fill in the address where this function was called from.
*/
Result ERRF_ThrowResult(Result failure);
/**
* @brief Logs a system error with the given Result code.
* @param[in] failure Result code to log.
*
* Similar to \ref ERRF_Throw, except that it does not display anything on the screen,
* nor does it force the system to reboot.
*
* This function \em does fill in the address where this function was called from.
*/
Result ERRF_LogResult(Result failure);
/**
* @brief Throws a system error with the given Result code and message.
* @param[in] failure Result code to throw.
* @param[in] message The message to display.
*
* This calls \ref ERRF_Throw with error type \ref ERRF_ERRTYPE_FAILURE and fills in the required data.
*
* This function does \em not fill in the address where this function was called from because it
* would not be displayed.
*/
Result ERRF_ThrowResultWithMessage(Result failure, const char* message);
/**
* @brief Specify an additional user string to use for error reporting.
* @param[in] user_string User string (up to 256 bytes, not including NUL byte)
*/
Result ERRF_SetUserString(const char* user_string);
/**
* @brief Handles an exception using ErrDisp.
* @param excep Exception information
* @param regs CPU registers
*
* You might want to clear ENVINFO's bit0 to be able to see any debugging information.
* @sa threadOnException
*/
void ERRF_ExceptionHandler(ERRF_ExceptionInfo* excep, CpuRegisters* regs) __attribute__((noreturn));
ERRF_ThrowResult
Result ERRF_ThrowResult(Result failure)
Throws (and logs) a system error with the given Result code.
ERRF_SetUserString
Result ERRF_SetUserString(const char *user_string)
Specify an additional user string to use for error reporting.
ERRF_ExceptionHandler
void ERRF_ExceptionHandler(ERRF_ExceptionInfo *excep, CpuRegisters *regs) __attribute__((noreturn))
Handles an exception using ErrDisp.
ERRF_ErrType
ERRF_ErrType
Types of errors that can be thrown by err:f.
Definition: errf.h:11
ERRF_ERRTYPE_LOG_ONLY
@ ERRF_ERRTYPE_LOG_ONLY
Log-level failure. Does not display the exception and does not force the system to reboot.
Definition: errf.h:17
ERRF_ERRTYPE_CARD_REMOVED
@ ERRF_ERRTYPE_CARD_REMOVED
Game content storage medium (cartridge and/or SD card) ejected. Not logged.
Definition: errf.h:14
ERRF_ERRTYPE_EXCEPTION
@ ERRF_ERRTYPE_EXCEPTION
CPU or VFP exception.
Definition: errf.h:15
ERRF_ERRTYPE_GENERIC
@ ERRF_ERRTYPE_GENERIC
Generic fatal error. Shows miscellaneous info, including the address of the caller.
Definition: errf.h:12
ERRF_ERRTYPE_NAND_DAMAGED
@ ERRF_ERRTYPE_NAND_DAMAGED
Damaged NAND (CC_ERROR after reading CSR)
Definition: errf.h:13
ERRF_ERRTYPE_FAILURE
@ ERRF_ERRTYPE_FAILURE
Fatal error with a message instead of the caller's address.
Definition: errf.h:16
errfExit
void errfExit(void)
Exits ERR:f. Unless you plan to call ERRF_Throw yourself, do not use this.
ERRF_ThrowResultWithMessage
Result ERRF_ThrowResultWithMessage(Result failure, const char *message)
Throws a system error with the given Result code and message.
ERRF_LogResult
Result ERRF_LogResult(Result failure)
Logs a system error with the given Result code.
errfGetSessionHandle
Handle * errfGetSessionHandle(void)
Gets the current err:f API session handle.
ERRF_ExceptionType
ERRF_ExceptionType
Types of 'Exceptions' thrown for ERRF_ERRTYPE_EXCEPTION.
Definition: errf.h:21
ERRF_EXCEPTION_UNDEFINED
@ ERRF_EXCEPTION_UNDEFINED
Undefined instruction.
Definition: errf.h:24
ERRF_EXCEPTION_PREFETCH_ABORT
@ ERRF_EXCEPTION_PREFETCH_ABORT
Prefetch Abort.
Definition: errf.h:22
ERRF_EXCEPTION_DATA_ABORT
@ ERRF_EXCEPTION_DATA_ABORT
Data abort.
Definition: errf.h:23
ERRF_EXCEPTION_VFP
@ ERRF_EXCEPTION_VFP
VFP (floating point) exception.
Definition: errf.h:25
ERRF_Throw
Result ERRF_Throw(const ERRF_FatalErrInfo *error)
Throws a system error and possibly logs it.
errfInit
Result errfInit(void)
Initializes ERR:f. Unless you plan to call ERRF_Throw yourself, do not use this.
__attribute__
__attribute__((warn_unused_result)) rbtree_node_t *rbtree_insert(rbtree_t *tree
Inserts a node into an rbtree.
CpuRegisters
Structure representing CPU registers.
Definition: types.h:63
ERRF_ExceptionData
Definition: errf.h:38
ERRF_ExceptionData::regs
CpuRegisters regs
CPU register dump.
Definition: errf.h:40
ERRF_ExceptionData::excep
ERRF_ExceptionInfo excep
Exception info struct.
Definition: errf.h:39
ERRF_ExceptionInfo
Definition: errf.h:28
ERRF_ExceptionInfo::type
ERRF_ExceptionType type
Type of the exception. One of the ERRF_EXCEPTION_* values.
Definition: errf.h:29
ERRF_ExceptionInfo::fsr
u32 fsr
ifsr (prefetch abort) / dfsr (data abort)
Definition: errf.h:31
ERRF_ExceptionInfo::far
u32 far
pc = ifar (prefetch abort) / dfar (data abort)
Definition: errf.h:32
ERRF_FatalErrInfo
Definition: errf.h:43
ERRF_FatalErrInfo::resCode
u32 resCode
Result code.
Definition: errf.h:47
ERRF_FatalErrInfo::revHigh
u8 revHigh
High revison ID.
Definition: errf.h:45
ERRF_FatalErrInfo::appTitleId
u64 appTitleId
Title ID of the running application.
Definition: errf.h:51
ERRF_FatalErrInfo::revLow
u16 revLow
Low revision ID.
Definition: errf.h:46
ERRF_FatalErrInfo::type
ERRF_ErrType type
Type, one of the ERRF_ERRTYPE_* enum.
Definition: errf.h:44
ERRF_FatalErrInfo::pcAddr
u32 pcAddr
PC address at exception.
Definition: errf.h:48
ERRF_FatalErrInfo::procId
u32 procId
Process ID of the caller.
Definition: errf.h:49
ERRF_FatalErrInfo::exception_data
ERRF_ExceptionData exception_data
Data for when type is ERRF_ERRTYPE_EXCEPTION.
Definition: errf.h:53
ERRF_FatalErrInfo::titleId
u64 titleId
Title ID of the caller.
Definition: errf.h:50
types.h
Various system types.
u64
uint64_t u64
64-bit unsigned integer
Definition: types.h:24
u8
uint8_t u8
would be nice if newlib had this already
Definition: types.h:21
Handle
u32 Handle
Resource handle.
Definition: types.h:41
Result
s32 Result
Function result.
Definition: types.h:42
u16
uint16_t u16
16-bit unsigned integer
Definition: types.h:22
u32
uint32_t u32
32-bit unsigned integer
Definition: types.h:23