src/cpu/testers/gpu_ruby_test/README - public/gem5 - Git at Google

 /*
  * Copyright (c) 2017-2021 Advanced Micro Devices, Inc.
  * All rights reserved.
  *
  * For use for simulation and test purposes only
  *
  * Redistribution and use in source and binary forms, with or without
  * modification, are permitted provided that the following conditions are met:
  *
  * 1. Redistributions of source code must retain the above copyright notice,
  * this list of conditions and the following disclaimer.
  *
  * 2. Redistributions in binary form must reproduce the above copyright notice,
  * this list of conditions and the following disclaimer in the documentation
  * and/or other materials provided with the distribution.
  *
  * 3. Neither the name of the copyright holder nor the names of its
  * contributors may be used to endorse or promote products derived from this
  * software without specific prior written permission.
  *
  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  * POSSIBILITY OF SUCH DAMAGE.
  */

 This directory contains a tester for gem5 GPU protocols. Unlike the Ruby random
 teter, this tester does not rely on sequential consistency. Instead, it
 assumes tested protocols supports release consistency.

 ----- Getting Started -----

 To start using the tester quickly, you can use the following example command
 line to get running immediately:

 build/GCN3_X86/gem5.opt configs/example/ruby_gpu_random_test.py \
             --test-length=1000 --system-size=medium --cache-size=small

 An overview of the main command line options is as follows. For all options
 use `build/GCN3_X86/gem5.opt configs/example/ruby_gpu_random_test.py --help`
 or see the configuration file.

  * --cache-size (small, large): Use smaller sizes for testing evict, etc.
  * --system-size (small, medium, large): Effectively the number of threads in
                  the GPU model. Large size will have more contention. Larger
                  sizes are useful for checking contention.
  * --episode-length (short, medium, long): Number of loads and stores in an
                  episode. Episodes will also have atomics mixed in. See below
                  for a definition of episode.
  * --test-length (int): Number of episodes to execute. This will determine the
                  amount of time the tester runs for. Longer time will stress
                  the protocol harder.

 The remainder of this file describes the theory behind the tester design and
 a link to a more detailed research paper is provided at the end.

 ----- Theory Overview -----

 The GPU Ruby tester creates a system consisting of both CPU threads and GPU
 wavefronts. CPU threads are scalar, so there is one lane per CPU thread. GPU
 wavefront may have multiple lanes. The number of lanes is initialized when
 a thread/wavefront is created.

 Each thread/wavefront executes a number of episodes. Each episode is a series
 of memory actions (i.e., atomic, load, store, acquire and release). In a
 wavefront, all lanes execute the same sequence of actions, but they may target
 different addresses. One can think of an episode as a critical section which
 is bounded by a lock acquire in the beginning and a lock release at the end. An
 episode consists of actions in the following order:

 1 - Atomic action
 2 - Acquire action
 3 - A number of load and store actions
 4 - Release action
 5 - Atomic action that targets the same address as (1) does

 There are two separate set of addresses: atomic and non-atomic. Atomic actions
 target only atomic addresses. Load and store actions target only non-atomic
 addresses. Memory addresses are all 4-byte aligned in the tester.

 To test false sharing cases in which both atomic and non-atomic addresses are
 placed in the same cache line, we abstract out the concept of memory addresses
 from the tester's perspective by introducing the concept of location. Locations
 are numbered from 0 to N-1 (if there are N addresses). The first X locations
 [0..X-1] are atomic locations, and the rest are non-atomic locations.
 The 1-1 mapping between locations and addresses are randomly created when the
 tester is initialized.

 Per load and store action, its target location is selected so that there is no
 data race in the generated stream of memory requests at any time during the
 test. Since in Data-Race-Free model, the memory system's behavior is undefined
 in data race cases, we exclude data race scenarios from our protocol test.

 Once location per load/store action is determined, each thread/wavefront either
 loads current value at the location or stores an incremental value to that
 location. The tester maintains a table tracking all last writers and their
 written values, so we know what value should be returned from a load and what
 value should be written next at a particular location. Value returned from a
 load must match with the value written by the last writer.

 ----- Directory Structure -----

 ProtocolTester.hh/cc -- This is the main tester class that orchestrates the
                         entire test.
 AddressManager.hh/cc -- This manages address space, randomly maps address to
                         location, generates locations for all episodes,
                         maintains per-location last writer and validates
                         values returned from load actions.
 TesterThread.hh/cc   -- This is abstract class for CPU threads and GPU
                         wavefronts. It generates and executes a series of
                         episodes.
 CpuThread.hh/cc      -- Thread class for CPU threads. Not fully implemented yet
 GpuWavefront.hh/cc   -- Thread class for GPU wavefronts.
 Episode.hh/cc        -- Class to encapsulate an episode, notably including
                         episode load/store structure and ordering.

 For more detail, please see the following paper:

 T. Ta, X. Zhang, A. Gutierrez and B. M. Beckmann, "Autonomous Data-Race-Free
 GPU Testing," 2019 IEEE International Symposium on Workload Characterization
 (IISWC), Orlando, FL, USA, 2019, pp. 81-92, doi:
 10.1109/IISWC47752.2019.9042019.
	/*
	* Copyright (c) 2017-2021 Advanced Micro Devices, Inc.
	* All rights reserved.
	*
	* For use for simulation and test purposes only
	*
	* Redistribution and use in source and binary forms, with or without
	* modification, are permitted provided that the following conditions are met:
	*
	* 1. Redistributions of source code must retain the above copyright notice,
	* this list of conditions and the following disclaimer.
	*
	* 2. Redistributions in binary form must reproduce the above copyright notice,
	* this list of conditions and the following disclaimer in the documentation
	* and/or other materials provided with the distribution.
	*
	* 3. Neither the name of the copyright holder nor the names of its
	* contributors may be used to endorse or promote products derived from this
	* software without specific prior written permission.
	*
	* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
	* AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
	* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
	* ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
	* LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
	* CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
	* SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
	* INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
	* CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
	* ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
	* POSSIBILITY OF SUCH DAMAGE.
	*/

	This directory contains a tester for gem5 GPU protocols. Unlike the Ruby random
	teter, this tester does not rely on sequential consistency. Instead, it
	assumes tested protocols supports release consistency.

	----- Getting Started -----

	To start using the tester quickly, you can use the following example command
	line to get running immediately:

	build/GCN3_X86/gem5.opt configs/example/ruby_gpu_random_test.py \
	--test-length=1000 --system-size=medium --cache-size=small

	An overview of the main command line options is as follows. For all options
	use `build/GCN3_X86/gem5.opt configs/example/ruby_gpu_random_test.py --help`
	or see the configuration file.

	* --cache-size (small, large): Use smaller sizes for testing evict, etc.
	* --system-size (small, medium, large): Effectively the number of threads in
	the GPU model. Large size will have more contention. Larger
	sizes are useful for checking contention.
	* --episode-length (short, medium, long): Number of loads and stores in an
	episode. Episodes will also have atomics mixed in. See below
	for a definition of episode.
	* --test-length (int): Number of episodes to execute. This will determine the
	amount of time the tester runs for. Longer time will stress
	the protocol harder.

	The remainder of this file describes the theory behind the tester design and
	a link to a more detailed research paper is provided at the end.

	----- Theory Overview -----

	The GPU Ruby tester creates a system consisting of both CPU threads and GPU
	wavefronts. CPU threads are scalar, so there is one lane per CPU thread. GPU
	wavefront may have multiple lanes. The number of lanes is initialized when
	a thread/wavefront is created.

	Each thread/wavefront executes a number of episodes. Each episode is a series
	of memory actions (i.e., atomic, load, store, acquire and release). In a
	wavefront, all lanes execute the same sequence of actions, but they may target
	different addresses. One can think of an episode as a critical section which
	is bounded by a lock acquire in the beginning and a lock release at the end. An
	episode consists of actions in the following order:

	1 - Atomic action
	2 - Acquire action
	3 - A number of load and store actions
	4 - Release action
	5 - Atomic action that targets the same address as (1) does

	There are two separate set of addresses: atomic and non-atomic. Atomic actions
	target only atomic addresses. Load and store actions target only non-atomic
	addresses. Memory addresses are all 4-byte aligned in the tester.

	To test false sharing cases in which both atomic and non-atomic addresses are
	placed in the same cache line, we abstract out the concept of memory addresses
	from the tester's perspective by introducing the concept of location. Locations
	are numbered from 0 to N-1 (if there are N addresses). The first X locations
	[0..X-1] are atomic locations, and the rest are non-atomic locations.
	The 1-1 mapping between locations and addresses are randomly created when the
	tester is initialized.

	Per load and store action, its target location is selected so that there is no
	data race in the generated stream of memory requests at any time during the
	test. Since in Data-Race-Free model, the memory system's behavior is undefined
	in data race cases, we exclude data race scenarios from our protocol test.

	Once location per load/store action is determined, each thread/wavefront either
	loads current value at the location or stores an incremental value to that
	location. The tester maintains a table tracking all last writers and their
	written values, so we know what value should be returned from a load and what
	value should be written next at a particular location. Value returned from a
	load must match with the value written by the last writer.

	----- Directory Structure -----

	ProtocolTester.hh/cc -- This is the main tester class that orchestrates the
	entire test.
	AddressManager.hh/cc -- This manages address space, randomly maps address to
	location, generates locations for all episodes,
	maintains per-location last writer and validates
	values returned from load actions.
	TesterThread.hh/cc -- This is abstract class for CPU threads and GPU
	wavefronts. It generates and executes a series of
	episodes.
	CpuThread.hh/cc -- Thread class for CPU threads. Not fully implemented yet
	GpuWavefront.hh/cc -- Thread class for GPU wavefronts.
	Episode.hh/cc -- Class to encapsulate an episode, notably including
	episode load/store structure and ordering.

	For more detail, please see the following paper:

	T. Ta, X. Zhang, A. Gutierrez and B. M. Beckmann, "Autonomous Data-Race-Free
	GPU Testing," 2019 IEEE International Symposium on Workload Characterization
	(IISWC), Orlando, FL, USA, 2019, pp. 81-92, doi:
	10.1109/IISWC47752.2019.9042019.