summaryrefslogtreecommitdiffstats
path: root/cpukit/include/rtems/score/todimpl.h
blob: ce75ff681f9e7eda60c9955ed1ff0b5bb3ff1f42 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
/* SPDX-License-Identifier: BSD-2-Clause */

/**
 * @file
 *
 * @ingroup RTEMSScoreTOD
 * @ingroup RTEMSScoreTODHooks
 *
 * @brief This header file provides the interfaces of the
 *   @ref RTEMSScoreTOD and the @ref RTEMSScoreTODHooks.
 */

/*
 *  COPYRIGHT (c) 1989-2009.
 *  On-Line Applications Research Corporation (OAR).
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 * 1. Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 * 2. Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in the
 *    documentation and/or other materials provided with the distribution.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 * POSSIBILITY OF SUCH DAMAGE.
 */

#ifndef _RTEMS_SCORE_TODIMPL_H
#define _RTEMS_SCORE_TODIMPL_H

#include <rtems/score/status.h>
#include <rtems/score/timestamp.h>
#include <rtems/score/timecounterimpl.h>
#include <rtems/score/watchdog.h>
#include <rtems/score/watchdogticks.h>

#include <sys/time.h>
#include <time.h>

#ifdef __cplusplus
extern "C" {
#endif

/**
 * @defgroup RTEMSScoreTOD Time of Day Handler
 *
 * @ingroup RTEMSScore
 *
 * @brief This group contains the Time of Day Handler implementation.
 *
 * The following constants are related to the time of day and are
 * independent of RTEMS.
 *
 * @{
 */

/**
 *  This constant represents the number of seconds in a minute.
 */
#define TOD_SECONDS_PER_MINUTE (uint32_t)60

/**
 *  This constant represents the number of minutes per hour.
 */
#define TOD_MINUTES_PER_HOUR   (uint32_t)60

/**
 *  This constant represents the number of months in a year.
 */
#define TOD_MONTHS_PER_YEAR    (uint32_t)12

/**
 *  This constant represents the number of days in a non-leap year.
 */
#define TOD_DAYS_PER_YEAR      (uint32_t)365

/**
 *  This constant represents the number of hours per day.
 */
#define TOD_HOURS_PER_DAY      (uint32_t)24

/**
 *  This constant represents the number of seconds in a day which does
 *  not include a leap second.
 */
#define TOD_SECONDS_PER_DAY    (uint32_t) (TOD_SECONDS_PER_MINUTE * \
                                TOD_MINUTES_PER_HOUR   * \
                                TOD_HOURS_PER_DAY)

/**
 *  This constant represents the number of seconds in a non-leap year.
 */
#define TOD_SECONDS_PER_NON_LEAP_YEAR (365 * TOD_SECONDS_PER_DAY)

/**
 *  This constant represents the number of millisecond in a second.
 */
#define TOD_MILLISECONDS_PER_SECOND     (uint32_t)1000

/**
 *  This constant represents the number of microseconds in a second.
 */
#define TOD_MICROSECONDS_PER_SECOND     (uint32_t)1000000

/**
 *  This constant represents the number of nanoseconds in a second.
 */
#define TOD_NANOSECONDS_PER_SECOND      (uint32_t)1000000000

/**
 *  This constant represents the number of nanoseconds in a mircosecond.
 */
#define TOD_NANOSECONDS_PER_MICROSECOND (uint32_t)1000

/**@}*/

/**
 *  Seconds from January 1, 1970 to January 1, 1988.  Used to account for
 *  differences between POSIX API and RTEMS core. The timespec format time
 *  is kept in POSIX compliant form.
 */
#define TOD_SECONDS_1970_THROUGH_1988 \
  (((1987 - 1970 + 1)  * TOD_SECONDS_PER_NON_LEAP_YEAR) + \
  (4 * TOD_SECONDS_PER_DAY))

/**
 * @brief Seconds from 1970-01-01T00:00:00Z to 2400-01-01T00:00:00Z.
 *
 * This is the latest time of day which should be set by _TOD_Set().  The year
 * 2400 was chosen to guarantee a defined CLOCK_REALTIME within the range of a
 * system uptime of about 114 years.
 */
#define TOD_SECONDS_1970_THROUGH_2400 13569465600

/**
 *  @brief Earliest year to which an time of day can be initialized.
 *
 *  The following constant define the earliest year to which an
 *  time of day can be initialized.  This is considered the
 *  epoch.
 */
#define TOD_BASE_YEAR 1988

