libctru  v1.6.0
errf.h
Go to the documentation of this file.
1 /**
2  * @file errf.h
3  * @brief Error Display API
4  */
5 
6 #pragma once
7 
8 #include <3ds/types.h>
9 
10 /// Types of errors that can be thrown by err:f.
11 typedef enum {
12  ERRF_ERRTYPE_GENERIC = 0, ///< For generic errors. Shows miscellaneous info.
13  ERRF_ERRTYPE_MEM_CORRUPT = 1, ///< Same output as generic, but informs the user that "the System Memory has been damaged".
14  ERRF_ERRTYPE_CARD_REMOVED = 2, ///< Displays the "The Game Card was removed." message.
15  ERRF_ERRTYPE_EXCEPTION = 3, ///< For exceptions, or more specifically 'crashes'. union data should be exception_data.
16  ERRF_ERRTYPE_FAILURE = 4, ///< For general failure. Shows a message. union data should have a string set in failure_mesg
17  ERRF_ERRTYPE_LOGGED = 5, ///< Outputs logs to NAND in some cases.
18 } ERRF_ErrType;
19 
20 /// Types of 'Exceptions' thrown for ERRF_ERRTYPE_EXCEPTION
21 typedef enum {
22  ERRF_EXCEPTION_PREFETCH_ABORT = 0, ///< Prefetch Abort
23  ERRF_EXCEPTION_DATA_ABORT = 1, ///< Data abort
24  ERRF_EXCEPTION_UNDEFINED = 2, ///< Undefined instruction
25  ERRF_EXCEPTION_VFP = 3, ///< VFP (floating point) exception.
27 
28 typedef struct {
29  ERRF_ExceptionType type; ///< Type of the exception. One of the ERRF_EXCEPTION_* values.
30  u8 reserved[3];
31  u32 fsr; ///< ifsr (prefetch abort) / dfsr (data abort)
32  u32 far; ///< pc = ifar (prefetch abort) / dfar (data abort)
33  u32 fpexc;
34  u32 fpinst;
35  u32 fpinst2;
37 
38 typedef struct {
39  ERRF_ExceptionInfo excep; ///< Exception info struct
40  CpuRegisters regs; ///< CPU register dump.
42 
43 typedef struct {
44  ERRF_ErrType type; ///< Type, one of the ERRF_ERRTYPE_* enum
45  u8 revHigh; ///< High revison ID
46  u16 revLow; ///< Low revision ID
47  u32 resCode; ///< Result code
48  u32 pcAddr; ///< PC address at exception
49  u32 procId; ///< Process ID.
50  u64 titleId; ///< Title ID.
51  u64 appTitleId; ///< Application Title ID.
52  union {
53  ERRF_ExceptionData exception_data; ///< Data for when type is ERRF_ERRTYPE_EXCEPTION
54  char failure_mesg[0x60]; ///< String for when type is ERRF_ERRTYPE_FAILURE
55  } data; ///< The different types of data for errors.
57 
58 /// Initializes ERR:f. Unless you plan to call ERRF_Throw yourself, do not use this.
59 Result errfInit(void);
60 
61 /// Exits ERR:f. Unless you plan to call ERRF_Throw yourself, do not use this.
62 void errfExit(void);
63 
64 /**
65  * @brief Gets the current err:f API session handle.
66  * @return The current err:f API session handle.
67  */
69 
70 /**
71  * @brief Throws a system error and possibly results in ErrDisp triggering.
72  * @param[in] error Error to throw.
73  *
74  * After performing this, the system may panic and need to be rebooted. Extra information will be displayed on the
75  * top screen with a developer console or the proper patches in a CFW applied.
76  *
77  * The error may not be shown and execution aborted until errfExit(void) is called.
78  *
79  * You may wish to use ERRF_ThrowResult() or ERRF_ThrowResultWithMessage() instead of
80  * constructing the ERRF_FatalErrInfo struct yourself.
81  */
82 Result ERRF_Throw(const ERRF_FatalErrInfo* error);
83 
84 /**
85  * @brief Throws a system error with the given Result code.
86  * @param[in] failure Result code to throw.
87  *
88  * This calls ERRF_Throw() with error type ERRF_ERRTYPE_GENERIC and fills in the required data.
89  *
90  * This function \em does fill in the address where this function was called from.
91  *
92  * See https://3dbrew.org/wiki/ERR:Throw#Generic for expected top screen output
93  * on development units/patched ErrDisp.
94  */
96 
97 /**
98  * @brief Throws a system error with the given Result code and message.
99  * @param[in] failure Result code to throw.
100  * @param[in] message The message to display.
101  *
102  * This calls ERRF_Throw() with error type ERRF_ERRTYPE_FAILURE and fills in the required data.
103  *
104  * This function does \em not fill in the address where this function was called from because it
105  * would not be displayed.
106  *
107  * The message is only displayed on development units/patched ErrDisp.
108  *
109  * See https://3dbrew.org/wiki/ERR:Throw#Result_Failure for expected top screen output
110  * on development units/patched ErrDisp.
111  */
112 Result ERRF_ThrowResultWithMessage(Result failure, const char* message);
113 
114 /**
115  * @brief Handles an exception using ErrDisp.
116  * @param excep Exception information
117  * @param regs CPU registers
118  *
119  * You might want to clear ENVINFO's bit0 to be able to see any debugging information.
120  * @sa threadOnException
121  */
Data abort.
Definition: errf.h:23
Outputs logs to NAND in some cases.
Definition: errf.h:17
For general failure. Shows a message. union data should have a string set in failure_mesg.
Definition: errf.h:16
Result ERRF_ThrowResult(Result failure)
Throws a system error with the given Result code.
Various system types.
s32 Result
Function result.
Definition: types.h:42
uint16_t u16
16-bit unsigned integer
Definition: types.h:22
u32 fsr
ifsr (prefetch abort) / dfsr (data abort)
Definition: errf.h:31
CpuRegisters regs
CPU register dump.
Definition: errf.h:40
u32 procId
Process ID.
Definition: errf.h:49
ERRF_ExceptionType type
Type of the exception. One of the ERRF_EXCEPTION_* values.
Definition: errf.h:29
u32 Handle
Resource handle.
Definition: types.h:41
Result ERRF_Throw(const ERRF_FatalErrInfo *error)
Throws a system error and possibly results in ErrDisp triggering.
uint8_t u8
would be nice if newlib had this already
Definition: types.h:21
void errfExit(void)
Exits ERR:f. Unless you plan to call ERRF_Throw yourself, do not use this.
Structure representing CPU registers.
Definition: types.h:63
Result errfInit(void)
Initializes ERR:f. Unless you plan to call ERRF_Throw yourself, do not use this.
uint64_t u64
64-bit unsigned integer
Definition: types.h:24
u32 resCode
Result code.
Definition: errf.h:47
u16 revLow
Low revision ID.
Definition: errf.h:46
ERRF_ExceptionInfo excep
Exception info struct.
Definition: errf.h:39
Prefetch Abort.
Definition: errf.h:22
uint32_t u32
32-bit unsigned integer
Definition: types.h:23
Definition: errf.h:43
Handle * errfGetSessionHandle(void)
Gets the current err:f API session handle.
ERRF_ErrType
Types of errors that can be thrown by err:f.
Definition: errf.h:11
ERRF_ExceptionData exception_data
Data for when type is ERRF_ERRTYPE_EXCEPTION.
Definition: errf.h:53
u32 far
pc = ifar (prefetch abort) / dfar (data abort)
Definition: errf.h:32
ERRF_ExceptionType
Types of 'Exceptions' thrown for ERRF_ERRTYPE_EXCEPTION.
Definition: errf.h:21
For exceptions, or more specifically 'crashes'. union data should be exception_data.
Definition: errf.h:15
u64 appTitleId
Application Title ID.
Definition: errf.h:51
u8 revHigh
High revison ID.
Definition: errf.h:45
Displays the "The Game Card was removed." message.
Definition: errf.h:14
Result ERRF_ThrowResultWithMessage(Result failure, const char *message)
Throws a system error with the given Result code and message.
Definition: errf.h:28
void ERRF_ExceptionHandler(ERRF_ExceptionInfo *excep, CpuRegisters *regs) __attribute__((noreturn))
Handles an exception using ErrDisp.
u32 pcAddr
PC address at exception.
Definition: errf.h:48
__attribute__((warn_unused_result)) rbtree_node_t *rbtree_insert(rbtree_t *tree
Inserts a node into an rbtree.
Definition: errf.h:38
u64 titleId
Title ID.
Definition: errf.h:50
Undefined instruction.
Definition: errf.h:24
VFP (floating point) exception.
Definition: errf.h:25
For generic errors. Shows miscellaneous info.
Definition: errf.h:12
ERRF_ErrType type
Type, one of the ERRF_ERRTYPE_* enum.
Definition: errf.h:44
Same output as generic, but informs the user that "the System Memory has been damaged".
Definition: errf.h:13