trick/docs/documentation/software_requirements_specification/SRS.md

Home → Documentation Home → Software Requirements Specification

Introduction

The Software Requirements Specification defines the functional, performance, and interface requirements for Trick.

Adaptation Requirements

1. Trick source code shall use a POSIX compliant API when accessing POSIX threads (pthreads), mutual exclusions (mutexes), signals, interrupts, and clock routines. [Trick-151]

Applicable and Reference Documents

Applicable Documents

The following documents are reference documents utilized in the development of this SRS. These documents do not form a part of this SRS and are not controlled by their reference herein.

Document Number	Revision/ Release Date	Document Title

Reference Documents

The following documents are reference documents utilized in the development of this SRS. These documents do not form a part of this SRS and are not controlled by their reference herein.

Document Number	Revision/ Release Date	Document Title

Order of Precedence

In the event of a conflict between the text of this specification and an applicable document cited herein, the text of this specification takes precedence.

All specifications, standards, exhibits, drawings or other documents that are invoked as "applicable" in this specification are incorporated as cited. All documents that are referred to by an applicable document are considered to be for guidance and information only, with the exception of Interface Control Documents (ICD) which will have their applicable documents considered to be incorporated as cited.

Command Line Arguments Requirements

1. Trick shall save the number of command line arguments.
2. Trick shall save all command line arguments.
3. Trick shall determine and save the current directory of the simulation executable.
4. Trick shall determine and save the current name of the simulation executable.
5. Trick shall determine and save the current directory of the run input file.
6. Trick shall use the run input directory as the default output directory.
7. Trick shall allow the user to override the output directory.
8. Trick shall provide the option to create timestamped subdirectories within the output directory.

Data Recording Requirements

1. Data Recording shall provide the capability to record one or more variables that a user has specified in a log group.
2. Data Recording shall provide the capability to record multiple log groups.
3. Data Recording shall time tag the recorded data with the simulation time.
4. Data Recording shall provide the capability to record each log group at its own user specified frequency
5. Data Recording shall provide the capability to record each log group only when user specified model data changes.
6. Data Recording shall provide the capability to write data to disk without affecting the real-time performance of the simulation.

Design and Implementation Constraints

1. Trick shall not preclude that which cannot be precluded unless Trick is precluded from not precluding the unprecludable.

Environment Requirements

1. Trick shall plant a tree for every successful simulation built.
2. Trick shall be dolphin safe.
3. Trick shall recycle.

Scheduler Requirements

Simulation Time

1. Trick shall track simulation elapsed time by an integer count of tics/second
2. Trick shall initialize simulation elapsed time after all initialization class jobs have completed.
3. Trick shall increment simulation elapsed time to the next lowest job call time greater than the current simulation time after all jobs at the current simulation time have completed.

Modes

1. Trick shall provide an initialization mode.
2. Trick shall provide a run mode.
3. Trick shall provide a freeze mode.
4. Trick shall provide an exit mode.
5. Trick shall provide a mode command to transition to Freeze.
6. Trick shall provide a mode command to transition to Run.
7. Trick shall provide a mode command to transition to Shutdown.

Jobs

1. Trick shall provide a method for adding simulation objects to the scheduler prior to execution.
2. Trick shall order jobs by job_class, then phase, then sim_object id, then job_id.

Periodic Jobs

1. Trick shall execute periodic scheduled jobs during simulation run mode (all scheduled types).
2. Trick shall execute periodic freeze jobs during simulation freeze mode (freeze).
3. Trick shall execute periodic scheduled jobs during simulation run mode at the end of a settable software_frame (end_of_frame).
4. Trick shall assign the initial call time for a periodic job to the current simulation time + job offset.
5. Trick shall reschedule subsequent job call times for a periodic job to the current simulation time + job cycle.

Discrete Jobs

1. Trick shall execute discrete job execution scheduling on simulation startup (default_data).
2. Trick shall execute discrete job execution scheduling during simulation initialization (initialization).
3. Trick shall execute of discrete job execution scheduling upon entering simulation freeze (freeze_init).
4. Trick shall execute of discrete job execution scheduling upon exiting simulation freeze (unfreeze).
5. Trick shall execute discrete job execution scheduling during simulation termination (shutdown).

Instrumentation Jobs

1. Trick shall provide a method for inserting a job before each initialization and each scheduled job within a simulation.
2. Trick shall provide a method for inserting a job before a single initialization or scheduled job within a simulation.
3. Trick shall provide a method for inserting a job after each initialization and each scheduled job within a simulation.
4. Trick shall provide a method for inserting a job after a single initialization or scheduled job within a simulation.
5. Trick shall provide a method for removing instrumentation job(s).

Threads

