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

Last change on this file since b38dbcc was d84b7a5, checked in by Joel Sherrill <joel.sherrill@…>, on 05/05/13 at 16:30:41

UsingTheSchedulerSimulator?.txt: New asciidoc

  • Property mode set to 100644
File size: 15.4 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.0, 5 May 2013
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 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.
170The following is the output from the invocation 'task_create joel 5':
171
172-------------------------------------------------------------
173Task (joel) created: id=0x0a010001, priority=5
174Task (joel) starting: id=0x0a010001, priority=5
175  Thread Heir: 0x0a010001 priority=5
176  Thread Executing: 0x0a010001 priority=5
177-------------------------------------------------------------
178
179task_delete Command
180^^^^^^^^^^^^^^^^^^^
181*Usage*: task_delete name|id
182
183This command deletes the specified task.  It is the equivalent of the
184rtems_task_delete directive in the Classic API.
185
186The following is the output from the invocation task_delete joel :
187
188-------------------------------------------------------------
189  Thread Heir: 0x09010001 priority=255
190  Thread Executing: 0x09010001 priority=255
191Task (0x0a010001) deleted
192-------------------------------------------------------------
193
194task_mode Command
195^^^^^^^^^^^^^^^^^
196*Usage*: task_mode [-tTpP]
197
198This command is used to modified the current mode of the currently
199executing task.  It is the equivalent of the rtems_task_mode directive
200in the Classic API.
201
202The command line arguments are processed as follows:
203
204* -t - disable timeslicing
205* -T - enable timeslicing
206* -p - disable preemption
207* -p - enable preemption
208
209task_priority Command
210^^^^^^^^^^^^^^^^^^^^^
211*Usage*: task_set_priority name|id priority
212
213This command is used to modified the current priority of the currently
214executing task.  It is the equivalent of the rtems_task_priority directive
215in the Classic API.  When priority is 0, then the current priority of
216the specified task is returned.
217
218The following is the output from the invocation task_priority joel 0:
219
220-------------------------------------------------------------
221Task (0x0a010001) Current Priority is 0
222-------------------------------------------------------------
223
224The following is the output from the invocation task_priority joel 5:
225
226-------------------------------------------------------------
227Task (0x0a010001) Change Priority from 1 to 5
228-------------------------------------------------------------
229
230task_resume Command
231^^^^^^^^^^^^^^^^^^^
232*Usage*: task_resume name|id
233
234This command is used to suspend the specified task.  It is the equivalent
235of the rtems_task_suspend directive in the Classic API.
236
237task_suspend Command
238^^^^^^^^^^^^^^^^^^^^
239*Usage*: task_suspend name|id
240
241This command is used to resume the specified task.  It is the equivalent
242of the rtems_task_resume directive in the Classic API.
243
244task_wake_after Command
245^^^^^^^^^^^^^^^^^^^^^^^
246*Usage*: task_wake_after ticks
247
248This command is used to cause the currently executing task to sleep
249for the specified number of ticks.  It is the equivalent of the
250rtems_task_wake_after directive in the Classic API.
251
252clock_tick Command
253^^^^^^^^^^^^^^^^^^
254*Usage*: clock_tick ticks
255This command is used to cause the specified number of ticks to pass.
256
257It is the equivalent of calling the  rtems_clock_tick directive tick
258times in the Classic API.
259
260semaphore_create Command
261^^^^^^^^^^^^^^^^^^^^^^^^
262*Usage*: semaphore_create [-bcsfpiC:V:] name
263
264This method creates a semaphore named name with the specified attributes.  It is the equivalent of the rtems_semaphore_create directive in the Classic API.
265
266The command line arguments are processed as follows:
267
268* -b - binary mutex
269* -c - counting semaphore
270* -s - simple binary semaphore
271* -f - FIFO Blockin*
272* -p - Priority Blocking
273* -i - Priority Inheritance
274* -C priority - Priority Ceiling and priority
275* -V initial  - Initial value (default=0)
276
277semaphore_delete Command
278^^^^^^^^^^^^^^^^^^^^^^^^
279*Usage*: semaphore_delete name|id
280
281This method deletes the specified semaphore.  It is the equivalent of
282the rtems_semaphore_delete directive in the Classic API.
283
284semaphore_obtain Command
285^^^^^^^^^^^^^^^^^^^^^^^^
286*Usage*: semaphore_obtain name|id ticks
287
288This method causes the currently executing thread to attempt to obtain the
289specified semaphore.  It is the equivalent of the rtems_semaphore_obtain
290directive in the Classic API.
291
292*NOTE*: no polling supported yet
293
294semaphore_release Command
295^^^^^^^^^^^^^^^^^^^^^^^^^
296*Usage*: semaphore_release name|id
297
298This method causes the currently executing thread to release the specified
299semaphore.  It is the equivalent of the rtems_semaphore_release directive
300in the Classic API.
301
302semaphore_flush Command
303^^^^^^^^^^^^^^^^^^^^^^^
304*Usage*: semaphore_flush name|id
305
306This method causes the currently executing thread to flush the specified
307semaphore.  It is the equivalent of the rtems_semaphore_flush directive
308in the Classic API.
309
310
311executing Command
312^^^^^^^^^^^^^^^^^
313*Usage*: executing
314
315This method prints information on the currently executing task.
316
317heir Command
318^^^^^^^^^^^^
319*Usage*: heir
320
321This method prints information on the current heir task(s).
322
323Constructing Your Own Scheduler Simulator
324-----------------------------------------
325The Scheduler Simulator Framework is provided in the form of a library
326which can be utilized to instance scheduler simulator variants for
327custom algorithms.
328
329If developing a scheduler for possible inclusion in the main RTEMS source
330code, then you will want to construct the simulator in the 'rtems-schedsim'
331tree following the examples that are already present.
332
333However, it it also possible to construct a Scheduler Simulator instance
334outside the rtems-schedsim source tree.  The directory schedsim in
335the git module 'examples-v2' is a minimal example of doing this.  It is
336based on an installed copy of the RTEMS Scheduler Simulator and uses
337the default Deterministic Priority Scheduler in RTEMS.  It provides the
338following files:
339
340* config.c - RTEMS Configuration Instance
341* Makefile - instructions on building
342* printheir_executing.c - custom versions of PRINT_EXECUTING() and
343PRINT_HEIR()
344* README - overview of directory contents
345* schedsim.cc - main() for custom Scheduler Simulator instance
346* wrap_thread_dispatch.c - wrap method for _Thread_Dispatch so script
347output can include information on when context switches occur.
348
349When compiled, it produces an executable schedsim which has the following usage:
350
351-------------------------------------------------------------
352Usage:  ./schedsim [-v] script
353         -v           - enable verbose output
354-------------------------------------------------------------
355
356When invoked with '/dev/stdin' as the script, one can enter commands
357interactively.  The primary use case expected however is to use predefined
358scripts to exercise specific schedulers. For example, this is the
359contents of the script 'rtems/tools/schedsim/shell/scripts/script01' from
360the RTEMS Scheduler Simulator source:
361
362-------------------------------------------------------------
363echo "*** TEST 01 ***"
364rtems_init
365echo "=== Create and delete 0x0a010001 ==="
366task_create TA1 3
367task_delete TA1
368echo "=== Create and delete 0x0a010002 ==="
369task_create TA1 3
370task_delete 0x0a010002
371echo "*** END OF TEST 01 ***"
372exit
373# We will not get here
374-------------------------------------------------------------
375
376This test initializes the RTEMS simulator, creates and deletes two tasks,
377and then exits. When executed, the following output is generated:
378
379-------------------------------------------------------------
380*** TEST 01 ***
381  Thread Heir: 0x09010001 priority=255
382  Thread Executing: 0x09010001 priority=255
383=== Create and delete 0x0a010001 ===
384Task (TA1) created: id=0x0a010001, priority=3
385Task (TA1) starting: id=0x0a010001, priority=3
386  Thread Heir: 0x0a010001 priority=3
387  Thread Executing: 0x0a010001 priority=3
388  Thread Heir: 0x09010001 priority=255
389  Thread Executing: 0x09010001 priority=255
390Task (0x0a010001) deleted
391=== Create and delete 0x0a010002 ===
392Task (TA1) created: id=0x0a010002, priority=3
393Task (TA1) starting: id=0x0a010002, priority=3
394  Thread Heir: 0x0a010002 priority=3
395  Thread Executing: 0x0a010002 priority=3
396  Thread Heir: 0x09010001 priority=255
397  Thread Executing: 0x09010001 priority=255
398Task (0x0a010002) deleted
399*** END OF TEST 01 ***
400-------------------------------------------------------------
401
402This example uses a scheduler provided with RTEMS.  If you are developing
403your own scheduler, then you will have to include the scheduler in
404your build and configure it just as if doing so as part of a regular
405RTEMS application.  The following configuration directives will need to
406be specified:
407
408The pluggable scheduler interface was added after the 4.10 release series
409so there are not a lot of options at this point. We anticipate a lower
410memory, non-deterministic priority scheduler suitable for use in small
411systems and an Earliest Deadline First Scheduler (EDF) to arrive in
412the future.
413
414The pluggable scheduler interface enables the user to provide their own
415scheduling algorithm. If you choose to do this, you must define multiple
416configuration macros.  The following information on specifying a user
417provided scheduler is from the 'Configuring a System' chapter of
418the RTEMS User's Guide.
419
420First, you must define CONFIGURE_SCHEDULER_USER to indicate
421the application provides its own scheduling algorithm. If
422+CONFIGURE_SCHEDULER_USER+ is defined then the following additional macros
423must be defined:
424
425* +CONFIGURE_SCHEDULER_USER_ENTRY_POINTS+ must be defined with the set of
426methods which implement this scheduler.
427* +CONFIGURE_MEMORY_FOR_SCHEDULER+ must be defined with the amount of
428memory required as a base amount for the scheduler.
429* +CONFIGURE_MEMORY_PER_TASK_FOR_SCHEDULER(_tasks)+ must be defined as
430a formula which computes the amount of memory required based upon the
431number of tasks configured.
432
Note: See TracBrowser for help on using the repository browser.