grid_info.cuh File Reference

Information regarding the current kernel's launch grid and the calling thread's positions within it. More...

#include <kat/on_device/common.cuh>
#include <cassert>

Classes
struct	kat::dimensions_t
	A richer (kind-of-a-)wrapper for CUDA's dim3 class, used to specify dimensions for blocks and grid (up to 3 dimensions). More...

Namespaces
	kat::grid_info
	Convenience one-liners relating to grid dimensions, indices within the grid, block or warp, lane functionality etc.

Typedefs
using	kat::position_t = uint3
	A position within a 3-dimensional grid or block. More...

Enumerations
enum	: unsigned {   first_lane = 0,   last_lane = warp_size - 1 }
enum	{ half_warp_size = warp_size / 2 }
enum	{ half_warp_size = kat::grid_info::lane::half_warp_size }

Functions
template<unsigned Dimensionality = 3>
KAT_FD unsigned	kat::size (dimensions_t dims)
constexpr KAT_FHD bool	kat::operator== (const dimensions_t &lhs, const dimensions_t &rhs) noexcept
template<unsigned Dimensionality = 3>
constexpr KAT_FHD bool	kat::equals (const uint3 &lhs, const uint3 &rhs) noexcept
	A dimensions-conscious version of operator==.
template<unsigned Dimensionality = 3>
constexpr KAT_FHD bool	kat::equals (const dimensions_t &lhs, const dimensions_t &rhs) noexcept
template<unsigned Dimensionality = 3>
constexpr KAT_FHD bool	kat::less_than (const uint3 &lhs, const uint3 &rhs) noexcept
	A dimensions-conscious version of operator<.
template<unsigned Dimensionality = 3>
constexpr KAT_FHD bool	kat::less_than (const dimensions_t &lhs, const dimensions_t &rhs) noexcept
template<unsigned Dimensionality = 3, typename Size = unsigned>
KAT_FHD Size	kat::detail::row_major_linearization (position_t position, dimensions_t dims)
constexpr KAT_FHD bool	kat::dimensionality_is_canonical (dimensions_t dims)
	Determines whether a dimensions specification follows CUDA's convention of having non-trivial dimensions first. More...
template<unsigned Dimensionality = 3>
KAT_FD position_t	kat::grid_info::detail::last_position_for (dimensions_t dims)
template<unsigned Dimensionality = 3>
KAT_FD position_t	kat::grid_info::detail::first_position ()
KAT_FD dimensions_t	kat::grid_info::grid::dimensions_in_blocks ()
template<unsigned Dimensionality = 3>
KAT_FD unsigned	kat::grid_info::grid::num_blocks ()
KAT_FD position_t	kat::grid_info::grid::first_block_position ()
template<unsigned Dimensionality = 3>
KAT_FD position_t	kat::grid_info::grid::last_block_position ()
template<unsigned Dimensionality = 3>
KAT_FD dimensions_t	kat::grid_info::grid::dimensions_in_threads ()
KAT_FD dimensions_t	kat::grid_info::block::dimensions ()
KAT_FD position_t	kat::grid_info::block::position_in_grid ()
KAT_FD position_t	kat::grid_info::block::index ()
template<unsigned Dimensionality = 3>
KAT_FD bool	kat::grid_info::block::is_first_in_grid ()
template<unsigned Dimensionality = 3>
KAT_FD bool	kat::grid_info::block::is_last_in_grid ()
template<unsigned Dimensionality = 3>
KAT_FD grid_dimension_t	kat::grid_info::block::id_in_grid ()
	Produces the linearization of a block's index in the grid. More...
