source: rtems-schedsim/schedsim/UsingTheSchedulerSimulator.txt @ d1f9281

Last change on this file since d1f9281 was cc1a54a, checked in by Joel Sherrill <joel.sherrill@…>, on 05/22/14 at 15:19:55

Enhance cpus command to do validation of executing threads.

This patch enhances the cpus command such that it can take a list
of expected threads to be executing and validate that they are
executing on the expected cores.

The cpus command was moved to the shared directory.

The documentation was updated.

  • Property mode set to 100644
File size: 16.8 KB
Line 
1Using the RTEMS Scheduler Simulator
2===================================
3:doctype: book
4:toc3:
5:toclevels: 3
6:icons:
7:numbered:
8
9Joel Sherrill <joel.sherrill@oarcorp.com>
10
111.1, 22 May 2014
12
13Introduction
14------------
15The Scheduler Simulator is designed allow one to debug and validate an
16algorithm before attempting to execute it in the more complex environment
17of the actual RTEMS run-time on real hardware or a CPU simulator.
18The Scheduler Simulator script language is designed to produce very
19reproducible event sequences which may not be easy to do with the
20scheduler and a real set of tasks.
21
22The Scheduler Simulator consists of a subset of the RTEMS SuperCore,
23Classic API, Shell, and a set of custom commands to access particular
24services.  These are provided in the form of a library which can be
25utilized to instance scheduler simulator variants for custom algorithms.
26
27Checking out from Source Code Repository
28----------------------------------------
29
30The RTEMS Scheduler Simulator is in its own CVS module named
31rtems-schedsim in the RTEMS git Repository.  It can be cloned as follows:
32
33-------------------------------------------------------------
34git://git.rtems.org/rtems-schedsim.git
35-------------------------------------------------------------
36
37The source code must then be bootstrapped using the bootstrap script from
38the RTEMS source tree.  After this is complete, it can be configured
39and built outside the source tree like RTEMS itself.  The following is
40an example bootstrap and configure command invocation:
41
42-------------------------------------------------------------
43# “$r” is an environment variable which points to top of RTEMS source tree
44$ cd rtems-schedsim/
45$ $r/bootstrap
46.
47configure.ac:18: installing `./config.guess'
48configure.ac:18: installing `./config.sub'
49configure.ac:19: installing `./install-sh'
50configure.ac:19: installing `./missing'
51./schedsim
52rtems/Makefile.am: installing `../depcomp'
53$ cd ..
54$ mkdir b-schedsim
55$ cd b-schedsim
56$ ../rtems-schedsim/configure --enable-maintainer-mode --prefix=/tmp/schedsim \
57    --enable-rtemsdir=/home/joel/rtems-4.11-work/build/rtems
58-------------------------------------------------------------
59
60Unless the '–enable-smp' option is specified, it will not build the
61scheduler simulator instance for the Simple SMP Scheduler which is
62located in the schedsim/shell/schedsim_smpsimple subdirectory.
63
64After the tree is configured, it is a normal 'make' and 'make install' to
65build and install the RTEMS Scheduler Simulator.
66
67There are currently two scheduler simulator instances in this source
68tree. They are located in:
69
70* schedsim/shell/schedsim_smpsimple – Simple SMP Scheduler
71* schedsim/shell/schedsim_priority – Deterministic Priority Schedulers
72
73Under each is a directory named 'scenarios'  with .scen files and
74.expected files.  To run a single scenario, something like this works
75when in 'schedsim_priority'.
76
77The scenarios are in the source tree and the binary is in the build tree.
78This results in the simulator name often requiring a full path to execute.
79
80-------------------------------------------------------------
81$ cd
82/home/joel/rtems-4.11-work/build/rtems-schedsim/schedsim/shell/schedsim_priority
83$ ../../../../b-schedsim/schedsim/shell/schedsim_priority/schedsim \
84     scenarios/script06.scen
85-------------------------------------------------------------
86
87There is a script in the directory 'rtems-schedsim/schedsim/shell' named
88'run_scenarios' which can run all or a subset of scenarios and tell you
89if they pass or fail. It must be provided with the name of the Scheduler
90Simulator instance to invoke.
91
92-------------------------------------------------------------
93$ pwd
94/home/joel/rtems-4.11-work/build/rtems-schedsim/schedsim/shell/schedsim_priority
95$ ../run_scenarios -A \
96-s ../../../../b-schedsim/schedsim/shell/schedsim_priority/schedsim_priority/schedsim_priority
97PASS - scenarios/script01.scen
98PASS - scenarios/script02.scen
99PASS - scenarios/script03.scen
100PASS - scenarios/script04.scen
101PASS - scenarios/script05.scen
102PASS – scenarios/script06.scen
103-------------------------------------------------------------
104
105The first time you run a scenario, there is no output to check against
106and the script will echo the cp command line required to turn the actual
107output into the expected output file.
108
109Scripting Language
110------------------
111The Scheduler Simulator has a small command set which is designed to
112allow the scheduler implementer to write simple script files to exercise
113a scheduling algorithm.
114
115This chapter describes each of these commands and their common
116characteristics.  Examples were executed using the Scheduler Simulator
117found in examples-v2/schedsim/schedsim_priority.  Any lines of output
118from this simulator instance which start with 'Thread Heir' and
119'Thread Executing' are printed by the '_Thread_Dispatch' wrapper
120
121Common Characteristics
122~~~~~~~~~~~~~~~~~~~~~~
123The commands use arguments of similar types. This section describes
124the command characteristics of the commands.
125
126Task Names
127^^^^^^^^^^
128Multiple commands take task names.  The task names are of Classic API
129form.  They can be up to four characters. They should not start with "0"
130since that is the test used to determine if it is a hexadecimal task id.
131
132Commands
133~~~~~~~~
134The commands supported by the RTEMS Scheduler Simulator are described
135in this section.
136
137echo Command
138^^^^^^^^^^^^
139*Usage*: echo [ARGS]
140
141This methods prints all of the arguments on its command line to standard
142output followed by a new line.
143
144help  Command
145^^^^^^^^^^^^^
146*Usage*: help [topic|command]
147
148This command is used to obtain information on commands within a category
149(e.g. misc, rtems, etc.) or on a specific command.
150
151exit Command
152^^^^^^^^^^^^
153*Usage*: exit
154
155This command is used to exit the Scheduler Simulator.
156
157rtems_init Command
158^^^^^^^^^^^^^^^^^^
159*Usage*: rtems_init
160
161This command initializes RTEMS using the configuration provided.
162
163task_create Command
164^^^^^^^^^^^^^^^^^^^
165*Usage*: task_create [-tT] [-pP] [-a affinity] name priority
166
167This command creates and starts a Classic API task with the specified name
168and initial priority. It also starts the task.  This is the equivalent
169of the rtems_task_create and rtems_task_start Classic API directives.
170
171In SMP configurations, the -a argument can be used to specify the
172affinity of the created task if the default affinity is not desired.
173In this case, rtems_task_set_affinity is invoked between the calls
174to rtems_task_create and rtems_task_start Classic API directives.
175
176The command line arguments are processed as follows:
177
178* -t - disable timeslicing
179* -T - enable timeslicing
180* -p - disable preemption
181* -p - enable preemption
182* -a affinity - specify affinity mask
183
184The following is the output from the invocation 'task_create joel 5':
185
186-------------------------------------------------------------
187Task (joel) created: id=0x0a010001, priority=5
188Task (joel) starting: id=0x0a010001, priority=5
189  Thread Heir: 0x0a010001 priority=5
190  Thread Executing: 0x0a010001 priority=5
191-------------------------------------------------------------
192
193task_delete Command
194^^^^^^^^^^^^^^^^^^^
195*Usage*: task_delete name|id
196
197This command deletes the specified task.  It is the equivalent of the
198rtems_task_delete directive in the Classic API.
199
200The following is the output from the invocation task_delete joel :
201
202-------------------------------------------------------------
203  Thread Heir: 0x09010001 priority=255
204  Thread Executing: 0x09010001 priority=255
205Task (0x0a010001) deleted
206-------------------------------------------------------------
207
208task_mode Command
209^^^^^^^^^^^^^^^^^
210*Usage*: task_mode [-tTpP]
211
212This command is used to modified the current mode of the currently
213executing task.  It is the equivalent of the rtems_task_mode directive
214in the Classic API.
215
216The command line arguments are processed as follows:
217
218* -t - disable timeslicing
219* -T - enable timeslicing
220* -p - disable preemption
221* -p - enable preemption
222
223task_priority Command
224^^^^^^^^^^^^^^^^^^^^^
225*Usage*: task_set_priority name|id priority
226
227This command is used to modified the current priority of the currently
228executing task.  It is the equivalent of the rtems_task_priority directive
229in the Classic API.  When priority is 0, then the current priority of
230the specified task is returned.
231
232The following is the output from the invocation task_priority joel 0:
233
234-------------------------------------------------------------
235Task (0x0a010001) Current Priority is 0
236-------------------------------------------------------------
237
238The following is the output from the invocation task_priority joel 5:
239
240-------------------------------------------------------------
241Task (0x0a010001) Change Priority from 1 to 5
242-------------------------------------------------------------
243
244task_resume Command
245^^^^^^^^^^^^^^^^^^^
246*Usage*: task_resume name|id
247
248This command is used to suspend the specified task.  It is the equivalent
249of the rtems_task_suspend directive in the Classic API.
250
251task_suspend Command
252^^^^^^^^^^^^^^^^^^^^
253*Usage*: task_suspend name|id
254
255This command is used to resume the specified task.  It is the equivalent
256of the rtems_task_resume directive in the Classic API.
257
258task_wake_after Command
259^^^^^^^^^^^^^^^^^^^^^^^
260*Usage*: task_wake_after ticks
261
262This command is used to cause the currently executing task to sleep
263for the specified number of ticks.  It is the equivalent of the
264rtems_task_wake_after directive in the Classic API.
265
266task_get_affinity Command
267^^^^^^^^^^^^^^^^^^^^^^^^^
268*Usage*: task_get_affinity task
269
270This command is used to print the affinity of the specified task.
271It is the equivalent of the rtems_task_get_affinity directive
272in the Classic API.
273
274task_set_affinity Command
275^^^^^^^^^^^^^^^^^^^^^^^^^
276*Usage*: task_set_affinity task affinity
277
278This command is used to modify the affinity of the specified task.
279It is the equivalent of the rtems_task_set_affinity directive
280in the Classic API.
281
282clock_tick Command
283^^^^^^^^^^^^^^^^^^
284*Usage*: clock_tick ticks
285This command is used to cause the specified number of ticks to pass.
286
287It is the equivalent of calling the  rtems_clock_tick directive tick
288times in the Classic API.
289
290semaphore_create Command
291^^^^^^^^^^^^^^^^^^^^^^^^
292*Usage*: semaphore_create [-bcsfpiC:V:] name
293
294This method creates a semaphore named name with the specified attributes.  It is the equivalent of the rtems_semaphore_create directive in the Classic API.
295
296The command line arguments are processed as follows:
297
298* -b - binary mutex
299* -c - counting semaphore
300* -s - simple binary semaphore
301* -f - FIFO Blockin*
302* -p - Priority Blocking
303* -i - Priority Inheritance
304* -C priority - Priority Ceiling and priority
305* -V initial  - Initial value (default=0)
306
307semaphore_delete Command
308^^^^^^^^^^^^^^^^^^^^^^^^
309*Usage*: semaphore_delete name|id
310
311This method deletes the specified semaphore.  It is the equivalent of
312the rtems_semaphore_delete directive in the Classic API.
313
314semaphore_obtain Command
315^^^^^^^^^^^^^^^^^^^^^^^^
316*Usage*: semaphore_obtain name|id ticks
317
318This method causes the currently executing thread to attempt to obtain the
319specified semaphore.  It is the equivalent of the rtems_semaphore_obtain
320directive in the Classic API.
321
322*NOTE*: no polling supported yet
323
324semaphore_release Command
325^^^^^^^^^^^^^^^^^^^^^^^^^
326*Usage*: semaphore_release name|id
327
328This method causes the currently executing thread to release the specified
329semaphore.  It is the equivalent of the rtems_semaphore_release directive
330in the Classic API.
331
332semaphore_flush Command
333^^^^^^^^^^^^^^^^^^^^^^^
334*Usage*: semaphore_flush name|id
335
336This method causes the currently executing thread to flush the specified
337semaphore.  It is the equivalent of the rtems_semaphore_flush directive
338in the Classic API.
339
340
341cpus Command
342^^^^^^^^^^^^
343*Usage*: cpus [expected0 .. expectedn]
344
345This method prints the executing and heir thread for each processor
346in the system. If provided with arguments, the argumnents may be
347task names or ids and indicate the task which is expected to be
348executing on that processor. If the expected task name/id is '-',
349then that processor is not checked.
350
351In the event that the executing thread does not match the expected,
352the scenario is aborted. This allows for self-checking scenarios.
353
354executing Command
355^^^^^^^^^^^^^^^^^
356*Usage*: executing
357
358This method prints information on the currently executing task.
359
360heir Command
361^^^^^^^^^^^^
362*Usage*: heir
363
364This method prints information on the current heir task(s).
365
366Constructing Your Own Scheduler Simulator
367-----------------------------------------
368The Scheduler Simulator Framework is provided in the form of a library
369which can be utilized to instance scheduler simulator variants for
370custom algorithms.
371
372If developing a scheduler for possible inclusion in the main RTEMS source
373code, then you will want to construct the simulator in the 'rtems-schedsim'
374tree following the examples that are already present.
375
376However, it it also possible to construct a Scheduler Simulator instance
377outside the rtems-schedsim source tree.  The directory schedsim in
378the git module 'examples-v2' is a minimal example of doing this.  It is
379based on an installed copy of the RTEMS Scheduler Simulator and uses
380the default Deterministic Priority Scheduler in RTEMS.  It provides the
381following files:
382
383* config.c - RTEMS Configuration Instance
384* Makefile - instructions on building
385* printheir_executing.c - custom versions of PRINT_EXECUTING() and
386PRINT_HEIR()
387* README - overview of directory contents
388* schedsim.cc - main() for custom Scheduler Simulator instance
389* wrap_thread_dispatch.c - wrap method for _Thread_Dispatch so script
390output can include information on when context switches occur.
391
392When compiled, it produces an executable schedsim which has the following usage:
393
394-------------------------------------------------------------
395Usage:  ./schedsim [-v] script
396         -v           - enable verbose output
397-------------------------------------------------------------
398
399When invoked with '/dev/stdin' as the script, one can enter commands
400interactively.  The primary use case expected however is to use predefined
401scripts to exercise specific schedulers. For example, this is the
402contents of the script 'rtems/tools/schedsim/shell/scripts/script01' from
403the RTEMS Scheduler Simulator source:
404
405-------------------------------------------------------------
406echo "*** TEST 01 ***"
407rtems_init
408echo "=== Create and delete 0x0a010001 ==="
409task_create TA1 3
410task_delete TA1
411echo "=== Create and delete 0x0a010002 ==="
412task_create TA1 3
413task_delete 0x0a010002
414echo "*** END OF TEST 01 ***"
415exit
416# We will not get here
417-------------------------------------------------------------
418
419This test initializes the RTEMS simulator, creates and deletes two tasks,
420and then exits. When executed, the following output is generated:
421
422-------------------------------------------------------------
423*** TEST 01 ***
424  Thread Heir: 0x09010001 priority=255
425  Thread Executing: 0x09010001 priority=255
426=== Create and delete 0x0a010001 ===
427Task (TA1) created: id=0x0a010001, priority=3
428Task (TA1) starting: id=0x0a010001, priority=3
429  Thread Heir: 0x0a010001 priority=3
430  Thread Executing: 0x0a010001 priority=3
431  Thread Heir: 0x09010001 priority=255
432  Thread Executing: 0x09010001 priority=255
433Task (0x0a010001) deleted
434=== Create and delete 0x0a010002 ===
435Task (TA1) created: id=0x0a010002, priority=3
436Task (TA1) starting: id=0x0a010002, priority=3
437  Thread Heir: 0x0a010002 priority=3
438  Thread Executing: 0x0a010002 priority=3
439  Thread Heir: 0x09010001 priority=255
440  Thread Executing: 0x09010001 priority=255
441Task (0x0a010002) deleted
442*** END OF TEST 01 ***
443-------------------------------------------------------------
444
445This example uses a scheduler provided with RTEMS.  If you are developing
446your own scheduler, then you will have to include the scheduler in
447your build and configure it just as if doing so as part of a regular
448RTEMS application.  The following configuration directives will need to
449be specified:
450
451The pluggable scheduler interface was added after the 4.10 release series
452so there are not a lot of options at this point. We anticipate a lower
453memory, non-deterministic priority scheduler suitable for use in small
454systems and an Earliest Deadline First Scheduler (EDF) to arrive in
455the future.
456
457The pluggable scheduler interface enables the user to provide their own
458scheduling algorithm. If you choose to do this, you must define multiple
459configuration macros.  The following information on specifying a user
460provided scheduler is from the 'Configuring a System' chapter of
461the RTEMS User's Guide.
462
463First, you must define CONFIGURE_SCHEDULER_USER to indicate
464the application provides its own scheduling algorithm. If
465+CONFIGURE_SCHEDULER_USER+ is defined then the following additional macros
466must be defined:
467
468* +CONFIGURE_SCHEDULER_USER_ENTRY_POINTS+ must be defined with the set of
469methods which implement this scheduler.
470* +CONFIGURE_MEMORY_FOR_SCHEDULER+ must be defined with the amount of
471memory required as a base amount for the scheduler.
472* +CONFIGURE_MEMORY_PER_TASK_FOR_SCHEDULER(_tasks)+ must be defined as
473a formula which computes the amount of memory required based upon the
474number of tasks configured.
475
Note: See TracBrowser for help on using the repository browser.