xref: /third_party/ltp/testcases/realtime/00_Descriptions.txt

/******************************************************************************/
/*                                                                            */
/* Copyright (c) International Business Machines  Corp., 2007                 */
/*                                                                            */
/* This program is free software;  you can redistribute it and/or modify      */
/* it under the terms of the GNU General Public License as published by       */
/* the Free Software Foundation; either version 2 of the License, or          */
/* (at your option) any later version.                                        */
/*                                                                            */
/* This program is distributed in the hope that it will be useful,            */
/* but WITHOUT ANY WARRANTY;  without even the implied warranty of            */
/* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See                  */
/* the GNU General Public License for more details.                           */
/*                                                                            */
/* You should have received a copy of the GNU General Public License          */
/* along with this program;  if not, write to the Free Software               */
/* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA    */
/*                                                                            */
/******************************************************************************/

OO_DESCRIPTION.txt
==================

The contents of the LTP/testcases/realtime/ directory:

doc                -  Documentation
include            -  Header files which are to be included in the tests
lib                -  c library files for the real-time tests
scripts            -  Set up and parsing scripts needed to run the tests
logs               -  All test logs are stored in this directory
config             -  autotools configure support
confugure.ac       -  Top level autotools configure script
COPYING            -  GPL license
GNUmakefile.am     -  Top level automake makefile
README             -  How to build and run the tests


Below is the decription of what each testcase tests.

func/async_handler testcases :
=============================
async_handler.c:
- Measures latencies involved in asynchronous event handlers.  Specifically it
  measures the latency of the pthread_cond_signal call until signalled thread
  is scheduled.

async_handler_jk.c:
- Mimics an async event handler in a real-time JVM. An async event server
  thread is created that goes to sleep waiting to be woken up to do some
  work.  A user thread is created that simulates the firing of an event by
  signalling the async handler thread to do some work.

async_handler_tsc.c:
- Is similar to the above two i.e. it measures latencies involved in
  asynchronous event handlers.  This test measures time in terms of CPU
  timestamp clock(TSC), for pthread_cond_signal latency.


func/gtod_latency testcases :
=============================
gtod_infinite.c:
- Designed to run forever.  It must manually be killed so it is
  not suited to be part of functional validation suite of tests.  It is
  designed to look for 'delays' between two calls to clock_gettime()

gtod-latency.c:
- Simple program to measure the time between several pairs of calls to
  gettimeofday().  It provides the additional capability to produce graphical
  output as a histogram or a scatter graph.


func/matrix_mult testcases  :
============================
matrix_mult.c:
- Compares running sequential matrix multiplication routines to running them
  in parallel in order to judge multiprocessor performance.
  Test runs for 100 iterations and calculates the average time.


func/measurement testcases :
============================
preempt_timing.c:
- Measures the preemption delays that may be encountered by realtime apps.
  The program runs with the scheduling policy of SCHED_FIFO at a maximum
  SCHED_FIFO priority.  It is bound to a single processor and its address space
  is locked as well.  It makes successive calls to the gettimeofday() function
  (via inlined assembly to read the TSC).  The value returned between two such
  consecutive calls is reported as the latency.  The maximum, minimum and
  average delays are reported for x pairs of such calls.

rdtsc-latency.c:
- Measures the time between several pairs of calls to rdtsc(); rdtsc counts
  the timestamp clock


func/periodic_cpu_load testcases :
==================================
periodic_cpu_load.c:
- Measures variation in computational execution time at various periods and
  priorities.  This provides the timing information at different CPU loads.

periodic_cpu_load_single.c:
- Measures variation in computational execution time at specified period
  priority and loop.


func/pi-tests testcases :
=========================
testpi-0.c:
- Tests whether the priority inheritance feature is present in kernel

testpi-1.c:
-  Priority inheritance under two different scenarios.  It checks whether the
   presence of priority inheritance allows higher priority threads to make more
   progress than in absence of the same.

testpi-2.c:
-  Introduces a noise thread in above test and checks if the high priority
   thread preempts low prio thread multiple times

