source: rtems/cpukit/libmisc/testsupport/test.h @ 7f577d3

4.115
Last change on this file since 7f577d3 was 7f577d3, checked in by Alexander Krutwig <alexander.krutwig@…>, on Mar 5, 2015 at 8:06:44 AM

tests: Refactor parallel test execution

  • Property mode set to 100644
File size: 5.3 KB
Line 
1/*
2 * Copyright (c) 2014 embedded brains GmbH.  All rights reserved.
3 *
4 *  embedded brains GmbH
5 *  Dornierstr. 4
6 *  82178 Puchheim
7 *  Germany
8 *  <rtems@embedded-brains.de>
9 *
10 * The license and distribution terms for this file may be
11 * found in the file LICENSE in this distribution or at
12 * http://www.rtems.org/license/LICENSE.
13 */
14
15#ifndef _RTEMS_TEST_H
16#define _RTEMS_TEST_H
17
18#include <rtems.h>
19#include <rtems/bspIo.h>
20#include <rtems/score/atomic.h>
21#include <rtems/score/smpbarrier.h>
22
23#ifdef __cplusplus
24extern "C" {
25#endif /* __cplusplus */
26
27/**
28 * @defgroup RTEMSTest Test Support
29 *
30 * @brief Test support functions.
31 *
32 * @{
33 */
34
35/**
36 * @brief Each test must define a test name string.
37 */
38extern const char rtems_test_name[];
39
40/**
41 * @brief Fatal extension for tests.
42 */
43void rtems_test_fatal_extension(
44  rtems_fatal_source source,
45  bool is_internal,
46  rtems_fatal_code code
47);
48
49/**
50 * @brief Initial extension for tests.
51 */
52#define RTEMS_TEST_INITIAL_EXTENSION \
53  { NULL, NULL, NULL, NULL, NULL, NULL, NULL, rtems_test_fatal_extension }
54
55/**
56 * @brief Prints a begin of test message.
57 *
58 * @param[in] printf_func The formatted output function.
59 * @param[in, out] printf_arg The formatted output function argument.
60 *
61 * @returns As specified by printf().
62 */
63int rtems_test_begin_with_plugin(
64  rtems_printk_plugin_t printf_func,
65  void *printf_arg
66);
67
68/**
69 * @brief Prints a begin of test message using printf().
70 *
71 * @returns As specified by printf().
72 */
73static inline int rtems_test_begin(void)
74{
75  return rtems_test_begin_with_plugin(rtems_printf_plugin, NULL);
76}
77
78/**
79 * @brief Prints a begin of test message using printk().
80 *
81 * @returns As specified by printf().
82 */
83static inline int rtems_test_begink(void)
84{
85  return rtems_test_begin_with_plugin(printk_plugin, NULL);
86}
87
88/**
89 * @brief Prints an end of test message.
90 *
91 * @param[in] printf_func The formatted output function.
92 * @param[in, out] printf_arg The formatted output function argument.
93 *
94 * @returns As specified by printf().
95 */
96int rtems_test_end_with_plugin(
97  rtems_printk_plugin_t printf_func,
98  void *printf_arg
99);
100
101/**
102 * @brief Prints an end of test message using printf().
103 *
104 * @returns As specified by printf().
105 */
106static inline int rtems_test_end(void)
107{
108  return rtems_test_end_with_plugin(rtems_printf_plugin, NULL);
109}
110
111/**
112 * @brief Prints an end of test message using printk().
113 *
114 * @returns As specified by printf().
115 */
116static inline int rtems_test_endk(void)
117{
118  return rtems_test_end_with_plugin(printk_plugin, NULL);
119}
120
121/**
122 * @brief Internal context for parallel job execution.
123 */
124typedef struct {
125  Atomic_Ulong stop;
126  SMP_barrier_Control barrier;
127  size_t worker_count;
128  rtems_id stop_worker_timer_id;
129  rtems_id master_id;
130} rtems_test_parallel_context;
131
132/**
133 * @brief Basic parallel job description.
134 */
135typedef struct {
136  /**
137   * @brief Job initialization handler.
138   *
139   * This handler executes only in the context of the master worker before the
140   * job body handler.
141   *
142   * @param[in] ctx The parallel context.
143   * @param[in] arg The user specified argument.
144   *
145   * @return The desired job body execution time in clock ticks.  See
146   *   rtems_test_parallel_stop_job().
147   */
148  rtems_interval (*init)(
149    rtems_test_parallel_context *ctx,
150    void *arg
151  );
152
153  /**
154   * @brief Job body handler.
155   *
156   * @param[in] ctx The parallel context.
157   * @param[in] arg The user specified argument.
158   * @param[in] worker_index The worker index.  It ranges from 0 to the
159   *   processor count minus one.
160   */
161  void (*body)(
162    rtems_test_parallel_context *ctx,
163    void *arg,
164    size_t worker_index
165  );
166
167  /**
168   * @brief Job finalization handler.
169   *
170   * This handler executes only in the context of the master worker after the
171   * job body handler.
172   *
173   * @param[in] ctx The parallel context.
174   * @param[in] arg The user specified argument.
175   */
176  void (*fini)(
177    rtems_test_parallel_context *ctx,
178    void *arg
179  );
180
181  void *arg;
182} rtems_test_parallel_job;
183
184/**
185 * @brief Indicates if a job body should stop its work loop.
186 *
187 * @param[in] ctx The parallel context.
188 *
189 * @retval true The job body should stop its work loop and return to the caller.
190 * @retval false Otherwise.
191 */
192static inline bool rtems_test_parallel_stop_job(
193  rtems_test_parallel_context *ctx
194)
195{
196  return _Atomic_Load_ulong(&ctx->stop, ATOMIC_ORDER_RELAXED) != 0;
197}
198
199/**
200 * @brief Indicates if a worker is the master worker.
201 *
202 * The master worker is the thread that called rtems_test_parallel().
203 *
204 * @param[in] worker_index The worker index.
205 *
206 * @retval true This is the master worker.
207 * @retval false Otherwise.
208 */
209static inline bool rtems_test_parallel_is_master_worker(size_t worker_index)
210{
211  return worker_index == 0;
212}
213
214/**
215 * @brief Runs a bunch of jobs in parallel on all processors of the system.
216 *
217 * There are SMP barriers before and after the job body.
218 *
219 * @param[in] ctx The parallel context.
220 * @param[in] non_master_worker_priority The task priority for non-master
221 *   workers.
222 * @param[in] jobs The table of jobs.
223 * @param[in] job_count The count of jobs in the job table.
224 */
225void rtems_test_parallel(
226  rtems_test_parallel_context *ctx,
227  rtems_task_priority non_master_worker_priority,
228  const rtems_test_parallel_job *jobs,
229  size_t job_count
230);
231
232/** @} */
233
234#ifdef __cplusplus
235}
236#endif /* __cplusplus */
237
238#endif /* _RTEMS_TEST_H */
Note: See TracBrowser for help on using the repository browser.