OpenWFD Extensions

Contains extensions to allow users to create WFDSource objects from NvSciBuf objects.

Nvidia's OpenWFD driver libtegrawfd.so supports the following extensions:

WFD_NVX_create_source_from_nvscibuf

This extension allows users to create WFDSource objects out of NvSciBufObj buffer objects.

Two APIs are exposed to users as part of this extension. These are detailed below:

wfdNvSciBufSetDisplayAttributesNVX

API prototype:

WFDErrorCode wfdNvSciBufSetDisplayAttributesNVX(NvSciBufAttrList *attrList)

Parameters:

• NvSciBufAttrList *attrList - A valid pointer to a NvSciBufAttrList object

Return values:

• WFD_ERROR_NOT_SUPPORTED - The engine ID created for the display engine is not supported
• WFD_ERROR_OUT_OF_MEMORY - Insufficient memory is available to the OpenWFD driver for filling attrList
• WFD_ERROR_ILLEGAL_ARGUMENT - attrList is not a valid NvSciBufAttrList

Description:

Before allocation of NvSciBufObj, the list of engines that require access to the NvSciBufObj needs to be specified by clients of NvSciBuf.

For NvSciBufObj that are to be accessed by the display hardware, relevant display engine flags need to be added in NvSciBufAttrList along with any other engine's flags before reconciliation of the attribute lists.

This interface updates the input NvSciBufAttrList with values equivalent to the following public attribute key-values: NvSciBufGeneralAttrKey_PeerHwEngineArray set to the following NvSciBufPeerHwEngine values.

• NvSciBufHwEngName is set to NvSciBufHwEngName_Display.
• NvSciBufPlatformName is not filled by wfdNvSciBufSetDisplayAttributesNVX() and is expected to be set by the caller to the appropriate platform name as described in nvscibuf.h.

wfdNvSciBufSetDisplayAttributesNVX fills attrList with the required display engine attributes and OpenWFD clients that require NvSciBufObj buffers to be consumed by the display should call wfdNvSciBufSetDisplayAttributesNVX before allocating the NvSciBufObj.

wfdCreateSourceFromNvSciBufNVX

API prototype:

WFDSource wfdCreateSourceFromNvSciBufNVX(WFDDevice device, WFDPipeline pipeline, NvSciBufObj &bufferObject)

Parameters :

• WFDDevice device - A valid WFDDevice handle created using wfdCreateDevice
• WFDPipeline pipeline - A valid WFDPipeline handle created using wfdCreatePipeline
• NvSciBufObj &bufferObject - A valid reference to a NvSciBufObj

Return values:

• A valid WFDSource handle - On success
• WFD_INVALID_HANDLE - On failure. Use wfdGetError to query the error code.

Error codes:

• WFD_ERROR_ILLEGAL_ARGUMENT - bufferObject is not a valid NvSciBuf object or bufferObject does not contain display flags as part of its engine array list
• WFD_ERROR_NOT_SUPPORTED - The attributes of bufferObject are not supported by the extension.
• WFD_ERROR_BAD_HANDLE - pipeline is not a valid WFDPipeline

A limited set of values are supported by this extension for only the following NvSciBuf attribute keys:

Key	Value
NvSciBufGeneralAttrKey_Types	NvSciBufType_Image
NvSciBufImageAttrKey_PlaneCount	1, 2
NvSciBufImageAttrKey_PlaneColorFormat	NvSciColor_A8R8G8B8, NvSciColor_A8B8G8R8, NvSciColor_Y8, NvSciColor_U8_V8, NvSciColor_U8Y8V8Y8, NvSciColor_Y8U8Y8V8, NvSciColor_V8U8
NvSciBufImageAttrKey_PlaneColorStd	NvSciColorStd_SRGB, NvSciColorStd_REC709_SR, NvSciColorStd_REC709_ER

If the value of key NvSciBufImageAttrKey_PlaneColorStd is other than the supported values as listed in the preceding table, the following conditions apply:

• The OpenWFD defaults the color space to none.
• The display driver does not apply any de-gamma to the input color surface and will assume that the input surface is linearly encoded.