/**
 *  @brief Latest year to which a time of day can be initialized.
 *
 *  The following constant defines the latest year to which an
 *  RTEMS time of day can be set using rtems_clock_set().
 *
 *  32 bits can accept as latest point in time 2106-Feb-7 6:28:15
 *  but to simplify the implementation, is was decided to only
 *  check that the year is not greater than the year of this constant.
 *  The year 2099 was chosen because all years evenly divisible by 4 from 1988
 *  to 2099 are leap years.  In this time frame, years evenly divisible by 100
 *  are no leap years unless they are evenly divisible by 400.  Thus the year
 *  2000 is a leap year.
 *
 *  The internal CLOCK_REALTIME can run centuries longer but in
 *  contrast to the POSIX API, the RTEMS Classic API does not
 *  support this for efficiency reasons.
 */
#define TOD_LATEST_YEAR 2099

/**
 * @addtogroup RTEMSScoreTOD
 *
 * This handler encapsulates functionality used to manage time of day.
 *
 * @{
 */

/**
 *  @brief TOD control.
 */
typedef struct {
  /**
   *  @brief Indicates if the time of day is set.
   *
   *  This is true if the application has set the current
   *  time of day, and false otherwise.
   */
  bool is_set;
} TOD_Control;

/**
 * @brief TOD Management information
 */
extern TOD_Control _TOD;

/**
 * @brief This array contains the number of days in all months up to the month
 *   indicated by the index of the second dimension.
 *
 * The first dimension should be 0 for leap years, and 1 otherwise.
 */
extern const uint16_t _TOD_Days_to_date[ 2 ][ 13 ];

/**
 * @brief Locks the time of day mutex.
 */
void _TOD_Lock( void );

/**
 * @brief Unlocks the time of day mutex.
 */
void _TOD_Unlock( void );

/**
 * @brief Checks if api mutex is owner of the time of day mutex.
 *
 * @retval true It is owner of the time of day mutex.
 * @retval false It is not owner of the time of day mutex.
 */
#if defined(RTEMS_DEBUG)
bool _TOD_Is_owner( void );
#endif

/**
 * @brief Acquires the lock context for the timecounter.
 *
 * @param lock_context The lock to acquire.
 */
static inline void _TOD_Acquire( ISR_lock_Context *lock_context )
{
  _Timecounter_Acquire( lock_context );
}

/**
 * @brief Releases the lock context for the timecounter.
 *
 * @param lock_context The lock to release.
 */
static inline void _TOD_Release( ISR_lock_Context *lock_context )
{
  _Timecounter_Release( lock_context );
}

/**
 * @brief Maps the year to the leap year index.
 *
 * @param year is the year to map.
 *
 * @retval 0 The year is a leap year.
 *
 * @retval 1 The year is not a leap year.
 */
static inline size_t _TOD_Get_leap_year_index( uint32_t year )
{
  _Assert( year % 4 != 0 || year % 100 != 0 || year % 400 == 0 );
  return ( ( year % 4 ) + 3 ) / 4;
}

/**
 * @brief Checks the time point is a valid new time of day for _TOD_Set().
 *
 * @param tod the time of day to check.
 *
 * @retval STATUS_SUCCESSFUL The time of day is valid.
 *
 * @retval STATUS_INVALID_NUMBER The time of day is invalid.
 */
Status_Control _TOD_Is_valid_new_time_of_day( const struct timespec *tod );

/**
 * @brief Sets the time of day.
 *
 * The caller must be the owner of the TOD lock.
 *
 * @param tod The new time of day in timespec format representing
 *   the time since UNIX Epoch.  The new time of day shall be valid according
 *   to _TOD_Is_valid_new_time_of_day().
 * @param lock_context The ISR lock context used for the corresponding
 *   _TOD_Acquire().  The caller must be the owner of the TOD lock.  This
 *   function will release the TOD lock.
 *
 * @retval STATUS_SUCCESSFUL Successful operation.
 * @retval other Some error occurred.
 */
Status_Control _TOD_Set(
  const struct timespec *tod,
  ISR_lock_Context      *lock_context
);

/**
 * @brief Gets the current time in the timespec format.
 *
 * @param[out] time The value gathered by the request.
 */
static inline void _TOD_Get(
  struct timespec *tod
)
{
  _Timecounter_Nanotime( tod );
}

/**
 * @brief Gets the system uptime with potential accuracy to the nanosecond.
 *
 * This routine returns the system uptime with potential accuracy
 * to the nanosecond.
 *
 * The initial uptime value is undefined.
 *
 * @param[out] time Is a pointer to the uptime after the method call.
 */
