KallistiOS git master
Independent SDK for the Sega Dreamcast
Loading...
Searching...
No Matches
trap.h
Go to the documentation of this file.
1/* KallistiOS ##version##
2
3 arch/dreamcast/include/arch/trap.h
4 Copyright (C) 2024 Falco Girgis
5
6*/
7
8/** \file arch/trap.h
9 \brief Interrupt and exception handling.
10 \ingroup traps
11
12 This file contains various definitions and declarations related to handling
13 trap events, as are invoked through the `TRAPA` instruction.
14
15 \author Falco Girgis
16
17 \see arch/irq.h, dc/asic.h
18
19 \todo
20 - state management, propagation
21 - TRAPA instruction inline ASM
22 - document reserved TRAP codes
23*/
24
25#ifndef __ARCH_TRAP_H
26#define __ARCH_TRAP_H
27
28#include <stdint.h>
29
30#include <arch/irq.h>
31#include <sys/cdefs.h>
32__BEGIN_DECLS
33
34/** \defgroup traps Traps
35 \brief API for managing TRAPA events and handlers.
36 \ingroup system
37
38 This API provides methods for setting and getting the installed handler for
39 a particular `TRAPA` code.
40
41 `TRAPA` is an SH4 instruction which simply takes a code (0-255) and fires
42 an exception event which transfers execution to the kernel so that it can
43 then be handled in software.
44
45 @{
46*/
47
48/** Type for a code passed to the `TRAPA` instruction. */
49typedef uint8_t trapa_t;
50
51/** \defgroup irq_trapa_handler Handlers
52 \brief API for managing TRAPA handlers
53
54 This API allows for the setting and retrieving of a handler associated with
55 a particular `TRAPA` value.
56
57 @{
58*/
59
60/** The type of a TRAPA handler
61
62 \param code The IRQ that caused the handler to be called.
63 \param context The CPU's context.
64 \param data Arbitrary userdata associated with the handler.
65*/
66typedef void (*trapa_handler)(trapa_t code, irq_context_t *context, void *data);
67
68/** Set or remove a handler for a trapa code.
69
70 \param code The value passed to the trapa opcode.
71 \param hnd A pointer to the procedure to handle the trap.
72 \param data A pointer that will be passed along to the callback.
73
74 \retval 0 On success.
75
76 \sa trapa_get_handler()
77*/
78int trapa_set_handler(trapa_t code, trapa_handler hnd, void *data);
79
80/** Get an existing TRAPA handler.
81
82 \param trap The value passed to the trapa opcode.
83 \param data A pointer to a void* which will be filled in with
84 the handler's userdata, or NULL if not interested.
85
86 \return A pointer to the procedure to handle the TRAP code.
87
88 \sa trapa_set_handler()
89*/
91
92/** @} */
93
94/** @} */
95
96__END_DECLS
97
98#endif /* __ARCH_TRAP_H */
trapa_handler trapa_get_handler(trapa_t code, void **data)
Get an existing TRAPA handler.
int trapa_set_handler(trapa_t code, trapa_handler hnd, void *data)
Set or remove a handler for a trapa code.
void(* trapa_handler)(trapa_t code, irq_context_t *context, void *data)
The type of a TRAPA handler.
Definition trap.h:66
uint8_t trapa_t
Type for a code passed to the TRAPA instruction.
Definition trap.h:49
Interrupt and exception handling.
Architecture-specific structure for holding the processor state.
Definition irq.h:91