template<unsigned Dimensionality = 3>
KAT_FD grid_dimension_t	kat::grid_info::block::id ()
template<unsigned Dimensionality = 3>
KAT_FD grid_block_dimension_t	kat::grid_info::block::size ()
KAT_FD position_t	kat::grid_info::block::first_thread_position ()
template<unsigned Dimensionality = 3>
KAT_FD position_t	kat::grid_info::block::last_thread_position ()
template<unsigned Dimensionality = 3>
KAT_FD grid_block_dimension_t	kat::grid_info::block::num_full_warps ()
template<unsigned Dimensionality = 3>
KAT_FD grid_block_dimension_t	kat::grid_info::block::num_warps ()
KAT_FD grid_block_dimension_t	kat::grid_info::block::id_of_first_warp ()
KAT_FD position_t	kat::grid_info::block::index_of_first_warp ()
KAT_FD grid_block_dimension_t	kat::grid_info::block::id_of_last_warp ()
KAT_FD bool	kat::grid_info::block::is_linear ()
KAT_FD bool	kat::grid_info::grid::is_linear ()
	Determines whether the grid's non-trivial dimensions - in blocks and in threads - are on the x axis only. More...
template<unsigned OuterDimensionality = 3, unsigned InnerDimensionality = 3>
KAT_FD unsigned	kat::grid_info::grid::num_warps ()
template<unsigned OuterDimensionality = 3, unsigned InnerDimensionality = 3>
KAT_FD unsigned	kat::grid_info::grid::num_threads ()
template<unsigned OuterDimensionality = 3, unsigned InnerDimensionality = 3>
KAT_FD unsigned	kat::grid_info::grid::total_size ()
template<unsigned Dimensionality = 3>
KAT_FD unsigned	kat::grid_info::grid::num_warps_per_block ()
KAT_FD unsigned	kat::grid_info::warp::size ()
KAT_FD unsigned	kat::grid_info::warp::length ()
KAT_FD position_t	kat::grid_info::thread::position_in_block ()
KAT_FD position_t	kat::grid_info::thread::position ()
KAT_FD position_t	kat::grid_info::thread::index_in_block ()
KAT_FD position_t	kat::grid_info::thread::index ()
template<unsigned Dimensionality = 3>
KAT_FD bool	kat::grid_info::thread::is_first_in_block ()
template<unsigned Dimensionality = 3>
KAT_FD bool	kat::grid_info::thread::is_last_in_block ()
template<unsigned OuterDimensionality = 3, unsigned InnerDimensionality = 3>
KAT_FD bool	kat::grid_info::thread::is_first_in_grid ()
template<unsigned OuterDimensionality = 3, unsigned InnerDimensionality = 3>
KAT_FD bool	kat::grid_info::thread::is_last_in_grid ()
template<unsigned Dimensionality = 3>
KAT_FD unsigned	kat::grid_info::thread::id_in_block (position_t thread_position_in_block)
	Linearizes of a thread's position within its block. More...
