1 /*---------------------------------------------------------------------------* 2 Project: TwlSDK - RTC - include 3 File: api.h 4 5 Copyright 2003-2008 Nintendo. All rights reserved. 6 7 These coded instructions, statements, and computer programs contain 8 proprietary information of Nintendo of America Inc. and/or Nintendo 9 Company Ltd., and are protected by Federal copyright law. They may 10 not be disclosed to third parties or copied or duplicated in any form, 11 in whole or in part, without the prior written consent of Nintendo. 12 13 $Date:: $ 14 $Rev:$ 15 $Author:$ 16 *---------------------------------------------------------------------------*/ 17 18 #ifndef NITRO_RTC_ARM9_API_H_ 19 #define NITRO_RTC_ARM9_API_H_ 20 21 #ifdef __cplusplus 22 extern "C" { 23 #endif 24 25 /*===========================================================================*/ 26 27 #include <nitro/rtc/common/type.h> 28 #include <nitro/rtc/common/fifo.h> 29 #include <nitro/pxi.h> 30 31 32 /*---------------------------------------------------------------------------* 33 Constant Definitions 34 *---------------------------------------------------------------------------*/ 35 36 // Day of the Week Definitions 37 typedef enum RTCWeek 38 { 39 RTC_WEEK_SUNDAY = 0, // Sunday 40 RTC_WEEK_MONDAY, // Monday 41 RTC_WEEK_TUESDAY, // Tuesday 42 RTC_WEEK_WEDNESDAY, // Wednesday 43 RTC_WEEK_THURSDAY, // Thursday 44 RTC_WEEK_FRIDAY, // Friday 45 RTC_WEEK_SATURDAY, // Saturday 46 RTC_WEEK_MAX 47 } 48 RTCWeek; 49 50 // Alarm Channel Definitions 51 typedef enum RTCAlarmChan 52 { 53 RTC_ALARM_CHAN_1 = 0, // Interrupt channel 1 54 RTC_ALARM_CHAN_2, // Interrupt channel 2 55 RTC_ALARM_CHAN_MAX 56 } 57 RTCAlarmChan; 58 59 // Alarm Status Definitions 60 typedef enum RTCAlarmStatus 61 { 62 RTC_ALARM_STATUS_OFF = 0, // Interrupts disabled status 63 RTC_ALARM_STATUS_ON, // Interrupts enabled status 64 RTC_ALARM_STATUS_MAX 65 } 66 RTCAlarmStatus; 67 68 // Alarm Enable Flag Definitions 69 #define RTC_ALARM_ENABLE_NONE 0x0000 // No enabled flag 70 #define RTC_ALARM_ENABLE_WEEK 0x0001 // Use day of week setting in interrupt determination 71 #define RTC_ALARM_ENABLE_HOUR 0x0002 // Use hour setting in interrupt determination 72 #define RTC_ALARM_ENABLE_MINUTE 0x0004 // Use minute setting in interrupt determination 73 #define RTC_ALARM_ENABLE_ALL ( RTC_ALARM_ENABLE_WEEK | RTC_ALARM_ENABLE_HOUR | RTC_ALARM_ENABLE_MINUTE ) 74 75 // Processing Result Definitions 76 typedef enum RTCResult 77 { 78 RTC_RESULT_SUCCESS = 0, 79 RTC_RESULT_BUSY, 80 RTC_RESULT_ILLEGAL_PARAMETER, 81 RTC_RESULT_SEND_ERROR, 82 RTC_RESULT_INVALID_COMMAND, 83 RTC_RESULT_ILLEGAL_STATUS, 84 RTC_RESULT_FATAL_ERROR, 85 RTC_RESULT_MAX 86 } 87 RTCResult; 88 89 90 /*---------------------------------------------------------------------------* 91 Structure Definitions 92 *---------------------------------------------------------------------------*/ 93 // Callback Function Type Definitions 94 typedef void (*RTCCallback) (RTCResult result, void *arg); 95 typedef void (*RTCInterrupt) (void); 96 97 // Date structure 98 typedef struct RTCDate 99 { 100 u32 year; // Year ( 0 to 99 ) 101 u32 month; // Month ( 1 to 12 ) 102 u32 day; // Day ( 1 to 31 ) 103 RTCWeek week; // Day of the week 104 105 } 106 RTCDate; 107 108 // Time structure 109 typedef struct RTCTime 110 { 111 u32 hour; // Hour ( 0 to 23 ) 112 u32 minute; // Minute ( 0 to 59 ) 113 u32 second; // Second ( 0 to 59 ) 114 115 } 116 RTCTime; 117 118 // Time structure with an added millisecond field 119 typedef struct RTCTimeEx 120 { 121 u32 hour; // Hour ( 0 to 23 ) 122 u32 minute; // Minute ( 0 to 59 ) 123 u32 second; // Second ( 0 to 59 ) 124 u32 millisecond; // Millisecond (0 to 999) 125 } 126 RTCTimeEx; 127 128 // Alarm parameter structure 129 typedef struct RTCAlarmParam 130 { 131 RTCWeek week; // Day of the week 132 u32 hour; // Hour ( 0 to 23 ) 133 u32 minute; // Minute ( 0 to 59 ) 134 u32 enable; // Alarm enable flag ( RTC_ALARM_ENABLE_* ) 135 136 } 137 RTCAlarmParam; 138 139 140 /*---------------------------------------------------------------------------* 141 Function Definitions 142 *---------------------------------------------------------------------------*/ 143 144 /*---------------------------------------------------------------------------* 145 Name: RTC_Init 146 147 Description: Initializes the RTC library. 148 Notice: A power-on check is performed when initializing the component side. 149 150 Arguments: None. 151 152 Returns: None. 153 *---------------------------------------------------------------------------*/ 154 void RTC_Init(void); 155 156 /*---------------------------------------------------------------------------* 157 Name: RTC_GetDate 158 159 Description: Reads date data from the RTC. 160 161 Arguments: date - Specifies the buffer for storing date data. 162 163 Returns: RTCResult - Returns the device operation processing result. 164 *---------------------------------------------------------------------------*/ 165 RTCResult RTC_GetDate(RTCDate *date); 166 167 /*---------------------------------------------------------------------------* 168 Name: RTC_GetTime 169 170 Description: Reads time data from the RTC. 171 172 Arguments: time - Specifies the buffer for storing time data. 173 174 Returns: RTCResult - Returns the device operation processing result. 175 *---------------------------------------------------------------------------*/ 176 RTCResult RTC_GetTime(RTCTime *time); 177 178 /*---------------------------------------------------------------------------* 179 Name: RTC_GetDateTime 180 181 Description: Read date and time data from RTC. 182 183 Arguments: date - Specifies the buffer for storing date data. 184 time - Specifies the buffer for storing time data. 185 186 Returns: RTCResult - Returns the device operation processing result. 187 *---------------------------------------------------------------------------*/ 188 RTCResult RTC_GetDateTime(RTCDate *date, RTCTime *time); 189 190 /*---------------------------------------------------------------------------* 191 Name: RTC_SetDate 192 193 Description: Writes date data to the RTC. 194 195 Arguments: date - Specifies the buffer where date data is stored. 196 197 Returns: RTCResult - Returns the device operation processing result. 198 *---------------------------------------------------------------------------*/ 199 RTCResult RTC_SetDate(const RTCDate *date); 200 201 /*---------------------------------------------------------------------------* 202 Name: RTC_SetTime 203 204 Description: Writes time data to the RTC. 205 206 Arguments: time - Specifies the buffer where time data is stored. 207 208 Returns: RTCResult - Returns the device operation processing result. 209 *---------------------------------------------------------------------------*/ 210 RTCResult RTC_SetTime(const RTCTime *time); 211 212 /*---------------------------------------------------------------------------* 213 Name: RTC_SetDateTime 214 215 Description: Writes date and time data to the RTC. 216 217 Arguments: date - Specifies the buffer where date data is stored. 218 time - Specifies the buffer where time data is stored. 219 220 Returns: RTCResult - Returns the device operation processing result. 221 *---------------------------------------------------------------------------*/ 222 RTCResult RTC_SetDateTime(const RTCDate *date, const RTCTime *time); 223 224 /*---------------------------------------------------------------------------* 225 Name: RTC_GetAlarmStatus 226 227 Description: Reads alarm ON/OFF status from the RTC. 228 229 Arguments: chan - Specifies an alarm channel. 230 status - Specifies a buffer for storing alarm status. 231 232 Returns: RTCResult - Returns the device operation processing result. 233 *---------------------------------------------------------------------------*/ 234 RTCResult RTC_GetAlarmStatus(RTCAlarmChan chan, RTCAlarmStatus *status); 235 236 /*---------------------------------------------------------------------------* 237 Name: RTC_GetAlarmParam 238 239 Description: Reads alarm setting values from the RTC. 240 241 Arguments: chan - Specifies an alarm channel. 242 param - Specifies a buffer for storing alarm setting values. 243 244 Returns: RTCResult - Returns the device operation processing result. 245 *---------------------------------------------------------------------------*/ 246 RTCResult RTC_GetAlarmParam(RTCAlarmChan chan, RTCAlarmParam *param); 247 248 /*---------------------------------------------------------------------------* 249 Name: RTC_SetAlarmStatus 250 251 Description: Writes alarm status to the RTC. 252 253 Arguments: chan - Specifies an alarm channel. 254 status - Specifies the buffer where alarm status is stored. 255 256 Returns: RTCResult - Returns the device operation processing result. 257 *---------------------------------------------------------------------------*/ 258 RTCResult RTC_SetAlarmStatus(RTCAlarmChan chan, const RTCAlarmStatus *status); 259 260 /*---------------------------------------------------------------------------* 261 Name: RTC_SetAlarmParam 262 263 Description: Writes alarm setting values to the RTC. 264 265 Arguments: chan - Specifies an alarm channel. 266 param - Specifies the buffer where alarm setting values are stored. 267 268 Returns: RTCResult - Returns the device operation processing result. 269 *---------------------------------------------------------------------------*/ 270 RTCResult RTC_SetAlarmParam(RTCAlarmChan chan, const RTCAlarmParam *param); 271 272 /*---------------------------------------------------------------------------* 273 Name: RTC_GetDateAsync 274 275 Description: Asynchronously reads date data from the RTC. 276 277 Arguments: date - Specifies the buffer for storing date data. 278 callback - Specifies the function to be called when the asynchronous process is completed. 279 arg - Specifies the argument used when calling the callback function. 280 281 Returns: RTCResult - Returns the result of the process that starts the asynchronous device operation. 282 *---------------------------------------------------------------------------*/ 283 RTCResult RTC_GetDateAsync(RTCDate *date, RTCCallback callback, void *arg); 284 285 /*---------------------------------------------------------------------------* 286 Name: RTC_GetTimeAsync 287 288 Description: Asynchronously reads time data from the RTC. 289 290 Arguments: time - Specifies the buffer for storing time data. 291 callback - Specifies the function to be called when the asynchronous process is completed. 292 arg - Specifies the argument used when calling the callback function. 293 294 Returns: RTCResult - Returns the result of the process that starts the asynchronous device operation. 295 *---------------------------------------------------------------------------*/ 296 RTCResult RTC_GetTimeAsync(RTCTime *time, RTCCallback callback, void *arg); 297 298 /*---------------------------------------------------------------------------* 299 Name: RTC_GetDateTimeAsync 300 301 Description: Asynchronously reads date and time data from the RTC. 302 303 Arguments: date - Specifies the buffer for storing date data. 304 time - Specifies the buffer for storing time data. 305 callback - Specifies the function to be called when the asynchronous process is completed. 306 arg - Specifies the argument used when calling the callback function. 307 308 Returns: RTCResult - Returns the result of the process that starts the asynchronous device operation. 309 *---------------------------------------------------------------------------*/ 310 RTCResult RTC_GetDateTimeAsync(RTCDate *date, RTCTime *time, RTCCallback callback, void *arg); 311 312 /*---------------------------------------------------------------------------* 313 Name: RTC_SetDateAsync 314 315 Description: Asynchronously writes date data to the RTC. 316 317 Arguments: date - Specifies the buffer where date data is stored. 318 callback - Specifies the function to be called when the asynchronous process is completed. 319 arg - Specifies the argument used when calling the callback function. 320 321 Returns: RTCResult - Returns the result of the process that starts the asynchronous device operation. 322 *---------------------------------------------------------------------------*/ 323 RTCResult RTC_SetDateAsync(const RTCDate *date, RTCCallback callback, void *arg); 324 325 /*---------------------------------------------------------------------------* 326 Name: RTC_SetTimeAsync 327 328 Description: Asynchronously writes time data to the RTC. 329 330 Arguments: time - Specifies the buffer where time data is stored. 331 callback - Specifies the function to be called when the asynchronous process is completed. 332 arg - Specifies the argument used when calling the callback function. 333 334 Returns: RTCResult - Returns the result of the process that starts the asynchronous device operation. 335 *---------------------------------------------------------------------------*/ 336 RTCResult RTC_SetTimeAsync(const RTCTime *time, RTCCallback callback, void *arg); 337 338 /*---------------------------------------------------------------------------* 339 Name: RTC_SetDateTimeAsync 340 341 Description: Asynchronously writes date and time data to the RTC. 342 343 Arguments: date - Specifies the buffer where date data is stored. 344 time - Specifies the buffer where time data is stored. 345 callback - Specifies the function to be called when the asynchronous process is completed. 346 arg - Specifies the argument used when calling the callback function. 347 348 Returns: RTCResult - Returns the result of the process that starts the asynchronous device operation. 349 *---------------------------------------------------------------------------*/ 350 RTCResult RTC_SetDateTimeAsync(const RTCDate *date, const RTCTime *time, RTCCallback callback, 351 void *arg); 352 353 /*---------------------------------------------------------------------------* 354 Name: RTC_GetAlarmStatusAsync 355 356 Description: Asynchronously reads alarm ON/OFF status from the RTC. 357 358 Arguments: chan - Specifies an alarm channel. 359 status - Specifies a buffer for storing alarm status. 360 callback - Specifies the function to be called when the asynchronous process is completed. 361 arg - Specifies the argument used when calling the callback function. 362 363 Returns: RTCResult - Returns the result of the process that starts the asynchronous device operation. 364 *---------------------------------------------------------------------------*/ 365 RTCResult RTC_GetAlarmStatusAsync(RTCAlarmChan chan, RTCAlarmStatus *status, RTCCallback callback, 366 void *arg); 367 368 /*---------------------------------------------------------------------------* 369 Name: RTC_GetAlarmParamAsync 370 371 Description: Asynchronously reads alarm setting values from the RTC. 372 373 Arguments: chan - Specifies an alarm channel. 374 param - Specifies a buffer for storing alarm setting values. 375 callback - Specifies the function to be called when the asynchronous process is completed. 376 arg - Specifies the argument used when calling the callback function. 377 378 Returns: RTCResult - Returns the result of the process that starts the asynchronous device operation. 379 *---------------------------------------------------------------------------*/ 380 RTCResult RTC_GetAlarmParamAsync(RTCAlarmChan chan, RTCAlarmParam *param, RTCCallback callback, 381 void *arg); 382 383 /*---------------------------------------------------------------------------* 384 Name: RTC_SetAlarmInterrupt 385 386 Description: Sets the callback function for when an alarm interrupt is generated. 387 388 Arguments: interrupt - Specifies a callback function. 389 390 Returns: None. 391 *---------------------------------------------------------------------------*/ 392 void RTC_SetAlarmInterrupt(RTCInterrupt interrupt); 393 394 /*---------------------------------------------------------------------------* 395 Name: RTC_SetAlarmStatusAsync 396 397 Description: Asynchronously writes alarm status to the RTC. 398 399 Arguments: chan - Specifies an alarm channel. 400 status - Specifies the buffer where alarm status is stored. 401 callback - Specifies the function to be called when the asynchronous process is completed. 402 arg - Specifies the argument used when calling the callback function. 403 404 Returns: RTCResult - Returns the result of the process that starts the asynchronous device operation. 405 *---------------------------------------------------------------------------*/ 406 RTCResult RTC_SetAlarmStatusAsync(RTCAlarmChan chan, const RTCAlarmStatus *status, 407 RTCCallback callback, void *arg); 408 409 /*---------------------------------------------------------------------------* 410 Name: RTC_SetAlarmParamAsync 411 412 Description: Asynchronously writes alarm settings to the RTC. 413 Notice: Write will fail if the RTC alarm status is not ON, because the device side will not accept write. 414 415 416 Arguments: chan - Specifies an alarm channel. 417 param - Specifies the buffer where alarm setting values are stored. 418 callback - Specifies the function to be called when the asynchronous process is completed. 419 arg - Specifies the argument used when calling the callback function. 420 421 Returns: RTCResult - Returns the result of the process that starts the asynchronous device operation. 422 *---------------------------------------------------------------------------*/ 423 RTCResult RTC_SetAlarmParamAsync(RTCAlarmChan chan, const RTCAlarmParam *param, 424 RTCCallback callback, void *arg); 425 426 427 /*---------------------------------------------------------------------------* 428 Definitions of Private Functions 429 *---------------------------------------------------------------------------*/ 430 BOOL RTCi_ResetAsync(void); 431 BOOL RTCi_SetHourFormatAsync(void); 432 BOOL RTCi_ReadRawDateTimeAsync(void); 433 BOOL RTCi_WriteRawDateTimeAsync(void); 434 BOOL RTCi_ReadRawDateAsync(void); 435 BOOL RTCi_WriteRawDateAsync(void); 436 BOOL RTCi_ReadRawTimeAsync(void); 437 BOOL RTCi_WriteRawTimeAsync(void); 438 BOOL RTCi_ReadRawPulseAsync(void); 439 BOOL RTCi_WriteRawPulseAsync(void); 440 BOOL RTCi_ReadRawAlarm1Async(void); 441 BOOL RTCi_WriteRawAlarm1Async(void); 442 BOOL RTCi_ReadRawAlarm2Async(void); 443 BOOL RTCi_WriteRawAlarm2Async(void); 444 BOOL RTCi_ReadRawStatus1Async(void); 445 BOOL RTCi_WriteRawStatus1Async(void); 446 BOOL RTCi_ReadRawStatus2Async(void); 447 BOOL RTCi_WriteRawStatus2Async(void); 448 BOOL RTCi_ReadRawAdjustAsync(void); 449 BOOL RTCi_WriteRawAdjustAsync(void); 450 BOOL RTCi_ReadRawFreeAsync(void); 451 BOOL RTCi_WriteRawFreeAsync(void); 452 RTCResult RTCi_SetRegStatus2Async(const RTCRawStatus2 *status2, RTCCallback callback, void *arg); 453 RTCResult RTCi_SetRegAdjustAsync(const RTCRawAdjust *adjust, RTCCallback callback, void *arg); 454 RTCResult RTCi_SetRegAdjust(const RTCRawAdjust *Adjust); 455 RTCResult RTCi_SetRegStatus2(const RTCRawStatus2 *status2); 456 457 458 /*===========================================================================*/ 459 460 #ifdef __cplusplus 461 } /* extern "C" */ 462 #endif 463 464 #endif /* NITRO_RTC_ARM9_API_H_ */ 465 466 /*---------------------------------------------------------------------------* 467 End of file 468 *---------------------------------------------------------------------------*/ 469