Display TellTale CRCs#

Telltales are warnings or important notices to drivers of cars which are shown on one of the screens in front of the driver in the form of some image, possibly on top of other images. Examples could be a warning about lane changes or proximity alerts.

The NvDisplay hardware allows for mechanisms to obtain regional CRCs of regions containing telltale images to make sure that these are displayed correctly and to allow the system to take corrective action if the CRC does not match an expected CRC.

Static Configuration#

A telltale resource must be linked with a window to allow the window to use that resource to generate CRCs. The number of telltale resources that a window can use is configurable.

These can be configured in the display configuration DTSI along with other per window configuration. For more information on nvdisplay device tree configuration, see the SDK documentation.

display@8808c00000 {

    guests {
        gos0 {
                window-0 {
                    window-id = 0; //existing
                    hw-head-id = 0; //existing
                    crc-resources {
                        num-telltales = 5; // Number of telltale regions allowed.
                    };
                };
            };
        };
    };
};

Getting Max ROIS That Can Be Registered#

Get this information from ioctl DRM_NVIDIA_GET_ROI_CAPABILITIES:

/**
* @brief Parameters for getting ROI capabilities
*
* This structure is used with the DRM_NVIDIA_GET_ROI_CAPABILITIES ioctl to
* get ROI capabilities.
*
* @param[out] max_rois Maximum number of ROIs that can be registered
*/

struct drm_nvidia_get_roi_capabilities_params {
    uint32_t max_registered_rois;     /* OUT Maximum number of ROIs that can be registered */
    uint32_t reserved[7];
};

Region Registration and Unregistration#

In NVDisplay HW, the ROIs are programmed into a Region RAM and then referred to by their region handles when configuring a window to enable the CRC. The region RAM entries are treated as separate resources and must be registered and unregistered outside of the regular commit cycle.

An ROI can be registered with the ioctl DRM_NVIDIA_REGISTER_ROI. The following parameters are specified:

/**
* @brief Parameters for getting ROI capabilities
*
* This structure is used with the DRM_NVIDIA_GET_ROI_CAPABILITIES ioctl to
* get ROI capabilities.
*
* @param[out] max_rois Maximum number of ROIs that can be registered
*/

struct drm_nvidia_register_roi_params {
    struct drm_rect;   /* IN */
    int32_t region_handle; /* OUT*/
};

The region handle is referenced in subsequent plane operations to enable the CRC.

An ROI can be unregistered with the ioctl DRM_NVIDIA_UNREGISTER_ROI. The following parameters are specified:

/**
* @brief Parameters for getting ROI capabilities
*
* This structure is used with the DRM_NVIDIA_GET_ROI_CAPABILITIES ioctl to
* get ROI capabilities.
*
* @param[out] max_rois Maximum number of ROIs that can be registered
*/

struct drm_nvidia_unregister_roi_params {
    int32_t region_handle; /* IN*/
};

There are some constraints that must be kept in mind with region handles:

  • A region handle that is actively in use (configured in the CRC enablement property) cannot be unregistered.

  • Only a handle that was previously registered by this VM can be unregistered.

  • While overlapping regions can be registered via this API, they must not be used on the same head at the same time.

Enabling CRC for Region on a Plane#

  • Check the number of telltale CRCs per plane that are allowed by reading the plane property NV_DRM_NUM_PLANE_TELLTALE_CRCS.

  • Set the blob property NV_DRM_PLANE_TELLTALES on the plane before the atomic commit. The struct drm_nvidia_plane_telltales has the contents of the blob property.

  • The golden_crc field can be set to enable safety interrupts for mismatched CRC. For more details, see the HW documentation.

  • If the CRC collection for this region should be stopped, this property should be removed from the plane properties.

struct drm_nvidia_telltale_per_plane_config {
    int32_t region_handle;   /* IN */
    uint64_t golden_crc;     /* IN  0 if not configured*/
};

// This is the maximum size of the drm_nvidia_plane_telltales struct - only the number of CRCs read from
// NV_DRM_NUM_PLANE_TELLTALE_CRCS should be configured
#define NV_DRM_MAX_TELLTALES_PER_PLANE 32

// This will be installed as a new blob property
// "NV_DRM_PLANE_TELLTALES"
struct drm_nvidia_plane_telltales {
    struct drm_nvidia_telltale_per_plane_config telltale_configs[NV_DRM_MAX_TELLTALES_PER_PLANE];
};

  • DRM_NVIDIA_GET_CRTC_ROI_CRCS to read CRCs given a CRTC ID.

  • The ioctl responds with the information in drm_nvidia_read_crc_params.

# define NV_DRM_MAX_ROIS_PER_CRTC 32
struct drm_nvidia_roi_crc {
    int32_t region_handle; /* OUT */
    uint64_t crc;          /* OUT */
    uint64_t reserved[4];
};

struct drm_nvidia_read_crc_params {
int32_t crtc_id;      /* IN */
int32_t num_collected_crcs; /* OUT */
int32_t reserved[4];
    struct drm_nvidia_roi_crc roi_crcs[NV_DRM_MAX_ROIS_PER_CRTC]; /*OUT*/
};