testpi-4.c:
-  The scheduling policies of threads are different from previous testcase

testpi-5.c:
-  Uses priority inheritance protocol (PTHREAD_PRIO_INHERIT) and uses
   test-skeleton.  Test creates a child thread which tries to acquire lock
   twice.

testpi-6.c:
- Uses robust mutex lock (PTHREAD_MUTEX_ROBUST) and uses test-skeleton for
  other things.

testpi-7.c:
- Measures latencies involved in priority boosting through priority inheritance

test-skeleton.c:
- is a skeleton test which creates two processes through fork().  Also it
  handles signals by noting down timing information.

sbrk_mutex.c:
- Uses  NUM_THREADS to walk through an array of malloc'd pthread mutexes.
  Each thread holds up to NUM_CONCURRENT locks at a time.


func/prio-preempt testcases :
=============================
prio-preempt.c:
- Tests priority preemption.  Main thread creates multiple number of threads
  with different priorities, all fight for holding mutexes.  Threads sleep and
  wake-up with condvars.  Testcase exhibit scheduling of threads in accordance
  with priority-preemption.


func/prio-wake testcases :
==========================
prio-wake.c:
- Tests priority ordered wakeup with pthread_cond_*.  It creates number of
  worker threads with increasing FIFO priorities.  By default, the number of
  worker threads is equal to number of cpus.  The time when worker thread
  starts running is noted.  Each of the worker thread then waits on same
  _condvar_.  The time it wakes up is also noted.  Once all the threads finish
  execution, the start and wakeup times of all the threads are displayed.  The
  output must indicate that the thread wakeup happened in a priority order.



func/pthread_kill_latency testcases :
====================================
pthread_kill_latency.c:
- Measures the latency involved in sending a signal to a thread using
  pthread_kill.  Two threads are created - the one that receives the signal
  (thread1) and other that sends signal (thread2).  Before sending the signal,
  the thread2 waits for thread1 to initialize, notes the time and sends
  pthread_kill signal to thread1.  Thread2, which has defined a handler for the
  signal, notes the time it receives the signal.  The maximum and minimum
  latency is reported.


func/sched_football testcases :
===============================
sched_football.c:
- A scheduler test that uses a football analogy.  The premise is that we want
  to make sure that lower priority threads (the offensive team) do not preempt
  higher priority threads (the defensive team).


func/sched_jitter testcases :
=============================
sched_jitter.c:
- Measures scheduling jitter between realtime processes.


func/sched_latency testcases :
==============================
sched_latency.c:
-  Measures the latency involved with periodic scheduling.  A thread is created
   at priority 89.  It periodically sleeps for a specified duration (PERIOD).
   The delay is measured as delay = (now - start - i*PERIOD) converted to
   microseconds where now = CLOCK_MONOTONIC gettime in ns, start =
   CLOCK_MONOTONIC gettime at the start of the test, i = iteration number,
   PERIOD = the period chosen.


func/thread_clock testcases :
=============================
tc-2.c:
- Check if clock_gettime is working properly.  This test creates NUMSLEEP
  threads that just sleep and NUMWORK threads that spend time on the CPU. It
  then reads the thread cpu clocks of all these threads and compares the sum
  of thread cpu clocks with the process that spend time on the CPU.  It then
  reads the cpu clock of all these threads and compares the sum of thread cpu
  clocks with the process cpu clock value.  The test expects that: the cpu
  clock of every sleeping thread shows close to zero value.  Sum of cpu clocks
  of all threads is comparable with the process cpu clock.


perf/latency testcases :
========================
pthread_cond_latency.c:
-  Measures latencies involved in pthread_cond_t

pthread_cond_many.c:
- Measures latencies involved in pthread_cond_t.  This test executes in
  many processes running together and contesting to being scheduled.


stress/pi-tests testcases :
===========================
testpi-3.c:
- Tests priority inheritance under stress conditions.  Test runs in two
  scenarios: non-pi and pi.


lookup_pi_state.c:
- Tests lookup_pi_state under stress conditions.  Test creates one master and
  several slave threads, all fighting for mutexes.