static inline void _TOD_Get_uptime(
  Timestamp_Control *time
)
{
  *time = _Timecounter_Sbinuptime();
}

/**
 * @brief Gets the system uptime with potential accuracy to the nanosecond.
 *
 * The initial uptime value is zero.
 *
 * @param[out] time Is a pointer to the uptime after the method call.
 */
static inline void _TOD_Get_zero_based_uptime(
  Timestamp_Control *time
)
{
  *time = _Timecounter_Sbinuptime() - SBT_1S;
}

/**
 * @brief Gets the system uptime with potential accuracy to the nanosecond.
 *
 * The initial uptime value is zero.
 *
 * @param[out] time Is a pointer to the uptime after the method call.
 */
static inline void _TOD_Get_zero_based_uptime_as_timespec(
  struct timespec *time
)
{
  _Timecounter_Nanouptime( time );
  --time->tv_sec;
}

/**
 * @brief Returns Number of seconds Since RTEMS epoch.
 *
 * The following contains the number of seconds from 00:00:00
 * January 1, TOD_BASE_YEAR until the current time of day.
 *
 * @return The number of seconds since RTEMS epoch.
 */
static inline uint32_t _TOD_Seconds_since_epoch( void )
{
  return (uint32_t) _Timecounter_Time_second;
}

/**
 *  @brief Gets number of ticks in a second.
 */
#define TOD_TICKS_PER_SECOND _Watchdog_Ticks_per_second

/**
 * @brief This routine returns a timeval based upon the internal timespec
 *      format TOD.
 *
 * @param[out] time The timeval to be filled in by the method.
 */
static inline void _TOD_Get_timeval(
  struct timeval *time
)
{
  _Timecounter_Microtime( time );
}

/**
 * @brief Adjusts the Time of Time.
 *
 * This method is used to adjust the current time of day by the
 * specified amount.
 *
 * @param delta is the amount to adjust.
 *
 * @retval STATUS_SUCCESSFUL Successful operation.
 * @retval other Some error occurred.
 */
Status_Control _TOD_Adjust(
  const struct timespec *delta
);

/**
 * @brief Check if the TOD is Set
 *
 * @retval true The time is set.
 * @retval false The time is not set.
 */
static inline bool _TOD_Is_set( void )
{
  return _TOD.is_set;
}

/** @} */

/**
 * @defgroup RTEMSScoreTODHooks Time of Day Handler Action Hooks
 *
 * @ingroup RTEMSScoreTOD
 *
 * @brief This group contains the implementation to support Time of Day Handler
 *   action hooks.
 *
 * The following support registering a hook which is invoked
 * when the TOD is set. These can be used by a paravirtualized
 * BSP to mirror time changes to the hosting environment or a
 * regular BSP to program a real-time clock when the RTEMS TOD
 * is set.
 *
 * @{
 */

/**
 *  @brief Possible actions where a registered hook could be invoked
 */
typedef enum {
  /**
   *  @brief Constant to indicate the TOD is being set.
   */
  TOD_ACTION_SET_CLOCK
} TOD_Action;

/**
 * @brief Structure to manage each TOD action hook
 */
typedef struct TOD_Hook {
  /** This is the chain node portion of an object. */
  Chain_Node Node;

  /** This is the TOD action hook that is invoked. */
  Status_Control ( *handler )( TOD_Action, const struct timespec * );
} TOD_Hook;

/**
 * @brief Set of registered methods for TOD Actions
 */
extern Chain_Control _TOD_Hooks;

/**
 * @brief Add a TOD Action Hook
 *
 * This method is used to add a hook to the TOD action set.
 *
 * @brief hook is the action hook to register.
 */
void _TOD_Hook_Register(
  TOD_Hook *hook
);

/**
 * @brief Remove a TOD Action Hook
 *
 * This method is used to remove a hook from the TOD action set.
 *
 * @brief hook is the action hook to unregister.
 */
void _TOD_Hook_Unregister(
  TOD_Hook *hook
);

/**
 * @brief Run the TOD Action Hooks
 *
 * This method is used to invoke the set of TOD action hooks.
 *
 * @brief action The action which triggered this run.
 * @brief tod The current time of day.
 *
 * @retval STATUS_SUCCESSFUL Successful operation.
 * @retval other Some error occurred.
 */
Status_Control _TOD_Hook_Run(
  TOD_Action             action,
  const struct timespec *tod
);


/** @} */

#ifdef __cplusplus
}
#endif

#endif
/* end of include file */