Video and Vision Processing Suite Intel® FPGA IP User Guide

ID 683329
Date 4/04/2022
Public

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

Document Table of Contents

19.5. 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 295.   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_set_roi_en Enable or disable the region of interest mode
intel_vvp_tmo_set_roi_swap Enable or disable swap region in region of interest mode
intel_vvp_tmo_set_roi_horizontal_x0x1 Set horizontal starting and ending positions of the region of interest, implicitly enables region of interest mode
intel_vvp_tmo_set_roi_vertical_y0y1 Set vertical starting and ending positions of the region of interest, implicitly enables region of interest mode
intel_vvp_tmo_get_roi_en Return current value of the region of interest enable bit
intel_vvp_tmo_get_roi_swap Return current value of the region of interest swap bit
intel_vvp_tmo_get_roi_horizontal_x0 Return current value of the horizontal starting position of the region of interest
intel_vvp_tmo_get_roi_horizontal_x1 Return current value of the horizontal ending position of the region of interest
intel_vvp_tmo_get_roi_vertical_y0 Return current value of the vertical starting position of the region of interest
intel_vvp_tmo_get_roi_vertical_y1 Return current value of the vertical ending position of the region of interest
intel_vvp_tmo_get_pip Return current configuration value of the number of pixels-in-parallel
intel_vvp_tmo_get_resolution_width Return width of the current video resolution in number of pixels
intel_vvp_tmo_get_resolution_height Return height of the current video resolution in number of lines
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_set_roi_en

void intel_vvp_tmo_set_roi_en(intel_vvp_tmo_instance_t* instance, uint32_t roi_en)
Description
Enable or disable the region of interest mode
Arguments

instance – pointer to the TMO software driver instance

region of interest enable – 1 – enable region of interest mode, 0 – disable region of interest mode

Return Value
void

intel_vvp_tmo_set_roi_swap

void intel_vvp_tmo_set_roi_swap(intel_vvp_tmo_instance_t* instance, uint32_t roi_swap)
Description
Enable or disable swap region in region of interest mode
Arguments

instance – pointer to the TMO software driver instance

region of interest swap – 1 – swap the region of interest, 0 – do not swap the region of interest

Return Value
void

intel_vvp_tmo_set_roi_horizontal_x0x1

void intel_vvp_tmo_set_roi_horizontal_x0x1(intel_vvp_tmo_instance_t* instance, const uint32_t
          pos_x0, const uint32_t pos_x1)
Description
Set horizontal starting and ending positions of the region of interest, implicitly enables region of interest mode
Arguments

instance – pointer to the TMO software driver instance

horizontal region of interest starting position – starting pixel position of the region of interest in the width dimension, divided by pixels-in-parallel

horizontal region of interest ending position – ending pixel position of the region of interest in the width dimension, divided by pixels-in-parallel

Return Value
void

intel_vvp_tmo_set_roi_vertical_y0y1

void intel_vvp_tmo_set_roi_vertical_y0y1(intel_vvp_tmo_instance_t* instance, const uint32_t
          pos_y0, const uint32_t pos_y1)
Description
Set vertical starting and ending positions of the region of interest, implicitly enables region of interest mode
Arguments

instance – pointer to the TMO software driver instance

vertical region of interest starting position – starting line position of the region of interest in the height dimension

vertical region of interest ending position – ending line position of the region of interest in the height dimension

Return Value
void

intel_vvp_tmo_get_roi_en

uint32_t
intel_vvp_tmo_get_roi_en(intel_vvp_tmo_instance_t* instance)
Description
Return current value of the region of interest enable bit
Arguments
instance – pointer to the TMO software driver instance structure
Return Value
1 – region of interest mode is enabled; 0 – region of interest mode is disabled

intel_vvp_tmo_get_roi_swap

uint32_t
intel_vvp_tmo_get_roi_swap(intel_vvp_tmo_instance_t* instance)
Description
Return current value of the region of interest swap bit
Arguments
instance – pointer to the TMO software driver instance structure
Return Value
1 – region of interest is swapped; 0 – region of interest is not swapped

intel_vvp_tmo_get_roi_horizontal_x0

uint32_t
intel_vvp_tmo_get_roi_horizontal_x0(intel_vvp_tmo_instance_t*
instance)
Description
Return current value of the horizontal starting position of the region of interest
Arguments
instance – pointer to the TMO software driver instance structure
Return Value
Current value of the horizontal starting pixel position of the region of interest, divided by pixels-in-parallel

intel_vvp_tmo_get_roi_horizontal_x1

uint32_t
intel_vvp_tmo_get_roi_horizontal_x1(intel_vvp_tmo_instance_t*
instance)
Description
Return current value of the horizontal ending position of the region of interest
Arguments
instance – pointer to the TMO software driver instance structure
Return Value
Current value of the horizontal ending pixel position of the region of interest, divided by pixels-in-parallel

intel_vvp_tmo_get_roi_vertical_y0

uint32_t
intel_vvp_tmo_get_roi_vertical_y0(intel_vvp_tmo_instance_t*
instance)
Description
Return current value of the vertical starting position of the region of interest
Arguments
instance – pointer to the TMO software driver instance structure
Return Value
Current value of the vertical starting line position of the region of interest

intel_vvp_tmo_get_roi_vertical_y1

uint32_t
intel_vvp_tmo_get_roi_vertical_y1(intel_vvp_tmo_instance_t*
instance)
Description
Return current value of the vertical ending position of the region of interest
Arguments
instance – pointer to the TMO software driver instance structure
Return Value
Current value of the vertical ending line position of the region of interest

intel_vvp_tmo_get_pip

uint32_t
intel_vvp_tmo_get_pip(intel_vvp_tmo_instance_t*
instance)
Description
Return current configuration value of the number of pixels-in-parallel
Arguments
instance – pointer to the TMO software driver instance structure
Return Value
Configuration value of the number of pixels-in-parallel

intel_vvp_tmo_get_resolution_width

uint32_t
intel_vvp_tmo_get_resolution_width(intel_vvp_tmo_instance_t*
instance)
Description
Return width of the current video resolution in number of pixels
Arguments
instance – pointer to the TMO software driver instance structure
Return Value
Current value of the video resolution width in number of pixels

intel_vvp_tmo_get_resolution_height

uint32_t
intel_vvp_tmo_get_resolution_height(intel_vvp_tmo_instance_t*
instance)
Description
Return height of the current video resolution in number of lines
Arguments
instance – pointer to the TMO software driver instance structure
Return Value
Current value of the video resolution height in number of lines

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