The output colorspace is always set to sRGB.

In previous releases, the display driver did not apply any de-gamma regardless of what NvSciColorStd value was specified. Starting in 6.0.7.0, the display driver honors the NvSciColorStd values mentioned in the preceding table.

Description:

wfdCreateSourceFromNvSciBufNVX creates WFDSource handles out of NvSciBufObjs.

bufferObject should be allocated with reconciliation including a NvSciBufAttrList filled via wfdNvSciBufSetDisplayAttributesNVX.

WFD_NVX_commit_non_blocking

This extension allows users to schedule flips to the display that do not block until the display is done with its work.

The default behaviour of the core OpenWFD API wfdDeviceCommit is to block until the display is done with the flip.

This extensions adds a new WFDPipeline attribute WFD_PIPELINE_COMMIT_NON_BLOCKING_NVX which can be used to alter the default behaviour of wfdDeviceCommit.

By default, WFD_PIPELINE_COMMIT_NON_BLOCKING_NVX is set to WFD_FALSE making calls to wfdDeviceCommit on the WFDPipeline blocking.

wfdSetPipelineAttribi function can be used to set the value of a WFDPipeline object's WFD_PIPELINE_COMMIT_NON_BLOCKING_NVX attribute to WFD_TRUE, which makes calls to wfdDeviceCommit on the WFDPipeline non blocking.

When calling wfdDeviceCommit with WFDCommitType set to either WFD_COMMIT_ENTIRE_PORT or WFD_COMMIT_ENTIRE_DEVICE, all WFDPipeline objects attached to the WFDPort and WFDDevice handles need to have their WFD_PIPELINE_COMMIT_NON_BLOCKING_NVX attribute set to WFD_TRUE for non blocking commits to occur.

Synchronization of calls to wfdDeviceCommit in this scenario must be handled explicitly by the user with the help of WFD_NVX_nvscisync.

Additions to the list of WFDPipelineConfigAttrib enums:

• WFD_PIPELINE_COMMIT_NON_BLOCKING_NVX

WFD_NVX_nvscisync

This extension allows you to explicitly handle synchronization of work submission to the display by using NvSciSyncFence.

You can use the WFDPipeline attribute WFD_PIPELINE_POSTFENCE_SCANOUT_BEGIN_NVX to alter the default behavior of the post-flip fence returned by wfdDeviceCommitWithNvSciSyncFenceNVX.

By default, WFD_PIPELINE_POSTFENCE_SCANOUT_BEGIN_NVX is set to WFD_TRUE making the post-flip fence returned from wfdDeviceCommitWithNvSciSyncFenceNVX to be signaled when the display hardware starts scanning out the current buffer.

Use the wfdSetPipelineAttribi function to modify the value of WFD_PIPELINE_POSTFENCE_SCANOUT_BEGIN_NVX. When this is set to WFD_FALSE, the post-flip fence returned by wfdDeviceCommitWithNvSciSyncFenceNVX will be signaled at the end of scanout of the buffer. This can happen only when a wfdDeviceCommit on a new WFDSource handle is scheduled so that the display hardware can stop scanning the WFDSource used for the previous wfdDeviceCommit. The wfdSetPipelineAttribi function can be called to modify the value of WFD_PIPELINE_POSTFENCE_SCANOUT_BEGIN_NVX only once per WFDPipeline for the duration of the application lifecycle.

Use the wfdGetPipelineAttribi function to query the value of WFD_PIPELINE_POSTFENCE_SCANOUT_BEGIN_NVX.

Note

When scheduling commits of type WFD_COMMIT_ENTIRE_PORT or type WFD_COMMIT_ENTIRE_DEVICE, the values of WFD_PIPELINE_POSTFENCE_SCANOUT_BEGIN_NVX should be the same for all WFDPipeline handles included in the commit. When there are mismatches in the values of the WFD_PIPELINE_POSTFENCE_SCANOUT_BEGIN_NVX attribute, the value of the highest Z-ordered WFDPipeline for the WFDPort is considered. Application should not rely on this behavior, and instead ensure to explicitly set the value of WFD_PIPELINE_POSTFENCE_SCANOUT_BEGIN_NVX for all WFDPipeline handles included in the commit.

