MMALIB_types.h

Go to the documentation of this file.

/******************************************************************************
 *                                                                             *
 * module name       :MMALIB                                                   *
 *                                                                             *
 * module descripton :Matrix Multiply Accelerator Library module for C7x+MMA   *
 *                                                                             *
 * Copyright (C) 2017-2018 Texas Instruments Incorporated - https://www.ti.com/ *
 * ALL RIGHTS RESERVED                                                         *
 *                                                                             *
 ******************************************************************************/

#ifndef COMMON_MMALIB_TYPES_H_
#define COMMON_MMALIB_TYPES_H_ 1

/* This header is needed to be included in OpenCL programs which link
 * against MMALIB, but OpenCL doesn't need the following headers */
#ifndef __OPENCL_VERSION__
#include <stdint.h>
#include <stdlib.h>
#include <inttypes.h>
#include <stddef.h> // for NULL
#include <stdio.h>  // for printf
#endif
#include <c7x.h> // for streaming engine, streaming address gen.


#include "MMALIB_bufParams.h"
#include "TI_platforms.h"

#if defined (__C7100__) || defined (__device__)
#include "c71/MMALIB_defines.h"
#else
#error invalid target
#endif

#if defined (__C7100__)
#include "c7100/MMALIB_defines.h"
#include "c7100/MMALIB_types.h"
#endif


#if !defined(MMALIB_DEBUGPRINT)
#define MMALIB_DEBUGPRINT 0 
#endif
#if MMALIB_DEBUGPRINT == 1
#include "c71/MMALIB_debug.h"
#endif

#if (defined(_HOST_BUILD) && (MMALIB_COMPILER_VERSION < 1003999))
#define MMALIB_const
#else
#define MMALIB_const const
#endif

/* ---------------------------------------------------------------- */
/*  MISRAC Rule 4.9(DEFINE.FUNC) Deviation: The following two       */
/*  function-like macros do not have equivalent function            */
/*  implementations.                                                */
/* ---------------------------------------------------------------- */
#define MMALIB_DEBUGPRINTFN(N, fmt, ...)                                       \
  do {                                                                         \
    if (MMALIB_DEBUGPRINT >= (N)) {                                            \
      fprintf(stdout, "MMALIB debug %s - %d: " fmt, __FUNCTION__, __LINE__,    \
              __VA_ARGS__);                                                    \
    }                                                                          \
  } while (0)

#define MMALIB_PRINTF(fmt,...)                                                 \
   do {                                                                        \
      fprintf(stdout, fmt, __VA_ARGS__);                                       \
   } while (0)

#if defined(MMALIB_MESSAGES)
// if enabled, display messages to the library user
// MMALIB_MESSAGES should only be defined when TARGET_BUILD=debug or CHECKPARAMS=1
#define MMALIB_MESG(fmt, ...) fprintf(stderr, fmt, __VA_ARGS__)
#else
#define MMALIB_MESG(fmt, ...)
#endif //#if defined(MMALIB_MESSAGES)

/* Original implementation that had the benefit of always being compiled and thus
 receiving error checking.  However, the fprintf generates a MISRA-C violation.
#define MMALIB_DEBUGPRINTFN(N, fmt, ...)                                       \
  do {                                                                         \
    if (MMALIB_DEBUGPRINT >= (N)) {                                            \
      fprintf(stderr, "MMALIB debug %s - %d: " fmt, __FUNCTION__, __LINE__,    \
              __VA_ARGS__);                                                    \
    }                                                                          \
  } while (0)

#define MMALIB_PRINTF(fmt, ...)                                                \
   do {                                                                        \
       fprintf(stderr, fmt, __VA_ARGS__);                                      \
   } while (0)
#endif
 */


#define MMALIB_SOFT_MMA_RESET 0

// switch to enable or disable static inline for MMALIB functions defined in .c files (so not many functions)
#define MMALIB_STATIC_INLINE static inline


