include/rtems/test-scheduler.h

0001 /* SPDX-License-Identifier: BSD-2-Clause */
0002
0003 /**
0004  * @file
0005  *
0006  * @ingroup RTEMSTestFramework
0007  *
0008  * @brief This header file defines the scheduler test support API.
0009  */
0010
0011 /*
0012  * Copyright (C) 2021 embedded brains GmbH & Co. KG
0013  *
0014  * Redistribution and use in source and binary forms, with or without
0015  * modification, are permitted provided that the following conditions
0016  * are met:
0017  * 1. Redistributions of source code must retain the above copyright
0018  *    notice, this list of conditions and the following disclaimer.
0019  * 2. Redistributions in binary form must reproduce the above copyright
0020  *    notice, this list of conditions and the following disclaimer in the
0021  *    documentation and/or other materials provided with the distribution.
0022  *
0023  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
0024  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
0025  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
0026  * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
0027  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
0028  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
0029  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
0030  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
0031  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
0032  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
0033  * POSSIBILITY OF SUCH DAMAGE.
0034  */
0035
0036 #ifndef _RTEMS_TEST_SCHEDULER_H
0037 #define _RTEMS_TEST_SCHEDULER_H
0038
0039 #include <rtems/test.h>
0040 #include <rtems/score/processormask.h>
0041 #include <rtems/score/scheduler.h>
0042
0043 #ifdef __cplusplus
0044 extern "C" {
0045 #endif
0046
0047 /**
0048  * @addtogroup RTEMSTestFramework
0049  *
0050  * @{
0051  */
0052
0053 typedef enum {
0054     T_SCHEDULER_NOP,
0055     T_SCHEDULER_ADD_PROCESSOR,
0056     T_SCHEDULER_ANY,
0057     T_SCHEDULER_ASK_FOR_HELP,
0058     T_SCHEDULER_BLOCK,
0059     T_SCHEDULER_CANCEL_JOB,
0060     T_SCHEDULER_CLEAN_STICKY,
0061     T_SCHEDULER_INITIALIZE,
0062     T_SCHEDULER_MAKE_STICKY,
0063     T_SCHEDULER_MAP_PRIORITY,
0064     T_SCHEDULER_NODE_DESTROY,
0065     T_SCHEDULER_NODE_INITIALIZE,
0066     T_SCHEDULER_PIN,
0067     T_SCHEDULER_RECONSIDER_HELP_REQUEST,
0068     T_SCHEDULER_RELEASE_JOB,
0069     T_SCHEDULER_REMOVE_PROCESSOR,
0070     T_SCHEDULER_SCHEDULE,
0071     T_SCHEDULER_SET_AFFINITY,
0072     T_SCHEDULER_START_IDLE,
0073     T_SCHEDULER_UNBLOCK,
0074     T_SCHEDULER_UNMAP_PRIORITY,
0075     T_SCHEDULER_UNPIN,
0076     T_SCHEDULER_UPDATE_PRIORITY,
0077     T_SCHEDULER_WITHDRAW_NODE,
0078     T_SCHEDULER_YIELD
0079 } T_scheduler_operation;
0080
0081 typedef struct {
0082     Thread_Control *executing;
0083     uint32_t cpu;
0084     T_time instant;
0085     T_scheduler_operation operation;
0086     Thread_Control *thread;
0087     Scheduler_Node *node;
0088     union {
0089         struct {
0090             Priority_Control in;
0091             Priority_Control out;
0092         } map_unmap_priority;
0093         struct {
0094             bool success;
0095         } ask_for_help;
0096         struct {
0097 #ifdef RTEMS_SMP
0098             Thread_Scheduler_state next_state;
0099 #else
0100             int next_state;
0101 #endif
0102         } withdraw_node;
0103         struct {
0104             struct Per_CPU_Control *cpu;
0105         } pin_unpin;
0106         struct {
0107             Thread_Control *idle;
0108         } add_processor;
0109         struct {
0110             struct Per_CPU_Control *cpu;
0111             Thread_Control *idle;
0112         } remove_processor;
0113         struct {
0114             Priority_Node *priority;
0115             uint64_t deadline;
0116         } release_job;
0117         struct {
0118             Priority_Node *priority;
0119         } cancel_job;
0120         struct {
0121             Processor_mask affinity;
0122             Status_Control status;
0123         } set_affinity;
0124     };
0125 } T_scheduler_event;
0126
0127 typedef struct {
0128     size_t recorded;
0129     size_t capacity;
0130     uint64_t operations;
0131 } T_scheduler_header;
0132
0133 typedef struct {
0134     T_scheduler_header header;
0135     T_scheduler_event events[T_ZERO_LENGTH_ARRAY];
0136 } T_scheduler_log;
0137
0138 typedef struct {
0139     T_scheduler_header header;
0140     T_scheduler_event events[2];
0141 } T_scheduler_log_2;
0142
0143 typedef struct {
0144     T_scheduler_header header;
0145     T_scheduler_event events[4];
0146 } T_scheduler_log_4;
0147
0148 typedef struct {
0149     T_scheduler_header header;
0150     T_scheduler_event events[10];
0151 } T_scheduler_log_10;
0152
0153 typedef struct {
0154     T_scheduler_header header;
0155     T_scheduler_event events[20];
0156 } T_scheduler_log_20;
0157
0158 typedef struct {
0159     T_scheduler_header header;
0160     T_scheduler_event events[40];
0161 } T_scheduler_log_40;
0162
0163 T_scheduler_log *T_scheduler_record(T_scheduler_log *);
0164
0165 T_scheduler_log *T_scheduler_record_2(T_scheduler_log_2 *);
0166
0167 T_scheduler_log *T_scheduler_record_4(T_scheduler_log_4 *);
0168
0169 T_scheduler_log *T_scheduler_record_10(T_scheduler_log_10 *);
0170
0171 T_scheduler_log *T_scheduler_record_20(T_scheduler_log_20 *);
0172
0173 T_scheduler_log *T_scheduler_record_40(T_scheduler_log_40 *);
0174
0175 typedef enum {
0176     T_SCHEDULER_BEFORE,
0177     T_SCHEDULER_AFTER
0178 } T_scheduler_when;
0179
0180 typedef void (*T_scheduler_event_handler)(void *, const T_scheduler_event *,
0181     T_scheduler_when);
0182
0183 void T_scheduler_set_event_handler(T_scheduler_event_handler, void *);
0184
0185 extern const T_scheduler_event T_scheduler_event_null;
0186
0187 const T_scheduler_event *T_scheduler_next(T_scheduler_header *,
0188     T_scheduler_operation, size_t *);
0189
0190 const T_scheduler_event *T_scheduler_next_any(T_scheduler_header *,
0191     size_t *);
0192
0193 void T_scheduler_initialize(const Scheduler_Control *);
0194
0195 void T_scheduler_schedule(const Scheduler_Control *, Thread_Control *);
0196
0197 void T_scheduler_yield(const Scheduler_Control *, Thread_Control *,
0198     Scheduler_Node *);
0199
0200 void T_scheduler_block(const Scheduler_Control *, Thread_Control *,
0201     Scheduler_Node *);
0202
0203 void T_scheduler_unblock(const Scheduler_Control *, Thread_Control *,
0204     Scheduler_Node *);
0205
0206 void T_scheduler_update_priority(const Scheduler_Control *, Thread_Control *,
0207     Scheduler_Node *);
0208
0209 Priority_Control T_scheduler_map_priority(const Scheduler_Control *,
0210     Priority_Control);
0211
0212 Priority_Control T_scheduler_unmap_priority(const Scheduler_Control *,
0213     Priority_Control);
0214
0215 void T_scheduler_node_initialize(const Scheduler_Control *, Scheduler_Node *,
0216     Thread_Control *, Priority_Control);
0217
0218 void T_scheduler_node_destroy(const Scheduler_Control *, Scheduler_Node *);
0219
0220 void T_scheduler_release_job(const Scheduler_Control *, Thread_Control *,
0221     Priority_Node *, uint64_t, Thread_queue_Context *);
0222
0223 void T_scheduler_cancel_job(const Scheduler_Control *, Thread_Control *,
0224     Priority_Node *, Thread_queue_Context *);
0225
0226 void T_scheduler_start_idle(const Scheduler_Control *, Thread_Control *,
0227     struct Per_CPU_Control *);
0228
0229 #ifdef RTEMS_SMP
0230 bool T_scheduler_ask_for_help(const Scheduler_Control *, Thread_Control *,
0231     Scheduler_Node *);
0232
0233 void T_scheduler_reconsider_help_request(const Scheduler_Control *,
0234     Thread_Control *, Scheduler_Node *);
0235
0236 void T_scheduler_withdraw_node(const Scheduler_Control *, Thread_Control *,
0237     Scheduler_Node *, Thread_Scheduler_state);
0238
0239 void T_scheduler_make_sticky(const Scheduler_Control *, Thread_Control *,
0240     Scheduler_Node *);
0241
0242 void T_scheduler_clean_sticky(const Scheduler_Control *, Thread_Control *,
0243     Scheduler_Node *);
0244
0245 void T_scheduler_pin(const Scheduler_Control *, Thread_Control *,
0246     Scheduler_Node *, struct Per_CPU_Control *);
0247
0248 void T_scheduler_unpin(const Scheduler_Control *, Thread_Control *,
0249     Scheduler_Node *, struct Per_CPU_Control *);
0250
0251 void T_scheduler_add_processor(const Scheduler_Control *, Thread_Control *);
0252
0253 Thread_Control *T_scheduler_remove_processor(const Scheduler_Control *,
0254     struct Per_CPU_Control *);
0255
0256 Status_Control T_scheduler_set_affinity(const Scheduler_Control *,
0257     Thread_Control *, Scheduler_Node *, const Processor_mask *);
0258 #endif
0259
0260 #ifdef RTEMS_SMP
0261 #define T_SCHEDULER_ENTRY_POINTS { T_scheduler_initialize, \
0262     T_scheduler_schedule, T_scheduler_yield, T_scheduler_block, \
0263     T_scheduler_unblock, T_scheduler_update_priority, \
0264     T_scheduler_map_priority, T_scheduler_unmap_priority, \
0265     T_scheduler_ask_for_help, T_scheduler_reconsider_help_request, \
0266     T_scheduler_withdraw_node, T_scheduler_make_sticky, \
0267     T_scheduler_clean_sticky, T_scheduler_pin, T_scheduler_unpin, \
0268     T_scheduler_add_processor, T_scheduler_remove_processor, \
0269     T_scheduler_node_initialize, T_scheduler_node_destroy, \
0270     T_scheduler_release_job, T_scheduler_cancel_job, \
0271     T_scheduler_start_idle, T_scheduler_set_affinity }
0272 #else
0273 #define T_SCHEDULER_ENTRY_POINTS { T_scheduler_initialize, \
0274     T_scheduler_schedule, T_scheduler_yield, T_scheduler_block, \
0275     T_scheduler_unblock, T_scheduler_update_priority, \
0276     T_scheduler_map_priority, T_scheduler_unmap_priority, \
0277     T_scheduler_node_initialize, T_scheduler_node_destroy, \
0278     T_scheduler_release_job, T_scheduler_cancel_job, \
0279     T_scheduler_start_idle }
0280 #endif
0281
0282 extern const Scheduler_Operations T_scheduler_operations[];
0283
0284 /** @} */
0285
0286 #ifdef __cplusplus
0287 }
0288 #endif
0289
0290 #endif /* _RTEMS_TEST_SCHEDULER_H */