Cyclicload test-tool is designed to simulate
load in form of one or two load threads.
Signed-off-by: Priyanka Jain <Priyanka.Jain@xxxxxxxxxxxxx>
---
src/cyclicload/README | 273 +++++++++++++++++++++++++++++++++++++++++++++++++
1 files changed, 273 insertions(+), 0 deletions(-)
create mode 100644 src/cyclicload/README
diff --git a/src/cyclicload/README b/src/cyclicload/README
new file mode 100644
index 0000000..b95b517
--- /dev/null
+++ b/src/cyclicload/README
@@ -0,0 +1,273 @@
+ABSTRACT
+---------
+While developing an embedded product at the level of unit testing or
+component testing, it is often a requirement to test it under a
+specified load so that test setup is close to the real product.
+E.g while working on Linux Network stack targeted for LTE product,
+requirement is to simulate L2 stack load for unit testing of Linux
+network stack. Also as the load can be of Real-time (RT) type or
+Non Real-Time (NRT) type, requirement is to simulate load of both
+types.
+Cyclicload has been developed to meet these requirements.
+It can simulate RT and/or NRT type of load in form of load threads.
+
+
+
+INTRODUCTION
+-------------
+Cyclicload is a test tool, designed to simulate system load
+for unit/component testing.
+It can simulate user-defined load at user-defined interval
+of user-defined priority/nice values.
+It is also capable or producing simultaneous Real-Time critical
+(RT) as well as Non Real-Time (NRT) critical type of load.
+It can work for both uniprocessor as well as multiprocessor.
+
+
+
+WHAT DOES IT DO
+---------------
+It creates one or two load generating thread/s.
+1) Simulated load1_thread
+ -of RT type
+ -can run for load of 0% to 99%
+2) Simulated load2_thread
+ -can be of RT or NRT type
+ -can run for load of 0% to 99%
+
+Priority, nice value, load%, etc as input via command line.
+Also sum of 'load1' and 'load2' should not be greater than 99%
+as 1% has been reserved for control framework.
+
+
+HOW DOES IT WORK
+-----------------
+Cyclicload workflow can be broadly divided into following stages
+1) Initialization stage
+ a) Calibration
+ b) Other initialization
+2) Load producing stage
+3) Exit stage
+
+1) Initialization stage
+Calibration is the most important part of this stage from
+functional point of view as calibration data can vary from
+system to system or for various configurations on same system.
+But as generally for given set of configuration on a particular
+system, calibration output is same, it is kept as optional part
+depending on presence of 'calibrate_count' file.
+
+First it calibrates required loop_count per unit time per CPU to
+simulate load for a unit time. It stores this data in
+'calibrate_count' file.
+For the same run or subsequent runs on the same system,
+it uses this calibrated data to generate load.
+It is recommended to run cyclicload with no other load
+present on the system for proper calibration to generate
+'calibrate_count' file and then use this file for the next run.
+
+2) Load producing stage
+This is the actual testing stage.
+In this stage, cyclicload calls a loop after every regular interval.
+In this interval, it generates 'load1', 'load2' and then waits for the
+next interval.
+It might be possible that interval expires before the 'load2' completion.
+In that case it discards off the remaining load.
+
+3)Exit stage
+In this stage, it displays how much desired load it was able to simulate
+in form of percentage of actual load run verses the desired load.
+
+For design details, see the DESIGN OVERVIEW SECTION.
+
+
+EXAMPLE USE CASE
+-----------------
+For better understanding of why this tool is required, what does it
+do and how does it works, let's consider an example use-case of LTE
+products.
+
+LTE system has many software components running on it:
+LTE layer2 stack having some Real time critical tasks
+like MAC thread and non-real time critical tasks like PDCP,
+Linux network stack, etc.
+While doing unit testing of Linux Network stack driver,
+one generally has a requirement to build the test setup which
+is close to the target LTE product. But making the complete
+LTE setup with EPC, eNodeB, etc is not always feasible.
+Cyclicload comes very handy here in simulating the LTE type
+of load.
+
+Let's assume LTE layer2 stack has 30% of real-time critical load
+and 20% on non-real time type.
+
+Cyclicload can first calibrate how much loop_count is required to
+generate a particular load. It can then use this output to simulate
+load in form of two threads:
+1) load1_thread
+ -running at RT priority
+ -producing 30% load
+ -simulating RT load on LTE layer2 stack
+
+2) load2_thread
+ -running at NRT priority
+ -producing 20% load
+ -simulating NRT load on LTE layer2 stack.
+
+This setup with simulated load can now be used to test the behavior
+of Linux network stack under the presence of simulated LTE layer2 load.
+
+Also, on completion, it displays how much ‘load1’ and ‘load2’
+it was able to simulate giving the user an idea of how much
+CPU bandwidth is available for the actual load in the system.
+
+Above example clearly showcase that one can do
+system optimization at unit level.
+
+
+COMMAND LINE ARGUMENTS/EXAMPLES
+-------------------------------
+
+Some of command line arguments:
+ "-x --load_t1 load in percentage for t1 thread"
+ "-X --load_t2 load in percentage for t2 thread"
+ "-z --priority_t2 priority of t2 thread"
+ "-Z --nice_t2 nice value of t2 thread"
+
+For more details on arguments, see cyclicload.8 file
+
+If both load_t1 and load_t2 are zero, it behaves as default cyclictest application
+
+ #sudo ./cyclicload -p 99 -S -c 1 -d 0 -x 20 -X 30 -q -D 600&
+
+For help,
+ #sudo ./cyclicload -help
+
+
+
+THINGS TO NOTE
+---------------
+Cyclicload has overhead of 0%-3% for 'load1' thread and
+'load2' thread. So this should be taken into account
+while running load.
+If someone has a requirement of more précised load,
+he can run 2-3 cycles of Cyclicload and check CPU load
+of load threads using applications like ‘top –H –d 60’
+to get an idea of extra load of threads on the
+particular system.
+This extra load is generally constant for the particular system.
+
+
+RECOMMENDED SETTINGS
+----------------------
+-First run is recommended to be run with no or least load for accuracy.
+-Should be run with sudo or root permission.
+-Calibration routine produces 'calibrate_count' file in 'pwd' directory.
+ If one don't have permission in that directory,
+ file path should be changed in FILENAME in source
+ code or one can exploit shared memory method.
+-As load1_thread in addition to load generation, also controls
+ intervals start and end, it is recommended to be run with
+ highest RT priority.
+-Recommended to run in quiet mode (-q) in background for more accurate
+ load generation.
+
+
+TESTED ON
+----------
+Tested on uni-processor and multi-processor PowerPC
+and i686 platforms having PREEMPT_RT Linux running on it.
+
+
+FUTURE ENHANCEMENTS
+-------------------
+-Add option to take filepath from command line.
+-Add option to flush caches in each interval to make it
+ close to actual possible scenario.
+-can be scalable to produce n number of load threads.
+-Test on other architectures.
+
+
+DESIGN OVERVIEW
+-----------------
+Cyclicload uses exiting cyclictest application present
+in rt-tests test suite as its base code. It adds logic
+for calibration and to simulate load above it.
+
+Cyclicload code can be functionally divided into following
+threads
+1) cyclicload process thread
+2) calibrate_thread
+3) timerthread ('load1' thread)
+4) load2_thread
+
+Details below
+
+1) cyclicload process thread
+--------------------------
+-Parse input arguments.
+
+-For first run (!'calibrate_count' file present):
+ -Creates 'calibrate_count' file.
+ -Create 'calibrate_thread'.
+ -Store calibrated count in 'calibrate_count' file
+
+-For subsequent runs ('calibrate_count' file present):
+ -Read calibrated count from file in
+ 'calibrate_count_array' and use that count
+ to simulate desired load.
+
+-Create t 'timerthread'
+ -Simulate CPU interval windows.
+ -'timerthread' also act as 'load1_thread'
+ -'t' depends on command-line argument
+ By default for SMP system
+ t = num of cores, one thread per core
+
+-Update stats periodically while !shutdown
+-Print stats periodically depending on command-line
+ argument while !shutdown
+
+
+2) calibrate_thread
+------------------
+-Is created only once for the first run of cyclicload
+ if 'calibrate_count' file is not present.
+-Runs at highest RT priority.
+-Affine itself turn by turn to each CPU.
+ (for all CPUs for Multicore system)
+-Calibrates loop-count per unit (ms by default) per CPU.
+-Stores per CPU data in calibrate_count_array (global array).
+
+
+3)timerthread ('load1' thread)
+---------------------------
+-Run at priority parsed in main routine
+-Creates 'load2_thread' if load2 is of nonzero value
+-Calculate number of loops to generate 'load1' and 'load2' by
+ using calibrate_count_array (global array) and
+ required load percentage parsed in main routine.
+-Calculates interval(window) and reduced interval for which
+ it should sleep.
+ reduced interval = interval(window) - duration for 'load1'
+-While loop until !shutdown
+ -Generates 'load1' load
+ -Sleep for reduced interval
+ -Calculates latency.
+ -Set next_window_started flag.
+ -Signal load2_thread about next window start.
+-Overhead: 0%-3% of full CPU utilization.
+ -Varies from system to system but generally constant
+ for a system.
+
+
+load2_thread
+------------
+-While loop until !shutdown
+ -Generates 'load2' load
+ if window expires before generate 'load2' finishes,
+ discards-off remaining load
+ -Waits for signal for next window to start.
+-Overhead: 0%-2% of full CPU utilization.
+ -Varies from system to system but generally constant
+ for a system.
--
1.7.4.1
--
To unsubscribe from this list: send the line "unsubscribe linux-rt-users" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