Five APIs are exposed to users as part of this extension and are described below:

wfdNvSciSyncSetWaiterAttributesNVX

API prototype:

WFDErrorCode wfdNvSciSyncSetWaiterAttributesNVX(NvSciSyncAttrList *attrList)

Parameters:

• *attrList: A valid pointer to a NvSciSyncAttrList object.

Return values:

• WFD_ERROR_ILLEGAL_ARGUMENT: attrList is not a valid NvSciSyncAttrList
• WFD_ERROR_NONE: On success

Description:

The OpenWFD driver only supports syncpoint synchronization primitives and any NvSciSyncFences passed to OpenWFD must be generated from NvSciSyncObjs that have been created with reconciliation of attribute lists that specify the syncpoint type support by the OpenWFD driver.

wfdNvSciSyncSetWaiterAttributesNVX allows OpenWFD clients intending to pass waiter NvSciSyncFences to fill NvSciSyncAttrLists with the supported syncpoint primitive type for reconciliation. This API updates the input NvSciSyncAttrList with values equivalent to the following public attributes of key-value pairs:

• NvSciSyncAttrKey_RequiredPerm set to NvSciSyncAccessPerm_WaitOnly
• NvSciSyncAttrKey_PrimitiveInfo set to NvSciSyncAttrValPrimitiveType_Syncpoint

wfdNvSciSyncSetSignalerAttributesNVX

API prototype:

WFDErrorCode wfdNvSciSyncSetSignalerAttributesNVX(NvSciSyncAttrList *attrList)

Parameters

• *attrList: A valid handle to a NvSciSyncAttrList object.

Return values:

• WFD_ERROR_ILLEGAL_ARGUMENT: attrList is not a valid NvSciSyncAttrList
• WFD_ERROR_NONE: On success

Description:

Similar to wfdNvSciSyncSetWaiterAttributesNVX, wfdNvSciSyncSetSignalerAttributesNVX allows OpenWFD clients intending to pass NvSciSyncFences that are signaled by the display hardware to fill NvSciSyncAttrLists with the supported syncpoint primitive type for reconciliation. This API updates the input NvSciSyncAttrList with values equivalent to the following public attributes of key-value pairs:

• NvSciSyncAttrKey_RequiredPerm set to NvSciSyncAccessPerm_SignalOnly
• NvSciSyncAttrKey_PrimitiveInfo set to NvSciSyncAttrValPrimitiveType_Syncpoint

wfdBindNvSciSyncFenceToSourceNVX

API prototype:

WFDErrorCode wfdBindNvSciSyncFenceToSourceNVX(WFDDevice device, WFDSource source, const NvSciSyncFence *const fence)

Parameters:

• WFDDevice device: A valid WFDDevice handle created using wfdCreateDevice
• WFDSource source: A valid WFDSource handle created using wfdCreateSourceFromNvSciBufNVX
• const NvSciSyncFence *const fence: A valid pointer to a NvSciSyncFence object.

Return values:

• WFD_ERROR_ILLEGAL_ARGUMENT - fence is either nullptr or an invalid NvSciSyncFence object or source is not a valid WFDSource handle
• WFD_ERROR_BAD_DEVICE - device is an invalid WFDDevice handle
• WFD_ERROR_BAD_HANDLE - source is not bound to a valid WFDPipeline
• WFD_ERROR_NONE - Success

Description:

wfdBindNvSciSyncFenceToSourceNVX allows users to associate a NvSciSyncFence object with a WFDSource handle.

Any work submissions done to the display with the WFDSource handle will block on the NvSciSyncFence bound to the WFDSource.

The user is responsible to signal the NvSciSyncFence and allow the display to consume the buffer.

wfdRegisterPostFlipNvSciSyncObjNVX

API prototype:

WFDErrorCode wfdRegisterPostFlipNvSciSyncObjNVX(WFDDevice device, NvSciSyncObj* obj)