template<unsigned Dimensionality = 3>
KAT_FD unsigned	kat::grid_info::thread::id_in_block ()
template<unsigned Dimensionality = 3>
KAT_FD unsigned	kat::grid_info::thread::id ()
template<unsigned Dimensionality = 3>
KAT_FD position_t	kat::grid_info::thread::position_in_grid (position_t block_position_in_grid, position_t thread_position_in_block)
template<unsigned OuterDimensionality = 3>
KAT_FD unsigned	kat::grid_info::thread::id_in_grid (unsigned block_id_in_grid, unsigned thread_id_in_block)
template<unsigned OuterDimensionality = 3, unsigned InnerDimensionality = 3>
KAT_FD unsigned	kat::grid_info::thread::id_in_grid (position_t block_position_in_grid, position_t thread_position_in_block)
template<unsigned OuterDimensionality = 3, unsigned InnerDimensionality = 3>
KAT_FD unsigned	kat::grid_info::thread::id_in_grid ()
template<unsigned OuterDimensionality = 3, unsigned InnerDimensionality = 3>
KAT_FD position_t	kat::grid_info::thread::position_in_grid ()
template<unsigned OuterDimensionality = 3, unsigned InnerDimensionality = 3>
KAT_FD position_t	kat::grid_info::thread::index_in_grid ()
template<unsigned OuterDimensionality = 3, unsigned InnerDimensionality = 3>
KAT_FD unsigned	kat::grid_info::thread::global_id ()
template<unsigned OuterDimensionality = 3, unsigned InnerDimensionality = 3>
KAT_FD position_t	kat::grid_info::thread::global_index ()
template<unsigned Dimensionality = 3>
KAT_FD unsigned	kat::grid_info::warp::id_in_block ()
template<unsigned Dimensionality = 3>
KAT_FD unsigned	kat::grid_info::warp::index_in_block ()
template<unsigned OuterDimensionality = 3, unsigned InnerDimensionality = 3>
KAT_FD unsigned	kat::grid_info::warp::id_in_grid ()
template<unsigned Dimensionality>
KAT_FD unsigned	kat::grid_info::warp::index ()
template<unsigned OuterDimensionality = 3, unsigned InnerDimensionality = 3>
KAT_FD unsigned	kat::grid_info::warp::global_id ()
template<unsigned Dimensionality = 3>
KAT_FD unsigned	kat::grid_info::warp::id_of_first_lane ()
template<unsigned Dimensionality = 3>
KAT_FD unsigned	kat::grid_info::warp::index_in_block_of_first_lane ()
template<unsigned Dimensionality = 3>
KAT_FD unsigned	kat::grid_info::warp::global_id_of_first_lane ()
template<unsigned Dimensionality = 3>
KAT_FD unsigned	kat::grid_info::warp::index_in_grid_of_first_lane ()
template<unsigned Dimensionality = 3>
KAT_FD unsigned	kat::grid_info::warp::id ()
template<unsigned Dimensionality = 3>
KAT_FD bool	kat::grid_info::warp::is_first_in_block ()
template<unsigned Dimensionality = 3>
KAT_FD bool	kat::grid_info::warp::is_last_in_block ()
template<unsigned Dimensionality = 3>
KAT_FD bool	kat::grid_info::warp::is_first_in_grid ()
template<unsigned Dimensionality = 3>
KAT_FD bool	kat::grid_info::warp::is_last_in_grid ()
template<unsigned Dimensionality = 3>
KAT_FD unsigned	kat::grid_info::lane::id (position_t thread_position)
template<unsigned Dimensionality = 3>
KAT_FD unsigned	kat::grid_info::lane::id_in_warp ()
template<unsigned Dimensionality = 3>
KAT_FD unsigned	kat::grid_info::lane::id ()
template<unsigned Dimensionality = 3>
KAT_FD unsigned	kat::grid_info::lane::index ()
template<unsigned Dimensionality = 3>
KAT_FD unsigned	kat::grid_info::lane::index_in_warp ()
template<unsigned Dimensionality = 3>
KAT_FD unsigned	kat::grid_info::lane::is_first ()
template<unsigned Dimensionality = 3>
KAT_FD unsigned	kat::grid_info::lane::is_last ()
template<unsigned Dimensionality = 3>
KAT_FD bool	kat::grid_info::thread::is_first_in_warp ()
template<unsigned Dimensionality = 3>
KAT_FD bool	kat::grid_info::thread::is_last_in_warp ()
KAT_FD grid_dimension_t	kat::linear_grid::grid_info::grid::num_blocks ()
KAT_FD grid_dimension_t	kat::linear_grid::grid_info::grid::dimensions_in_blocks ()
KAT_FD grid_dimension_t	kat::linear_grid::grid_info::grid::index_of_first_block ()
KAT_FD grid_dimension_t	kat::linear_grid::grid_info::grid::index_of_last_block ()
KAT_FD grid_dimension_t	kat::linear_grid::grid_info::grid::first_block_position ()
KAT_FD grid_dimension_t	kat::linear_grid::grid_info::grid::first_last_position ()
KAT_FD unsigned	kat::linear_grid::grid_info::block::index_in_grid ()
KAT_FD grid_block_dimension_t	kat::linear_grid::grid_info::block::index ()
KAT_FD unsigned	kat::linear_grid::grid_info::block::id_in_grid ()
KAT_FD grid_block_dimension_t	kat::linear_grid::grid_info::block::id ()
KAT_FD grid_block_dimension_t	kat::linear_grid::grid_info::block::position_in_grid ()
KAT_FD bool	kat::linear_grid::grid_info::block::is_first_in_grid ()
KAT_FD bool	kat::linear_grid::grid_info::block::is_last_in_grid ()
KAT_FD grid_block_dimension_t	kat::linear_grid::grid_info::block::length ()
KAT_FD grid_block_dimension_t	kat::linear_grid::grid_info::block::size ()
KAT_FD grid_block_dimension_t	kat::linear_grid::grid_info::block::num_threads ()
KAT_FD unsigned	kat::linear_grid::grid_info::block::num_full_warps ()
KAT_FD unsigned	kat::linear_grid::grid_info::block::index_of_first_thread ()
KAT_FD unsigned	kat::linear_grid::grid_info::block::index_of_last_thread ()
KAT_FD unsigned	kat::linear_grid::grid_info::block::first_thread_position ()
KAT_FD unsigned	kat::linear_grid::grid_info::block::last_thread_position ()
KAT_FD unsigned	kat::linear_grid::grid_info::block::num_warps ()
KAT_FD grid_block_dimension_t	kat::linear_grid::grid_info::block::index_of_first_warp ()
KAT_FD grid_block_dimension_t	kat::linear_grid::grid_info::block::index_of_last_warp ()
KAT_FD grid_block_dimension_t	kat::linear_grid::grid_info::block::index_of_last_full_warp ()
KAT_FD bool	kat::linear_grid::grid_info::block::is_linear ()
KAT_FD dimensions_t	kat::linear_grid::grid_info::block::dimensions_in_threads ()
KAT_FD unsigned	kat::linear_grid::grid_info::grid::num_warps ()
KAT_FD unsigned	kat::linear_grid::grid_info::grid::num_threads ()
KAT_FD unsigned	kat::linear_grid::grid_info::grid::total_size ()
KAT_FD unsigned	kat::linear_grid::grid_info::grid::num_warps_per_block ()
KAT_FD grid_block_dimension_t	kat::linear_grid::grid_info::thread::index_in_block (uint3 position_in_block)
KAT_FD grid_block_dimension_t	kat::linear_grid::grid_info::thread::index_in_block ()
KAT_FD grid_block_dimension_t	kat::linear_grid::grid_info::thread::id_in_block (uint3 position_in_block)
KAT_FD grid_block_dimension_t	kat::linear_grid::grid_info::thread::index ()
KAT_FD grid_block_dimension_t	kat::linear_grid::grid_info::thread::id_in_block ()
KAT_FD grid_block_dimension_t	kat::linear_grid::grid_info::thread::id ()
KAT_FD grid_block_dimension_t	kat::linear_grid::grid_info::thread::position ()
KAT_FD grid_block_dimension_t	kat::linear_grid::grid_info::thread::position_in_block ()
KAT_FD bool	kat::linear_grid::grid_info::thread::is_first_in_block ()
KAT_FD bool	kat::linear_grid::grid_info::thread::is_last_in_block ()
KAT_FD bool	kat::linear_grid::grid_info::thread::is_first_in_grid ()
KAT_FD bool	kat::linear_grid::grid_info::thread::is_last_in_grid ()
KAT_FD unsigned	kat::linear_grid::grid_info::thread::index_in_grid (grid_dimension_t block_index, grid_dimension_t thread_index)
	Returns the global index of the thread - not within the block (the work group), but considering all threads for the current kernel together - assuming a one-dimensional grid.