1. Trick shall support single threaded execution during all modes of operation.
2. Trick shall support multiple threads of execution during run mode.
3. Trick shall support child threads that synchronize execution with each time step of the parent thread (synchronous thread).
4. Trick shall support child threads that does not synchronize execution with the parent thread. Thread jobs are restarted at next available time step from the master thread. (asynchronous thread)
5. Trick shall support child threads that does synchronizes execution with the parent thread at a specified interval. This interval may be greater than a time step in the parent thread (asynchronous must finish (AMF) thread).
6. Trick shall spawn enough threads to accomodate jobs listed within the S_define file.
7. Trick shall provide inter-thread job dependencies. This ensures pre-requesite jobs are completed before current job execution.
8. Trick shall terminate simulation execution if a child thread exits.

Signals

1. Trick shall assign signal handlers to attempt a graceful shutdown of the simulation when the following signals occur: SIGINT, SIGTERM, SIGBUS, SIGSEGV, SIGFPE.
2. Trick shall assign signal handlers to handle the SIGCHLD signal.
3. Trick shall attempt to terminate the simulation gracefully when a SIGTERM, SIGBUS, or SIGSEGV signal is caught. Program corruption at this point may be too great to complete this requirement, hence "attempt".
4. Trick shall allow the user to assign the system default signal handlers for the signals SIGBUS, SIGSEGV, or SIGFPE signals.

Realtime Clock Requirements

1. Trick shall provide a framework to use a real-time clock source.
2. The framework shall provide a base real-time clock class that provides an interface to initialize the clock.
3. The framework shall provide a base real-time clock class that provides an interface to return the current time.
4. The framework shall provide a base real-time clock class that provides an interface to reset the clock.
5. The framework shall provide a base real-time clock class that provides an interface to wait/spin on the clock to reach a requested time.
6. The framework shall provide a base real-time clock class that provides an interface to stop the clock.
7. Trick shall provide a real-time clock based on the system gettimeofday clock (GetTimeofDay Clock).

Realtime Synchronization Requirements

1. Trick shall be capable of synchronizing simulation time to a real-time clock.
2. Trick shall be capable of running non-real-time.
3. Trick shall provide the capability to switch between real-time and non-real-time execution.
4. Trick shall detect when the current simulation job execution frame takes longer than the real-time frame (overrun).
5. Trick shall provide the option to respond to simulation overruns by continuing to next frame of execution.
6. Trick shall provide the option to respond to simulation overruns by freezing.
7. Trick shall provide the option to respond to simulation overruns by terminating.
8. The overrun criteria to cause a response shall be either a single large overrun of a user specified size (in seconds), or a user specified number of overruns is detected.
9. Trick shall detect when the current simulation job execution frame is equal to or shorter than the real-time frame (underrun).
10. Trick shall wait for real-time to catch up to the simulation time before starting the next frame of execution during an underrun.
11. Trick shall provide the option to release the processor (sleep) during an underrun.

Safety Requirements

There are no safety requirements for this software. Any simulations that use trick functions to control hazards are responsible for maintaining their safety requirements.

Scheduled Job Queue Requirements.

The ScheduledJobQueue is a helper object to the Scheduler. This object keeps an ordered queue of the jobs for a particular job class. The Scheduler adds and removes jobs from the queue. The Scheduler asks for the top job of the queue, or the next job that has an execution time that matches the current simulation time. Finally, the Scheduler asks the ScheduledJobQueue to insert an instrumentation job where the job is attached before or after a specific job in the queue, or attached before or after all jobs in the simulation.

Jobs

1. Trick shall store an ordered queue of jobs of the same scheduling class. The order shall be based on job class, phase number, sim_object order, and finally order of jobs within the simulation object.
2. Trick shall provide a method to add simulation objects to the queue.
3. Trick shall provide a method to add simulation objects to the queue that ignores the sim_object and job order.
4. Trick shall provide a method to clear the job queue.
5. Trick shall provide a method to get the next job on the list.
6. Trick shall provide a method to search for the next job on the list whose next job call time matches the current simulation time.
7. Trick shall provide a method to reset the search index to the top of the list.

Job Call Time

1. Trick shall track the lowest next job call time greater than the current call time.
2. Trick shall provide a method to retrieve the next job call time.

Instrumentation Jobs

1. Trick shall provide a method to insert a job before each job in the queue.
2. Trick shall provide a method to insert a job before a single job in the queue.
3. Trick shall provide a method to insert a job after each job in the queue.
4. Trick shall provide a method to insert a job after a single job in the queue.

Sleep Timer Requirements

1. Trick shall provide a framework to use a sleep timer.
2. The framework shall provide a base timer class that provides an interface to initialize the timer.
3. The framework shall provide a base timer class that provides an interface to start the timer.
4. The framework shall provide a base timer class that provides an interface to reset the timer.
5. The framework shall provide a base timer class that provides an interface to wait on the timer to expire.
6. The framework shall provide a base timer class that provides an interface to stop the timer.
7. The framework shall provide a base timer class that provides an interface to shutdown the timer.
8. Trick shall provide a sleep timer based on the system itimer (ITimer timer).

Traceability to Parent Requirements

1. There are no formal parent requirements that flow into this SRS.