source: rtems/cpukit/include/rtems/score/smplockticket.h @ 5803f37

5
Last change on this file since 5803f37 was 366dbf6, checked in by Andreas Dachsberger <andreas.dachsberger@…>, on 04/15/19 at 10:07:51

doxygen: score: adjust doc in smplockticket.h to doxygen guidelines

Update #3706.

  • Property mode set to 100644
File size: 4.6 KB
Line 
1/**
2 * @file
3 *
4 * @ingroup RTEMSScoreSMPLock
5 *
6 * @brief SMP Lock API
7 */
8
9/*
10 * Copyright (c) 2013, 2016 embedded brains GmbH
11 *
12 * The license and distribution terms for this file may be
13 * found in the file LICENSE in this distribution or at
14 * http://www.rtems.org/license/LICENSE.
15 */
16
17#ifndef _RTEMS_SCORE_SMPLOCKTICKET_H
18#define _RTEMS_SCORE_SMPLOCKTICKET_H
19
20#include <rtems/score/cpuopts.h>
21
22#if defined(RTEMS_SMP)
23
24#include <rtems/score/atomic.h>
25#include <rtems/score/smplockstats.h>
26
27#ifdef __cplusplus
28extern "C" {
29#endif /* __cplusplus */
30
31/**
32 * @addtogroup RTEMSScoreSMPLock
33 *
34 * @{
35 */
36
37/**
38 * @brief SMP ticket lock control.
39 */
40typedef struct {
41  Atomic_Uint next_ticket;
42  Atomic_Uint now_serving;
43} SMP_ticket_lock_Control;
44
45/**
46 * @brief SMP ticket lock control initializer for static initialization.
47 */
48#define SMP_TICKET_LOCK_INITIALIZER \
49  { \
50    ATOMIC_INITIALIZER_UINT( 0U ), \
51    ATOMIC_INITIALIZER_UINT( 0U ) \
52  }
53
54/**
55 * @brief Initializes the SMP ticket lock.
56 *
57 * Concurrent initialization leads to unpredictable results.
58 *
59 * @param[in, out] lock The SMP ticket lock control.
60 */
61static inline void _SMP_ticket_lock_Initialize(
62  SMP_ticket_lock_Control *lock
63)
64{
65  _Atomic_Init_uint( &lock->next_ticket, 0U );
66  _Atomic_Init_uint( &lock->now_serving, 0U );
67}
68
69/**
70 * @brief Destroys the SMP ticket lock.
71 *
72 * Concurrent destruction leads to unpredictable results.
73 *
74 * @param lock The SMP ticket lock control.
75 */
76static inline void _SMP_ticket_lock_Destroy( SMP_ticket_lock_Control *lock )
77{
78  (void) lock;
79}
80
81/**
82 * @brief Acquires the SMP ticket lock.
83 *
84 * @param[in, out] lock The lock to acquire.
85 * @param stats The SMP lock statistics.
86 * @param[out] stats_context The context for the statistics.
87 */
88static inline void _SMP_ticket_lock_Do_acquire(
89  SMP_ticket_lock_Control *lock
90#if defined(RTEMS_PROFILING)
91  ,
92  SMP_lock_Stats          *stats,
93  SMP_lock_Stats_context  *stats_context
94#endif
95)
96{
97  unsigned int                   my_ticket;
98  unsigned int                   now_serving;
99#if defined(RTEMS_PROFILING)
100  unsigned int                   initial_queue_length;
101  SMP_lock_Stats_acquire_context acquire_context;
102
103  _SMP_lock_Stats_acquire_begin( &acquire_context );
104#endif
105
106  my_ticket =
107    _Atomic_Fetch_add_uint( &lock->next_ticket, 1U, ATOMIC_ORDER_RELAXED );
108
109#if defined(RTEMS_PROFILING)
110  now_serving =
111    _Atomic_Load_uint( &lock->now_serving, ATOMIC_ORDER_ACQUIRE );
112  initial_queue_length = my_ticket - now_serving;
113
114  if ( initial_queue_length > 0 ) {
115#endif
116
117    do {
118      now_serving =
119        _Atomic_Load_uint( &lock->now_serving, ATOMIC_ORDER_ACQUIRE );
120    } while ( now_serving != my_ticket );
121
122#if defined(RTEMS_PROFILING)
123  }
124
125  _SMP_lock_Stats_acquire_end(
126    &acquire_context,
127    stats,
128    stats_context,
129    initial_queue_length
130  );
131#endif
132}
133
134/**
135 * @brief Acquires an SMP ticket lock.
136 *
137 * This function will not disable interrupts.  The caller must ensure that the
138 * current thread of execution is not interrupted indefinite once it obtained
139 * the SMP ticket lock.
140 *
141 * @param[in] lock The SMP ticket lock control.
142 * @param[in] stats The SMP lock statistics.
143 * @param[out] stats_context The SMP lock statistics context.
144 */
145#if defined(RTEMS_PROFILING)
146  #define _SMP_ticket_lock_Acquire( lock, stats, stats_context ) \
147    _SMP_ticket_lock_Do_acquire( lock, stats, stats_context )
148#else
149  #define _SMP_ticket_lock_Acquire( lock, stats, stats_context ) \
150    _SMP_ticket_lock_Do_acquire( lock )
151#endif
152
153/**
154 * @brief Releases the SMP ticket lock.
155 *
156 * @param[in, out] lock The SMP ticket lock to release.
157 * @param[out] stats_context The SMP lock statistics context.
158 */
159static inline void _SMP_ticket_lock_Do_release(
160  SMP_ticket_lock_Control *lock
161#if defined(RTEMS_PROFILING)
162  ,
163  const SMP_lock_Stats_context *stats_context
164#endif
165)
166{
167  unsigned int current_ticket =
168    _Atomic_Load_uint( &lock->now_serving, ATOMIC_ORDER_RELAXED );
169  unsigned int next_ticket = current_ticket + 1U;
170
171#if defined(RTEMS_PROFILING)
172  _SMP_lock_Stats_release_update( stats_context );
173#endif
174
175  _Atomic_Store_uint( &lock->now_serving, next_ticket, ATOMIC_ORDER_RELEASE );
176}
177
178/**
179 * @brief Releases an SMP ticket lock.
180 *
181 * @param[in] lock The SMP ticket lock control.
182 * @param[in] stats_context The SMP lock statistics context.
183 */
184#if defined(RTEMS_PROFILING)
185  #define _SMP_ticket_lock_Release( lock, stats_context ) \
186    _SMP_ticket_lock_Do_release( lock, stats_context )
187#else
188  #define _SMP_ticket_lock_Release( lock, stats_context ) \
189    _SMP_ticket_lock_Do_release( lock )
190#endif
191
192/** @} */
193
194#ifdef __cplusplus
195}
196#endif /* __cplusplus */
197
198#endif /* RTEMS_SMP */
199
200#endif /* _RTEMS_SCORE_SMPLOCKTICKET_H */
Note: See TracBrowser for help on using the repository browser.