TTL_tensors_common.h

Go to the documentation of this file.

/*
 * TTL_tensors_common.h
 *
 * Copyright (c) 2023 Mobileye
 *
 * Licensed under the Apache License, Version 2.0 (the License);
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an AS IS BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
 
/************************************************************************************************************
 * Allow for sizeof anything - deals with sizeof(void)
 ************************************************************************************************************/
 
/**
 * @def TTL_SIZEOF
 *
 * @brief opencl doesn't like sizeof(void) so for it to be 1 like normal c
 *
 * OpenCl will produce error: invalid application of 'sizeof' to a void type
 *
 * This will need to be expanded with more types - or a different language used!
 */
 
/************************************************************************************************************
 * Define Layout
 ***********************************************************************************************************/
 
/**
 * @brief Description of a Tensor layout in memory
 *
 * Each logical tensor is embedded in both global and local memories within some
 * enclosing physical tensors.
 *
 * This embedding is referred to as 'layout', which specifies the actual distance in elements
 * between the start of consecutive data elements in each dimension.
 *
 * For the first axis the distance is always 1 element and and so this value is not stored.
 *
 * line_length and plane_area in memory, in units of an element.
 */
typedef struct {
    TTL_dim_t row_spacing;    ///< The distance between the start of consequtive rows in units of elements.
    TTL_dim_t plane_spacing;  ///< The distance between the start of consequtive planes in units of elements.
} TTL_layout_t;
 
/**
 * @brief Create a 3D Description of a Tensor layout in memory
 *
 * @see TTL_layout_t for more information.
 *
 * @param row_spacing;   The distance between the start of consequtive rows in units of elements.
 * @param plane_spacing;   The distance between the start of consequtive planes in units of elements.
 *
 * @return A TTL_layout_t describing in 3D the layout requested.
 */
static inline TTL_layout_t __attribute__((overloadable)) TTL_create_layout(const TTL_dim_t row_spacing,
                                                                           const TTL_dim_t plane_spacing) {
    const TTL_layout_t res = { row_spacing, plane_spacing };
    return res;
}
 
/**
 * @brief Create a 2D Description of a Tensor layout in memory
 *
 * @see TTL_layout_t for more information.
 *
 * @param row_spacing The distance between the start of consequtive rows in units of elements.
 *
 * The plane spacing is set to 0 - as no planes exist to be spaced.
 *
 * @return A TTL_layout_t describing in 3D the layout requested.
 */
static inline TTL_layout_t __attribute__((overloadable)) TTL_create_layout(const TTL_dim_t row_spacing) {
    return TTL_create_layout(row_spacing, 0);
}
 
/**
 * @brief Create a 1D Description of a Tensor layout in memory
 *
 * @see TTL_layout_t for more information.
 *
 * The row spacing is set to 0 - as no rows exist to be spaced.
 * The plane spacing is set to 0 - as no planes exist to be spaced.
 **
 * @return A TTL_layout_t describing in 3D the layout requested.
 */
static inline TTL_layout_t __attribute__((overloadable)) TTL_create_layout(void) {
    return TTL_create_layout(0, 0);
}
 
/**
 * @brief Calculate the absolute linear offset in elements, based on a given
 * tensor offset and layout
 *
 * @param offset The 3D offset of the required linear offset.
 * @param layout The layout of the offset being calculated
 *
 * @return The offset in linear address space of the 3D offset
 */
static inline TTL_offset_dim_t TTL_linearize(const TTL_offset_t offset, const TTL_layout_t layout) {
    return ((offset.z * layout.plane_spacing) + (offset.y * layout.row_spacing) + offset.x);
}
 
/************************************************************************************************************
 * Structure of a tensor
 ***********************************************************************************************************/
 
/**
 * @def __TTL_typedef_tensor_t
 *
 * @brief A poor mans base class for an a tensor in the passed address space
 *
 * TTL_int_tensor_base_t contains both the logical dimensions of a tile as well as
 * its physical mapping to memory.
 *
 * @param TTL_scope The scope of the creation can be TTL_global or TTL_local
 * @param const_1 The const name to place after the prefix - should be empty or const_
 * @param location The location of the tensor - should be ext or int
 * @param type The type of the tensor - should be any valid c type
 * @param const_2 The const type to create - should be empty or const
 */
/**
 * @def __TTL_typedef_sub_tensor_t
 *
 * @brief A tensor plus its reference to its parent tensor
 *
 * __TTL_sub_tensor_t contains both the logical dimensions of a tile as well as
 * its physical mapping to memory.
 *
 * @param TTL_scope The scope of the creation can be TTL_global or TTL_local
 * @param const_1 The const name to place after the prefix - should be empty or const_
 * @param location The location of the tensor - should be ext or int
 * @param type The type of the tensor - should be any valid c type
 * @param const_2 The const type to create - should be empty or const
 */
/************************************************************************************************************
 * Creation of tensors
 ************************************************************************************************************/
 
/**
 * @brief Implementation of TTL_create_int_tensor
 *
 * @see TTL_create_int_tensor for full API and parameter information
 *
 * @param TTL_scope The scope of the creation can be TTL_global or TTL_local
 * @param const_1 The const name to place after the prefix - should be empty or const_
 * @param location The location of the tensor - should be ext or int
 * @param type The type of the tensor - should be any valid c type
 * @param const_2 The const type to create - should be empty or const
 */
/**
 * @brief Implementation of TTL_create_int_sub_tensor
 *
 * @see TTL_create_int_sub_tensor for full API and parameter information
 */
/************************************************************************************************************
 * Create the create tensor functions for different overloads
 ************************************************************************************************************/