Parameters:

• WFDDevice device: A valid WFDDevice handle created using wfdCreateDevice
• NvSciSyncObj *obj: A valid pointer to a NvSciSyncObj object or nullptr (see below)

Return values:

• WFD_ERROR_ILLEGAL_ARGUMENT: A NvSciSyncObj is already registered with device
• WFD_ERROR_BAD_ATTRIBUTE: obj is not a valid NvSciSyncObj
• WFD_ERROR_BAD_DEVICE: device is not a valid WFDDevice handle
• WFD_ERROR_NOT_SUPPORTED: obj encapsulates a primitive type not supported by the OpenWFD driver
• WFD_ERROR_NONE: Success

Description:

wfdRegisterPostFlipNvSciSyncObjNVX allows WFD clients to register a NvSciSyncObj with the OpenWFD driver. The OpenWFD driver uses this NvSciSyncObj to generate NvSciSyncFence objects that are passed to the WFD client and are signaled when the display hardware is done consuming the buffer.

The OpenWFD driver allows only one NvSciSyncObj to be registered at any time. nullptr can be passed for obj to unregister any existing NvSciSyncObj objects. This allows the WFD client to register a different NvSciSyncObj handle with the OpenWFD driver.

The NvSciSyncFence generated with the use of the registered NvSciSyncObj handle is returned to the client via wfdDeviceCommitWithNvSciSyncFeenceNVX.

obj should be created with a NvSciSyncAttrList filled by wfdNvSciSyncSetSignalerAttributesNVX.

wfdDeviceCommitWithNvSciSyncFenceNVX

API prototype:

void wfdDeviceCommitWithNvSciSyncFenceNVX(WFDDevice device, WFDCommitType type, WFDHandle handle, NvSciSyncFence *const fence)

Parameters:

• WFDDevice device: A valid WFDDevice handle created using wfdCreateDevice
• WFDCommitType type: A valid WFDCommitType value. Refer to the OpenWFD Interface Specification for the list of accepted values.
• WFDHandle handle: A valid handle to a WFDPort or a WFDPipeline. Refer to the OpenWFD Interface Specification for the list of accepted values.
• NvSciSyncFence *const fence: A pointer that can store a NvSciSyncFence object.

Return values: None

Error codes:

• WFD_ERROR_ILLEGAL_ARGUMENT: type is not a valid WFDCommitType.
• WFD_ERROR_NOT_SUPPORTED: If any hardware resource limitations exist.
• WFD_ERROR_BUSY: A call to wfdDeviceCommitWithNvSciSyncFenceNVX is currently executing
• WFD_ERROR_BAD_HANDLE: handle does not match the requirements of type as specified in the documentation of wfdDeviceCommit at OpenWFD Interface Specification.
• WFD_ERROR_INCONSISTENCY: If any configuration conflicts exist within the device or corresponding ports or corresponding pipelines.
• WFD_ERROR_BAD_ATTRIBUTE: fence is not a valid NvSciSyncFence object.

Description:

The working of this API is similar to the OpenWFD Core API wfdDeviceCommit with the addition of a NvSciSyncFence parameter.

When a NvSciSyncObj is registered with the OpenWFD driver, wfdDeviceCommitWithNvSciSyncFenceNVX can be used by the client to acquire an NvSciSyncFence object passed via fence. This is the post-flip fence of display and the signaling semantics of it depend on the value of WFD_PIPELINE_POSTFENCE_SCANOUT_BEGIN_NVX for the WFDpipeline included in the commit call. After the fence has been signaled, the fence must be cleared by the client with a call to NvSciSyncFenceClear().

When this API is called with no registered NvSciSyncObj, fence returns a nullptr.

WFD_NVX_port_mode_timings

This extension allows you to query the horizontal total and vertical total values of the display by using the following WFDPortMode attributes.

Additions to the list of WFDPortModeAttrib enums:

• WFD_PORT_MODE_H_TOTAL_NVX
• WFD_PORT_MODE_V_TOTAL_NVX

These attributes are read-only and can be queried via wfdGetPortModeAttribi only.