KAT_FD unsigned	kat::linear_grid::grid_info::thread::id_in_grid (grid_dimension_t block_index, grid_dimension_t thread_index)
KAT_FD unsigned	kat::linear_grid::grid_info::thread::index_in_grid ()
KAT_FD unsigned	kat::linear_grid::grid_info::thread::id_in_grid ()
KAT_FD unsigned	kat::linear_grid::grid_info::thread::global_index ()
KAT_FD unsigned	kat::linear_grid::grid_info::thread::global_id ()
KAT_FD unsigned	kat::linear_grid::grid_info::thread::block_stride_start_position (unsigned serialization_factor=1)
	Use this for kernels in a 1-dimensional (linear) grid, in which each block of K threads handles K * serialization_factor consecutive elements. More...
KAT_FD grid_block_dimension_t	kat::linear_grid::grid_info::warp::index_in_block ()
KAT_FD grid_block_dimension_t	kat::linear_grid::grid_info::warp::index ()
KAT_FD grid_block_dimension_t	kat::linear_grid::grid_info::warp::id_in_block ()
KAT_FD grid_block_dimension_t	kat::linear_grid::grid_info::warp::id ()
KAT_FD unsigned	kat::linear_grid::grid_info::warp::index_in_grid ()
KAT_FD unsigned	kat::linear_grid::grid_info::warp::id_in_grid ()
KAT_FD unsigned	kat::linear_grid::grid_info::warp::global_index ()
KAT_FD unsigned	kat::linear_grid::grid_info::warp::global_id ()
KAT_FD unsigned	kat::linear_grid::grid_info::warp::index_of_first_lane ()
KAT_FD unsigned	kat::linear_grid::grid_info::warp::index_in_block_of_first_lane ()
KAT_FD unsigned	kat::linear_grid::grid_info::warp::global_index_of_first_lane ()
KAT_FD unsigned	kat::linear_grid::grid_info::warp::index_in_grid_of_first_lane ()
KAT_FD bool	kat::linear_grid::grid_info::warp::is_first_in_block ()
KAT_FD bool	kat::linear_grid::grid_info::warp::is_last_in_block ()
KAT_FD bool	kat::linear_grid::grid_info::warp::is_first_in_grid ()
KAT_FD bool	kat::linear_grid::grid_info::warp::is_last_in_grid ()
KAT_FD unsigned	kat::linear_grid::grid_info::lane::id (unsigned thread_index)
KAT_FD unsigned	kat::linear_grid::grid_info::lane::id_in_warp ()
KAT_FD unsigned	kat::linear_grid::grid_info::lane::id ()
KAT_FD unsigned	kat::linear_grid::grid_info::lane::index ()
KAT_FD unsigned	kat::linear_grid::grid_info::lane::index_in_warp ()
KAT_FD unsigned	kat::linear_grid::grid_info::lane::is_first ()
KAT_FD unsigned	kat::linear_grid::grid_info::lane::is_last ()
KAT_FHD unsigned	kat::linear_grid::grid_info::lane::id_in_half_warp (unsigned thread_or_lane_index)
KAT_FD unsigned	kat::linear_grid::grid_info::lane::id_in_half_warp ()
KAT_FD unsigned	kat::linear_grid::grid_info::lane::index_in_half_warp ()
KAT_FD unsigned	kat::linear_grid::grid_info::lane::is_in_first_half_warp ()
KAT_FD unsigned	kat::linear_grid::grid_info::lane::is_in_second_half_warp ()