#ifdef __cplusplus
extern "C" {
#endif /* __cplusplus */

/* @{ */

/*******************************************************************************
 *
 * TYPEDEFS
 *
 ******************************************************************************/

typedef double MMALIB_D64; 
typedef float MMALIB_F32;  

typedef enum {
   MMALIB_SUCCESS = 0,           
   MMALIB_ERR_FAILURE = 1,       
   MMALIB_ERR_INVALID_VALUE = 2, 
   MMALIB_ERR_INVALID_TYPE  = 3, 
   MMALIB_ERR_INVALID_DIMENSION = 4, 
   MMALIB_ERR_NULL_POINTER = 5, 
   MMALIB_ERR_NOT_IMPLEMENTED = 6, 
   MMALIB_ERR_NOT_EQUAL_WIDTH_STRIDE = 7, 
   MMALIB_ERR_NOT_ALIGNED_PTRS_STRIDES = 8, 
   MMALIB_ERR_NOT_ALIGNED_WIDTHS = 9, 
   MMALIB_ERR_BUFFER_TOO_SMALL = 10, 
   MMALIB_ERR_INVALID_ACTIVATION = 11, 
   MMALIB_ERR_INVALID_SHIFT = 12,      
   MMALIB_ERROR_MAX = 13,
   // MMALIB_CNN_convolve_row
   MMALIB_ERR_CONVOLVE_ROW_INVALID_INCHOFFSET_CIRCULAR = 1000, 
   MMALIB_ERR_CONVOLVE_ROW_UNSUPPORTED_STRIDE  = 1001, 
   MMALIB_ERR_CONVOLVE_ROW_UNSUPPORTED_TYPE_COMBINATION = 1002, 
   MMALIB_ERR_CONVOLVE_ROW_INVALID_PTR_STRIDE = 1003, 
   MMALIB_ERR_CONVOLVE_ROW_INVALID_SUBMCHANNELS_STRIDE = 1004,  
   MMALIB_ERR_CONVOLVE_ROW_INVALID_SUBMCHANNELS = 1005,  
   MMALIB_ERR_CONVOLVE_ROW_INVALID_BUFFER_DIMENSION = 1006,  
   MMALIB_ERR_CONVOLVE_ROW_INVALID_ROWS_STRIDE = 1007, 
   MMALIB_ERR_CONVOLVE_ROW_INVALID_INITARGS = 1008, 
   MMALIB_ERR_CONVOLVE_ROW_INVALID_VALIDCOLSIN = 1009,  
   // MMALIB_CNN_convolve_col_smallNo
   MMALIB_ERR_CONVOLVE_COL_INVALID_SHIFTMETHOD = 2000, 
   MMALIB_ERR_CONVOLVE_COL_INVALID_SHIFTVALUES = 2001, 
   MMALIB_ERR_CONVOLVE_COL_INVALID_PAD_VALUES  = 2002, 
   MMALIB_ERR_CONVOLVE_COL_INVALID_NUMBIASVALS = 2003, 
   MMALIB_ERR_CONVOLVE_COL_INVALID_BIASBVALUES = 2004, 
   MMALIB_ERR_CONVOLVE_COL_INVALID_BIASB_TYPE  = 2005, 
   MMALIB_ERR_CONVOLVE_COL_UNSUPPORTED_INPUT_FEATURE_MAP_TYPE  = 2006, 
   MMALIB_ERR_CONVOLVE_COL_UNSUPPORTED_WEIGHTS_TYPE            = 2007, 
   MMALIB_ERR_CONVOLVE_COL_UNSUPPORTED_OUTPUT_FEATURE_MAP_TYPE = 2008, 
   MMALIB_ERR_CONVOLVE_COL_UNSUPPORTED_TYPE_COMBINATION        = 2009, 
   MMALIB_ERR_CONVOLVE_COL_UNSUPPORTED_STRIDE  = 2010, 
   MMALIB_ERR_CONVOLVE_COL_INVALID_CASE        = 2011, 
   // MMALIB_CNN_deconvolve_row
   MMALIB_ERR_DECONVOLVE_ROW_INVALID_KERNEL_SIZE = 3000, 
   MMALIB_ERR_DECONVOLVE_ROW_INVALID_STRIDE = 3001, 
   MMALIB_ERR_DECONVOLVE_ROW_INVALID_DILATION = 3002, 
   MMALIB_ERR_DECONVOLVE_ROW_INVALID_PAD = 3003, 
   MMALIB_ERR_DECONVOLVE_ROW_INVALID_INIT_ARGS = 3004, 
   MMALIB_ERR_DECONVOLVE_ROW_INVALID_BUFFER_DIMENSION_WEIGHTS = 3005, 
   MMALIB_ERR_DECONVOLVE_ROW_INVALID_SUBMCHANNELS = 3006,  
   MMALIB_ERR_DECONVOLVE_ROW_INVALID_BUFFER_SIZES = 3007,  
   // MMALIB_CNN_fullyConnected
   MMALIB_ERR_FULLYCONNECTED_INVALID_TYPE_COMBINATION = 4000, 
   MMALIB_ERR_FULLYCONNECTED_INVALID_DIMENSION_COMBINATION = 4001, 
   MMALIB_ERR_FULLYCONNECTED_INVALID_TYPE_RELU_COMBINATION = 4002, 
   // MMALIB_CNN_pixelShuffle_row
   MMALIB_ERR_PIXELSHUFFLE_ROW_INVALID_INCHOFFSET_CIRCULAR = 5000, 
   MMALIB_ERR_PIXELSHUFFLE_ROW_UNSUPPORTED_STRIDE  = 5001, 
   MMALIB_ERR_PIXELSHUFFLE_ROW_UNSUPPORTED_TYPE_COMBINATION = 5002, 
   MMALIB_ERR_PIXELSHUFFLE_ROW_INVALID_PTR_STRIDE = 5003, 
   MMALIB_ERR_PIXELSHUFFLE_ROW_INVALID_SUBMCHANNELS_STRIDE = 5004,  
   MMALIB_ERR_PIXELSHUFFLE_ROW_INVALID_SUBMCHANNELS = 5005,  
   MMALIB_ERR_PIXELSHUFFLE_ROW_INVALID_BUFFER_DIMENSION = 5006,  
   MMALIB_ERR_PIXELSHUFFLE_ROW_INVALID_ROWS_STRIDE = 5007, 
   MMALIB_ERR_PIXELSHUFFLE_ROW_INVALID_INITARGS = 5008, 
   MMALIB_ERR_PIXELSHUFFLE_ROW_INVALID_VALIDCOLSIN = 5009,  
   MMALIB_ERR_PIXELSHUFFLE_ROW_INVALID_UPSCALE_FACTOR = 5010,  
   // MMALIB_LINALG_matrixMatrixMultiply
   MMALIB_ERR_MATRIX_MATRIX_MULTIPLY_UNSUPPORTED_INPUT_TYPE  = 10000, 
   MMALIB_ERR_MATRIX_MATRIX_MULTIPLY_UNSUPPORTED_OUTPUT_TYPE = 10001, 
   MMALIB_ERR_MATRIX_MATRIX_MULTIPLY_UNSUPPORTED_TYPE_COMBINATION = 10002,  
   // MMALIB_LINALG_matrixMatrixMultiplyAccumulate
   MMALIB_ERR_MATRIX_MATRIX_MULTIPLY_ACCUMULATE_UNSUPPORTED_INPUT_TYPE  = 11000, 
   MMALIB_ERR_MATRIX_MATRIX_MULTIPLY_ACCUMULATE_UNSUPPORTED_OUTPUT_TYPE = 11001, 
   MMALIB_ERR_MATRIX_MATRIX_MULTIPLY_ACCUMULATE_UNSUPPORTED_TYPE_COMBINATION = 11002,  
   // MMALIB_LINALG_matrixTranspose
   MMALIB_ERR_MATRIX_TRANSPOSE_UNSUPPORTED_INPUT_TYPE  = 12000, 
   MMALIB_ERR_MATRIX_TRANSPOSE_UNSUPPORTED_OUTPUT_TYPE = 12001, 
   MMALIB_ERR_MATRIX_TRANSPOSE_UNSUPPORTED_TYPE_COMBINATION = 12002,  
   // MMALIB_LINALG_pointwiseMatrixMatrixMultiply
   MMALIB_ERR_POINTWISE_MATRIX_MATRIX_MULTIPLY_UNSUPPORTED_INPUT_TYPE  = 13000, 
   MMALIB_ERR_POINTWISE_MATRIX_MATRIX_MULTIPLY_UNSUPPORTED_OUTPUT_TYPE = 13001, 
   MMALIB_ERR_POINTWISE_MATRIX_MATRIX_MULTIPLY_UNSUPPORTED_TYPE_COMBINATION = 13002,  
} MMALIB_STATUS_NAME;

typedef MMALIB_STATUS_NAME MMALIB_STATUS; 

typedef void *MMALIB_kernelHandle; 

typedef enum {
  MMALIB_FUNCTION_NATC = 0,  
  MMALIB_FUNCTION_OPTIMIZED, 
  MMALIB_FUNCTION_MAX = 128
} MMALIB_FUNCTION_STYLE;

typedef enum {
  MMALIB_LINEAR = 0,    
  MMALIB_SE_CIRCULAR,   
  MMALIB_BUF_CIRCULAR   
} MMALIB_buffer_mode_e; // formerly eMMABufferMode;

/*******************************************************************************
 *
 * DEFINES
 *
 ******************************************************************************/

#define MMALIB_PARAM_SIZE 128 
#define MMALIB_BYTE_WIDTH 64  

/*******************************************************************************
 *
 * Macros
 *
 ******************************************************************************/

#define MMALIB_ALIGN_SHIFT_64BYTES                                             \
  6 
#define MMALIB_ALIGN_SHIFT_128BYTES                                            \
  7 
#define MMALIB_ALIGN_SHIFT_256BYTES                                            \
  8 

#define MMALIB_ALIGN_64BYTES                                                   \
  (1 << MMALIB_ALIGN_SHIFT_64BYTES) 
#define MMALIB_ALIGN_128BYTES                                                  \
  (1 << MMALIB_ALIGN_SHIFT_128BYTES) 
#define MMALIB_ALIGN_256BYTES                                                  \
  (1 << MMALIB_ALIGN_SHIFT_256BYTES) 

#define MMALIB_L2DATA_ALIGN_SHIFT                                              \
  MMALIB_ALIGN_SHIFT_64BYTES 


#define MMALIB_L2DATA_ALIGNMENT (((uint32_t)1) << ((uint32_t)MMALIB_L2DATA_ALIGN_SHIFT))

/* ---------------------------------------------------------------- */
/*  MISRAC Rule 4.9(DEFINE.FUNC) Deviation: The advisory is not     */
/*  being addressed                                                 */
/* ---------------------------------------------------------------- */
#define MMALIB_CALC_STRIDE(BYTES, ALIGN_SHIFT)                                 \
  (((((BYTES)-1) >> (ALIGN_SHIFT)) + 1) << (ALIGN_SHIFT))

#define MMALIB_MMA_SIZE_8_BIT_SHIFT                                            \
  6 
#define MMALIB_MMA_SIZE_16_BIT_SHIFT                                           \
  5 
#define MMALIB_MMA_SIZE_32_BIT_SHIFT                                           \
  4 


//#define MMALIB_MMA_SIZE_1_BYTE    1
#define MMALIB_MMA_SIZE_8_BIT                                              \
  ((uint32_t)(((uint32_t)1)                                                     \
             << MMALIB_MMA_SIZE_8_BIT_SHIFT)) 
#define MMALIB_MMA_SIZE_16_BIT                                                 \
  ((uint32_t)(((uint32_t)1)                                                     \
             << MMALIB_MMA_SIZE_16_BIT_SHIFT)) 
#define MMALIB_MMA_SIZE_32_BIT                                                 \
  ((int32_t)(((uint32_t)1)                                                     \
             << MMALIB_MMA_SIZE_32_BIT_SHIFT)) 


/******************************************************************************
 *
 *  Do not document these in the User Guide
 ******************************************************************************/

/* @{ */


/* ---------------------------------------------------------------- */
/*  MISRAC Rule 4.9(DEFINE.FUNC) Deviation: The advisory is not     */
/*  being addressed                                                 */
/* ---------------------------------------------------------------- */
// remove asm comments for Loki testing as they may add cycles
   #if defined(_HOST_BUILD)
      #define MMALIB_asm(string) ;
   #else
      #define MMALIB_asm(string); asm(string);
   #endif  // _HOST_BUILD

/* ---------------------------------------------------------------- */
/*  MISRAC Rule 4.9(DEFINE.FUNC) Deviation: The advisory is not     */
/*  being addressed  so as not to lose portability across different */
/*  platforms.                                                      */
/* ---------------------------------------------------------------- */
// cl7x unroll attributes not recognized by gcc/gpp compiler and generate
// warnings. Remove them with macro
#if defined(_HOST_BUILD)
#define str(x) #x
#define xstr(x) str(x)
#ifdef WIN32
#define __attribute__()
#define MMALIB_UNROLL(count)
#else
#define MMALIB_UNROLL(count) _Pragma(str(UNROLL(count)))
#endif
#else
#define MMALIB_UNROLL(COUNT) [[TI::unroll(COUNT)]]
#endif

#if defined(_HOST_BUILD)
#ifdef WIN32
#define __attribute__()
#define MMALIB_MUST_ITERATE(initial, max, multiple)
#else
#define MMALIB_MUST_ITERATE(initial, max, multiple) _Pragma(str(MUST_ITERATE(initial, max, multiple)))
#endif
#else
#define MMALIB_MUST_ITERATE(INTIAL, MAX, MULTIPLE)  [[TI::must_iterate(INTIAL, MAX, MULTIPLE)]]
#endif

#ifndef MMALIB_NUMBER_RANDOM_DIM_TESTS
#define MMALIB_NUMBER_RANDOM_DIM_TESTS 25
#endif

#define MMALIB_PERFORMANCE_TEST_PATTERN RANDOM_SIGNED

#define MMALIB_TEST_OUTPUT_HEAP 0
#if defined(_HOST_BUILD)
   // Valgrind works better when output is in the heap (it can't track statically allocated memory), so
   // in host emulation mode, place test outputs in the heap rather than statically allocated MSMC
   #define MMALIB_TEST_OUTPUT_MSMC MMALIB_TEST_OUTPUT_HEAP
#else
   #define MMALIB_TEST_OUTPUT_MSMC 1
#endif

#define STRIDE_OPT_4CYCLE 1

/*******************************************************************************
 *
 * MACROS
 *
 ******************************************************************************/

/* ---------------------------------------------------------------- */
/*  MISRAC Rule 4.9(DEFINE.FUNC) Deviation: The following           */
/*  function-like macros are intended to be used across different   */
/*  data types.                                                     */
/* ---------------------------------------------------------------- */
#define MMALIB_min(x, y)                                                       \
  (((x) < (y)) ? (x) : (y)) 
#define MMALIB_max(x, y)                                                       \
  (((x) < (y)) ? (y) : (x)) 
#define MMALIB_ceilingDiv(x, y)                                                \
  (((x) + (y)-1) /                                                             \
   (y)) 
/******************************************************************************
 *
 * COMMON MMA CONIFGURATIONS
 *
 ******************************************************************************/

   extern const uchar64 MMALIB_zeroVect_uchar64;
   extern const ushort32 MMALIB_zeroVect_ushort32;
   extern const uchar64 MMALIB_vperm_data_0_63;

   extern const MMALIB_MMA_CONFIG_REG configRegisterStruct_i32s_i32s_o32s;

   extern const MMALIB_MMA_CONFIG_REG configRegisterStruct_i16s_i16s_o16s;
   extern const MMALIB_MMA_CONFIG_REG configRegisterStruct_i16s_i16s_o16u;
   extern const MMALIB_MMA_CONFIG_REG configRegisterStruct_i16u_i16s_o16s;
   extern const MMALIB_MMA_CONFIG_REG configRegisterStruct_i16u_i16s_o16u;

   extern const MMALIB_MMA_CONFIG_REG configRegisterStruct_i8s_i8s_o8s;
   extern const MMALIB_MMA_CONFIG_REG configRegisterStruct_i8s_i8s_o8u;
   extern const MMALIB_MMA_CONFIG_REG configRegisterStruct_i8u_i8s_o8s;
   extern const MMALIB_MMA_CONFIG_REG configRegisterStruct_i8u_i8s_o8u;

   extern const __HWA_OFFSET_REG offsetRegStruct_zeros;
   extern const __HWA_OFFSET_REG offsetRegStruct_diagonal_32bit;
   extern const __HWA_OFFSET_REG offsetRegStruct_diagonal_16bit;
   extern const __HWA_OFFSET_REG offsetRegStruct_diagonal_8bit;


#ifdef __cplusplus
}
#endif /* __cplusplus */
#endif /* COMMON_MMALIB_TYPES_H_ */

/* ======================================================================== */
/*  End of file:  MMALIB_types.h                                             */
/* ======================================================================== */