libctru  v2.4.1
ptmsysm.h
Go to the documentation of this file.
1 /**
2  * @file ptmsysm.h
3  * @brief PTMSYSM service.
4  */
5 #pragma once
6 
7 #include <3ds/types.h>
8 
9 /// PDN wake events and MCU interrupts to select, combined with those of other processes
10 typedef struct PtmWakeEvents {
11  u32 pdn_wake_events; ///< Written to PDN_WAKE_EVENTS. Don't select bit26 (MCU), PTM will do it automatically.
12  u32 mcu_interupt_mask; ///< MCU interrupts to check when a MCU wake event happens.
14 
15 typedef struct {
16  PtmWakeEvents exit_sleep_events; ///< Wake events for which the system should fully wake up.
17  PtmWakeEvents continue_sleep_events; ///< Wake events for which the system should return to sleep.
19 
20 enum {
21  // Sleep FSM notification IDs
22  PTMNOTIFID_SLEEP_REQUESTED = 0x101, ///< @ref PTMSYSM_RequestSleep has been called (ack = 3)
23  PTMNOTIFID_SLEEP_DENIED = 0x102, ///< The sleep request has been denied by @ref PTMSYSM_ReplyToSleepQuery(true) (no ack required).
24  PTMNOTIFID_SLEEP_ALLOWED = 0x103, ///< The sleep request has been allowed by @ref PTMSYSM_ReplyToSleepQuery(false) (ack = 1).
25  PTMNOTIFID_GOING_TO_SLEEP = 0x104, ///< All processes not having "RunnableOnSleep" have been paused & the system is about to go to sleep (ack = 0).
26  PTMNOTIFID_FULLY_WAKING_UP = 0x105, ///< The system has been woken up, and the paused processes are about to be unpaused (ack = 1).
27  PTMNOTIFID_FULLY_AWAKE = 0x106, ///< The system is fully awake (no ack required).
28  PTMNOTIFID_HALF_AWAKE = 0x107, ///< The system has been woken up but is about to go to sleep again (ack = 2).
29 
30  PTMNOTIFID_SHUTDOWN = 0x108, ///< The system is about to power off or reboot.
31 
32  PTMNOTIFID_BATTERY_VERY_LOW = 0x211, ///< The battery level has reached 5% or below.
33  PTMNOTIFID_BATTERY_LOW = 0x212, ///< The battery level has reached 10% or below.
34 };
35 
36 /// See @ref PTMSYSM_NotifySleepPreparationComplete. Corresponds to the number of potentially remaning notifs. until sleep/wakeup.
38 {
39  static const s32 values[] = { 3, -1, 1, 0, 0, -1, 2 };
40  if (id < PTMNOTIFID_SLEEP_REQUESTED || id > PTMNOTIFID_HALF_AWAKE)
41  return -1;
42  return values[id - PTMNOTIFID_SLEEP_REQUESTED];
43 }
44 
45 /// Initializes ptm:sysm.
47 
48 /// Exits ptm:sysm.
49 void ptmSysmExit(void);
50 
51 /**
52  * @brief Gets a pointer to the current ptm:sysm session handle.
53  * @return A pointer to the current ptm:sysm session handle.
54  */
56 
57 /// Requests to enter sleep mode.
59 
60 /**
61  * @brief Accepts or denies the incoming sleep mode request.
62  * @param deny Whether or not to deny the sleep request.
63  * @note If deny = false, this is equivalent to calling @ref PTMSYSM_NotifySleepPreparationComplete(3)
64  */
66 
67 /**
68  * @brief Acknowledges the current sleep notification and advance the internal sleep mode FSM. All subscribers must reply.
69  * @param ackValue Use @ref ptmSysmGetNotificationAckValue
70  * @note @ref PTMNOTIFID_SLEEP_DENIED and @ref PTMNOTIFID_FULLY_AWAKE don't require this.
71  */
73 
74 /**
75  * @brief Sets the wake events (two sets: when to fully wake up and when to return to sleep).
76  * @param sleepConfig Pointer to the two sets of wake events.
77  * @note Can only be called just before acknowledging @ref PTMNOTIFID_GOING_TO_SLEEP or @ref PTMNOTIFID_HALF_AWAKE.
78  */
80 
81 /**
82  * @brief Gets the wake reason (only the first applicable wake event is taken into account).
83  * @param sleepConfig Pointer to the two sets of wake events. Only the relevant set will be filled.
84  */
86 
87 /// Cancels the "half-awake" state and fully wakes up the 3DS after some delay.
89 
90 /**
91  * @brief Sets the user time by updating the user time offset.
92  * @param msY2k The number of milliseconds since 01/01/2000.
93  */
95 
96 /// Invalidates the "system time" (cfg block 0x30002)
98 
99 /**
100  * @brief Reads the time and date coming from the RTC and converts the result.
101  * @param[out] outMsY2k The pointer to write the number of milliseconds since 01/01/2000 to.
102  */
104 
105 /**
106  * @brief Writes the time and date coming to the RTC, after conversion.
107  * @param msY2k The number of milliseconds since 01/01/2000.
108  */
110 
111 /**
112  * @brief Checks whether the system is a New 3DS.
113  * @param[out] out Pointer to write the New 3DS flag to.
114  */
116 
117 /**
118  * @brief Configures the New 3DS' CPU clock speed and L2 cache.
119  * @param value Bit0: enable higher clock, Bit1: enable L2 cache.
120  */
122 
123 /**
124  * @brief Trigger a hardware system shutdown via the MCU.
125  * @param timeout: timeout passed to PMApp:ShutdownAsync (PrepareForReboot).
126  */
128 
129 /**
130  * @brief Trigger a hardware system reboot via the MCU.
131  * @param timeout: timeout passed to PMApp:ShutdownAsync (PrepareForReboot).
132  */
Result PTMSYSM_RebootAsync(u64 timeout)
Trigger a hardware system reboot via the MCU.
Result PTMSYSM_SetRtcTime(s64 msY2k)
Writes the time and date coming to the RTC, after conversion.
Result ptmSysmInit(void)
Initializes ptm:sysm.
Result PTMSYSM_Awaken(void)
Cancels the "half-awake" state and fully wakes up the 3DS after some delay.
Result PTMSYSM_SetUserTime(s64 msY2k)
Sets the user time by updating the user time offset.
Result PTMSYSM_GetWakeReason(PtmSleepConfig *outSleepConfig)
Gets the wake reason (only the first applicable wake event is taken into account).
Result PTMSYSM_ShutdownAsync(u64 timeout)
Trigger a hardware system shutdown via the MCU.
Result PTMSYSM_GetRtcTime(s64 *outMsY2k)
Reads the time and date coming from the RTC and converts the result.
Result PTMSYSM_CheckNew3DS(bool *out)
Checks whether the system is a New 3DS.
Result PTMSYSM_ReplyToSleepQuery(bool deny)
Accepts or denies the incoming sleep mode request.
Result PTMSYSM_NotifySleepPreparationComplete(s32 ackValue)
Acknowledges the current sleep notification and advance the internal sleep mode FSM.
static s32 ptmSysmGetNotificationAckValue(u32 id)
See PTMSYSM_NotifySleepPreparationComplete. Corresponds to the number of potentially remaning notifs....
Definition: ptmsysm.h:37
Handle * ptmSysmGetSessionHandle(void)
Gets a pointer to the current ptm:sysm session handle.
@ PTMNOTIFID_HALF_AWAKE
The system has been woken up but is about to go to sleep again (ack = 2).
Definition: ptmsysm.h:28
@ PTMNOTIFID_FULLY_AWAKE
The system is fully awake (no ack required).
Definition: ptmsysm.h:27
@ PTMNOTIFID_FULLY_WAKING_UP
The system has been woken up, and the paused processes are about to be unpaused (ack = 1).
Definition: ptmsysm.h:26
@ PTMNOTIFID_SLEEP_REQUESTED
PTMSYSM_RequestSleep has been called (ack = 3)
Definition: ptmsysm.h:22
@ PTMNOTIFID_GOING_TO_SLEEP
All processes not having "RunnableOnSleep" have been paused & the system is about to go to sleep (ack...
Definition: ptmsysm.h:25
@ PTMNOTIFID_SHUTDOWN
The system is about to power off or reboot.
Definition: ptmsysm.h:30
@ PTMNOTIFID_BATTERY_LOW
The battery level has reached 10% or below.
Definition: ptmsysm.h:33
@ PTMNOTIFID_BATTERY_VERY_LOW
The battery level has reached 5% or below.
Definition: ptmsysm.h:32
@ PTMNOTIFID_SLEEP_ALLOWED
The sleep request has been allowed by PTMSYSM_ReplyToSleepQuery(false) (ack = 1).
Definition: ptmsysm.h:24
@ PTMNOTIFID_SLEEP_DENIED
The sleep request has been denied by PTMSYSM_ReplyToSleepQuery(true) (no ack required).
Definition: ptmsysm.h:23
Result PTMSYSM_ConfigureNew3DSCPU(u8 value)
Configures the New 3DS' CPU clock speed and L2 cache.
Result PTMSYSM_RequestSleep(void)
Requests to enter sleep mode.
void ptmSysmExit(void)
Exits ptm:sysm.
Result PTMSYSM_InvalidateSystemTime(void)
Invalidates the "system time" (cfg block 0x30002)
Result PTMSYSM_SetWakeEvents(const PtmSleepConfig *sleepConfig)
Sets the wake events (two sets: when to fully wake up and when to return to sleep).
Definition: ptmsysm.h:15
PtmWakeEvents continue_sleep_events
Wake events for which the system should return to sleep.
Definition: ptmsysm.h:17
PtmWakeEvents exit_sleep_events
Wake events for which the system should fully wake up.
Definition: ptmsysm.h:16
PDN wake events and MCU interrupts to select, combined with those of other processes.
Definition: ptmsysm.h:10
u32 pdn_wake_events
Written to PDN_WAKE_EVENTS. Don't select bit26 (MCU), PTM will do it automatically.
Definition: ptmsysm.h:11
u32 mcu_interupt_mask
MCU interrupts to check when a MCU wake event happens.
Definition: ptmsysm.h:12
Various system types.
int64_t s64
64-bit signed integer
Definition: types.h:29
uint64_t u64
64-bit unsigned integer
Definition: types.h:24
uint8_t u8
would be nice if newlib had this already
Definition: types.h:21
u32 Handle
Resource handle.
Definition: types.h:41
s32 Result
Function result.
Definition: types.h:42
int32_t s32
32-bit signed integer
Definition: types.h:28
uint32_t u32
32-bit unsigned integer
Definition: types.h:23