Detailed Description

Information regarding the current kernel's launch grid and the calling thread's positions within it.

Note

Currently, CUDA does not allows more than 2^31 threads in a launch grid, hence many functions here return unsigned / dimension_t

CUDA uses the term "index" for the 3-dimensional position within a block or a grid, and the term "id" for the position in a linearization of that block or grid. This is somewhat confusing, as the switching of those terms would be more in line with their literal, dictionary definitions; however - for consistency, the functions in this file maintain the same convention. So,

IF YOU WANT TO GET –== A SINGLE NUMBER ==– , USE id() METHODS
IF YOU WANT TO GET –== 3-D COORDINATES ==– , USE index() METHODS

however, the above applies only for 3-D grids. When the grid is linear, we drop the distinction between "index" and "id". Also, warp ID's are always linearized, since they don't respect the multi-dimensional structure.

Typedef Documentation

position_t

using kat::position_t = typedef uint3

A position within a 3-dimensional grid or block.

Note

all coordinates are non-negative - positions are taken from the "corner", not the center.

Function Documentation

block_stride_start_position()

KAT_FD unsigned kat::linear_grid::grid_info::thread::block_stride_start_position

(

unsigned

serialization_factor = 1

)

Use this for kernels in a 1-dimensional (linear) grid, in which each block of K threads handles K * serialization_factor consecutive elements.

