Video and Vision Processing Suite Intel® FPGA IP User Guide

ID 683329
Date 9/30/2021
Public

A newer version of this document is available. Customers should click here to go to the newest version.

Document Table of Contents

TMO IP Software API

The IP includes a software driver that configures and controls all the IP parameters.

Software Driver Example

int main()
{
  int ret = -1;

  /* Initialize datapath Video Timing Generator instance
  /* This API function is not part of the TMO driver. */ 
  /* Hence, it is up to the user to implement it, to provide VIDEO_WIDTH, VIDEO_HEIGHT values */
  datapath_vtiming_config(VTIMING_TMO_BASE, 1);

  /* Initialize TMO IP instance*/
  intel_vvp_base_t base = INTEL_VVP_TMO_BASE;
  intel_vvp_tmo_instance_t intel_vvp_tmo_instance;

  /*Query TMO IP instance, to know whether is has been initialized correctly. */
  /* A value == '0' indicates TMO IP has been initialized correctly  */
  ret = intel_vvp_tmo_init_instance(&intel_vvp_tmo_instance, base);

  if (ret == 0)
  {
    /* TMO IP Bypass control */
    uint32_t bypass = 0;

    intel_vvp_tmo_set_bypass(&intel_vvp_tmo_instance, bypass);
    printf("Intel VVP TMO Bypass %s\n\n", bypass ? "ENABLED" : "DISABLED");

    /* Initialize TMO IP to specific video resolution */
    intel_vvp_tmo_set_resolution(&intel_vvp_tmo_instance, VIDEO_WIDTH, VIDEO_HEIGHT);

    /* Update TMO IP volume control values */
    intel_vvp_tmo_set_volume(&intel_vvp_tmo_instance, VOLUME_CTL_USER);
    intel_vvp_tmo_set_threshold(&intel_vvp_tmo_instance, INT_THR_USER);

    printf("TMO initialization done\n");
    fcntl(STDIN_FILENO, F_SETFL, O_NONBLOCK);

    while (1)
    {
      /* This function checks if TMO IP bypass mode and/or volume control values need to be updated */
      /* but it is not part of the TMO IP SW driver package. Hence, customers are expected */
      /* to implement their own function according to their specific needs */   
      process_user_input(&intel_vvp_tmo_instance);

      /* This part of the code is for debug purpose only */
      /* Two conditions are checked: */
            
      /* Condition #1: Missing data collection per tile */
      static const uint32_t num_rows = 4;
      static const uint32_t row_mask = ~(~0u << num_rows);

    





      /* Read TMO IP debug register to check for error conditions */
      uint32_t reg_val = intel_vvp_tmo_get_debug(&intel_vvp_tmo_instance;

      if (reg_val & row_mask)
      {
        Printf ("Timeout rows: ";

        for (uint32_t i = 0; i < num_rows; ++ i)
        {
          if (reg_val & (0x1 << i))
            printf("%"PRIu32" ", i);
        }

        printf("\n";
      }

      /* Condition #2: Missing entire video frame */
      if (reg_val & 0x100)
      {
        printf ("FSYNC toggle error\n";
      }

      /* Set TMO IP debug register to capture new error conditions */
      intel_vvp_tmo_set_debug(&intel_vvp_tmo_instance, reg_val);
    }
  }
  else
  {
    printf("Error initializing intel_vvp_tmo instance: %d\n", ret);
  }

  return ret;
}

The TMO IP software driver does not include the process_user_input(&intel_vvp_tmo_instance) function, as its implementation depends on your system requirements and specifications. You can query and update TMO strength volume values in various ways. For example, you can implement the process_user_input(&intel_vvp_tmo_instance) in this way:

void process_user_input(intel_vvp_tmo_instance* instance)
{
  int c = getchar();
  static const int32_t VOL_STEP = 5;
  static const int32_t TS_STEP = 1000;
  int vol_delta = 0;
  int ts_delta = 0;

  if(c != EOF)
  {
    switch(c)
    {
      case 'w':
      case 'W':
        vol_delta = VOL_STEP;
        break;
      case 's':
      case 'S':
        vol_delta = -VOL_STEP;
        break;
      case 'd':
      case 'D':
        ts_delta = TS_STEP;
        break;
      case 'a':
      case 'A':
        ts_delta = - TS_STEP;
        break;
      case 'b':
      case 'B':
      {
        uint32_t bypass = intel_vvp_tmo_get_bypass(instance);
        bypass ^= 0x1;
        intel_vvp_tmo_set_bypass(instance, bypass);
        printf("TMO Bypass %s\n\n", bypass ? "ENABLED" : "DISABLED");
      }
        break;
      default:
        break;
    }

    if(vol_delta || ts_delta)
    {
      int32_t vol = (int32_t)(intel_vvp_tmo_get_volume(instance));
      int32_t ts = (int32_t)(intel_vvp_tmo_get_threshold(instance));

      vol += vol_delta;
      ts += ts_delta;

      if(vol > 100)
      vol = 100;

      if(vol < 0)
      vol = 0;

      if(ts > 9000)
      ts = 9000;

      if(ts < 0)
      ts = 0;

      printf("VOL: %"PRIi32"\n", vol);
      printf("TS: %"PRIi32"\n", ts);

      intel_vvp_tmo_set_volume(instance, (uint32_t)(vol));
      intel_vvp_tmo_set_threshold(instance, (uint32_t)(ts));
    }
  }
}

All the API functions require a pointer to intel_vvp_tmo_instance_t structure as the first parameter. The structure represents an individual instance of TMO IP and defined as following:

typedef struct intel_vvp_tmo_instance {
intel_vvp_tmo_base_t base;
} intel_vvp_tmo_instance_t;

Where:

intel_vvp_tmo_base_t base is a platform specific access handler that the driver uses to access configuration and control registers of the IP. Default definition for a bare metal environment is 32-bit unsigned integer representing base address of the TMO IP on the external CPU bus.

The internal driver uses the following macros to access individual registers of the IP:

  • tmoss_read_reg(x) – read register
  • tmoss_write_reg(x,y) – write register

Where:

x is the byte offset of the register from the IP core base address

y is the 32-bit register value to write.

Default bare metal implementation of the IP register access provided in the file intel_vvp_tmo_io.h. Provide alternative implementations through separate header files included conditionally from intel_vvp_tmo_io.h.

Byte offsets of all TMO IP registers are defined in the file intel_vvp_tmo_regs.h.

Table 52.   Software driver API reference The software driver for TMO IP provides various API functions
Name Description
intel_vvp_tmo_init_instance Initialize TMO IP driver instance
intel_vvp_tmo_set_bypass Set TMO IP into bypass mode
intel_vvp_tmo_get_bypass Return current setting of the bypass mode
intel_vvp_tmo_set_resolution Set input video resolution for TMO IP
intel_vvp_tmo_set_volume Adjust fine-level TMO volume as a percentage, which allows more granularity when setting TMO strength value
intel_vvp_tmo_get_volume Return current level of TMO strength
intel_vvp_tmo_set_threshold Adjust coarse level TMO volume, which allows setting TMO strength value
intel_vvp_tmo_get_threshold Return current value of fine-level TMO volume adjustment
intel_vvp_tmo_get_debug Return current value of debug information register
intel_vvp_tmo_set_debug Clear individual bits in debug information register

intel_vvp_tmo_init_instance

int intel_vvp_tmo_init_instance(intel_vvp_tmo_instance_t* instance, intel_vvp_tmo_base_t base)
Description
Initialize TMO software driver instance
Arguments
instance – pointer to the TMO software driver instance structure
base – platform specific IP access handle. In a bare metal environment this is typically defined as 32-bit unsigned integer representing base address of the IP on the external CPU bus
Return Value
Zero on success, negative integer otherwise

intel_vvp_tmo_set_bypass

void intel_vvp_tmo_set_bypass(intel_vvp_tmo_instance_t* instance, uint32_t bypass)
Description
Enable/disable TMO bypass mode. With bypass mode the TMO IP does not process the incoming video stream and passes it as is.
Arguments
instance – pointer to the TMO software driver instance structure
bypass - 1 – enable bypass mode; 0 – disable bypass mode
Return Value
void

intel_vvp_tmo_get_bypass

uint32_t intel_vvp_tmo_get_bypass(intel_vvp_tmo_instance_t* instance)
Description
Get the current setting of the bypass mode
Arguments
instance – pointer to the TMO software driver instance structure
Return Value
1 – bypass mode is enabled; 0 – bypass mode is disabled

intel_vvp_tmo_set_resolution

void intel_vvp_tmo_set_resolution(intel_vvp_tmo_instance_t* instance, const uint32_t width, const uint32_t height)
Description
Set up TMO IP for the required video resolution
Arguments
instance – pointer to the TMO software driver instance structure
width - video width in pixels e.g. 1920
height - video height in lines e.g. 1080
Return Value
void

intel_vvp_tmo_set_volume

void intel_vvp_tmo_set_volume(intel_vvp_tmo_instance_t* instance, const uint32_t volume)
Description
Set desired tone enhancement strength
Arguments
instance – pointer to the TMO software driver instance structure
volume - tone enhancement strength in the range [0..100]
Return Value
void

intel_vvp_tmo_get_volume

uint32_t intel_vvp_tmo_get_volume(intel_vvp_tmo_instance_t* instance)
Description
Get currently configured tone enhancement strength
Arguments
instance – pointer to the TMO software driver instance structure
Return Value
Current tone enhancement strength in the range [0..100]

intel_vvp_tmo_set_threshold

void intel_vvp_tmo_set_threshold(intel_vvp_tmo_instance_t* instance, const uint32_t threshold)
Description
Set fine-level tone enhancement strength
Arguments
instance – pointer to the TMO software driver instance structure
threshold – fine level tone enhancement strength in the range [0..10000]
Return Value
void

intel_vvp_tmo_get_threshold

uint32_t intel_vvp_tmo_get_threshold(intel_vvp_tmo_instance_t* instance)
Description
Get currently configured fine-level tone enhancement strength
Arguments
instance – pointer to the TMO software driver instance structure
Return Value
Current fine level tone enhancement strength in the range [0..10000]

intel_vvp_tmo_get_debug

uint32_t intel_vvp_tmo_get_debug(intel_vvp_tmo_instance_t* instance)
Description
Get current value of the Debug information register Ext_Reg_0xA0
Arguments
instance – pointer to the TMO software driver instance structure
Return Value
Current value of Ext_Reg_0xA0 as 32-bit unsigned integer

intel_vvp_tmo_set_debug

void intel_vvp_tmo_set_debug(intel_vvp_tmo_instance_t* instance, uint32_t val)
Description
Clear individual bits of the Debug information register Ext_Reg_0xA0
Arguments
instance – pointer to the TMO software driver instance structure
val - bit mask of the bits within the debug register to clear
Return Value
void