That's pretty common... (?)

Anyway, each individual thread accesses data with a stride of K.

Parameters

serialization_factor

The number of elements each thread would access

Returns

the initial position for a given thread

dimensionality_is_canonical()

constexpr KAT_FHD bool kat::dimensionality_is_canonical

(

dimensions_t

dims

)

Determines whether a dimensions specification follows CUDA's convention of having non-trivial dimensions first.

Parameters

[in]

dims

A dimensions specification. Assumed to not be "empty", i.e. assumed to have a value of at least 1 in every axis.

Returns

true if no non-trivial dimensions follow trivial dimensions

dimensions_in_blocks()

KAT_FD dimensions_t kat::grid_info::grid::dimensions_in_blocks

(

)

Note

These are the dimensions of the grid over blocks; the blocks may have additional "dimensions" relative to threads.

dimensions_in_threads() [1/2]

template<unsigned Dimensionality = 3>

KAT_FD dimensions_t kat::grid_info::grid::dimensions_in_threads

(

)

Note

These are the dimensions of the grid in terms of threads. This means that a grid can have less blocks (or even one block) in each dimension, but each block many have multiple threads, contributing to the overall dimension.

dimensions_in_threads() [2/2]

KAT_FD dimensions_t kat::linear_grid::grid_info::block::dimensions_in_threads

(

)

Note

These are the dimensions of the grid in terms of threads. This means that a grid can have less blocks (or even one block) in each dimension, but each block many have multiple threads, contributing to the overall dimension.

id_in_block()

template<unsigned Dimensionality = 3>

KAT_FD unsigned kat::grid_info::thread::id_in_block

(

position_t

thread_position_in_block

)

Linearizes of a thread's position within its block.

Parameters

thread_position_in_block

the Dimensionality-dimensional version of the thread index within its grid block, represented in the 3-dimensional dimensions_t structure

Returns

The 1-d index of the specified thread within its block, when it's flattened so that threads with identical z and y axis coordinates form a contiguous sequence

id_in_grid()

template<unsigned Dimensionality = 3>

KAT_FD grid_dimension_t kat::grid_info::block::id_in_grid

(

)

Produces the linearization of a block's index in the grid.

Note

Remember a thread's index is a multi-dimensional entity, not a single linear value. The id is the linearization of the index

index()

KAT_FD position_t kat::grid_info::block::index

(

)

Note

Remember a thread's index is a multi-dimensional entity, not a single linear value

is_linear() [1/2]

KAT_FD bool kat::grid_info::block::is_linear

(

)

Note

assumes linear kernels only use the x dimension - which is a reasonable assumptions, since the y and z dimensions are limited in extent by CUDA.

is_linear() [2/2]

KAT_FD bool kat::grid_info::grid::is_linear

(

)

Determines whether the grid's non-trivial dimensions - in blocks and in threads - are on the x axis only.

Note

One could consider y-only or z-only dimensions as linear; this definition was chosen for convenience (and performance) and is used throughout this library