Re: [PATCH i-g-t v4 18/46] lib/unigraf: Add TSI.h

["Luca Ceresoli" <luca.ceresoli@bootlin.com>]

On Mon Nov 10, 2025 at 2:39 PM CET, Louis Chauvet wrote:
> Unigraf does not provide header for the libTSI.so file, only dynamic
> library loading helpers for windows.
>
> In order to link against this library and use unigraf devices, add the
> function declaration used in the dynamic library loading wrappers.
>
> Signed-off-by: Louis Chauvet <louis.chauvet@bootlin.com>
> ---
>  lib/unigraf/TSI.h | 234 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 234 insertions(+)
>
> diff --git a/lib/unigraf/TSI.h b/lib/unigraf/TSI.h
> new file mode 100644
> index 000000000000..62daaab6300e
> --- /dev/null
> +++ b/lib/unigraf/TSI.h
> @@ -0,0 +1,234 @@
> +/* SPDX-License-Identifier: MIT */
> +
> +/*
> + * tsi.h - Header for libTSI.so
> + * Documentation here is taken from official documentation and developer observation.
> + */
> +
> +#ifndef TSI_H
> +#define TSI_H
> +
> +#define TSI_CURRENT_VERSION	12
> +#define MAX_EDID_SIZE		4096
> +
> +#define TSI_SUCCESS		0
> +
> +typedef unsigned int		TSI_VERSION_ID;
> +typedef unsigned int		TSI_SEARCH_OPTIONS;
> +typedef unsigned int		TSI_DEVICE_CAPS;
> +typedef unsigned int		TSI_CONFIG_ID;
> +typedef unsigned int		TSI_DEVICE_ID;
> +typedef unsigned int		TSI_INPUT_ID;
> +typedef int			TSI_RESULT;
> +typedef void			*TSI_HANDLE;
> +typedef int			TSI_FLAGS;
> +
> +/**
> + * TSI_Init() - Initialize the TSI library
> + * @ClientVersion: Indicates the version used to call the libTSI.so functions.
> + *
> + * Initialize libTSI for use and sets up internal state. It can be called
> + * multiple times, but TSI_Clean must be called the exact same number of time.
                                                                            times
> + *
> + * Returns:
> + * - In case of success: Reference count to the API (number of times to call TSI_Clean)
> + * - TSI_ERROR_NOT_COMPATIBLE if the requested client version is not supported
> + *   by the library
> + * - TSI_ERROR_COMPATIBILITY_MISMATCH if TSI_Init is called twice with
> + *   different client version
> + */
> +TSI_RESULT TSI_Init(TSI_VERSION_ID ClientVersion);
> +
> +/**
> + * TSI_Clean() - Cleans and closes the TSI library
> + *
> + * When TSI_Clean is called for the last time, cleanup the internal state. It
> + * should be called exactly the same number of time as TSI_Init
                                                  times

> + */
> +TSI_RESULT TSI_Clean(void);
> +
> +/**
> + * TSI_MISC_GetErrorDescription() - Get a human readable error message
> + * @ErrorCode: Error code for which you want the message
> + * @ErrorString: Pointer where to copy the message
> + * @StringMaxLen: Size of the allocated string @ErrorString
> + *
> + * The official documentation states: If the function succeeds, the
> + * return value is the number of characters required for the complete
> + * error description string.
> + * In reality, this function always returns 0 or error, so there is no way to

On error it returns 0...

> + * tell if the allocated memory was big enough
> + *
> + * Returns:
> + * - >= 0 on success, theorically the required string len to store the message
> + * - < 0 on failure

...or <0?

> + */
> +TSI_RESULT TSI_MISC_GetErrorDescription(TSI_RESULT ErrorCode,
> +					char *ErrorString,
> +					unsigned int StringMaxLen);
> +
> +/**
> + * TSIX_TS_GetConfigItem() - Read a configuration item from the UCD device
> + * @Device: Device handle to read config from. Can be NULL for certain configuration items.

For which items it can be NULL? I can guess some global config items, not
device-specific. Is it the case?

> + * @ConfigItemID: Identifier of the requested configuration item.
> + * @ConfigItemData: Pointer to store the read value.
> + * @ItemMaxSize: Size of the allocated memory for @ConfigItemData.
> + *
> + * Returns: The size of the raw data. If the return value is larger than ItemMaxSize, no data
> + *          is copied to ConfigItemData.
> + * Note:
> + * - Some configurations require specific size and alignment for the allocated buffer. Refer to
> + *   the specific item configuration documentation for details.
> + * - Data may still be written to @ConfigItemData even if the return value is larger than
> + *   @ItemMaxSize, potentially causing buffer overflow.

Oh, amazing!

> + */
> +TSI_RESULT TSIX_TS_GetConfigItem(TSI_HANDLE Device, TSI_CONFIG_ID ConfigItemID,
> +				 void *ConfigItemData,
> +				 unsigned int ItemMaxSize);
> +
> +/**
> + * TSIX_DEV_RescanDevices() - Refresh the internal list of devices for libTSI
> + * @SearchOptions: Options to filter the list of devices (e.g.,
> + *                 TSI_SEARCHOPTIONS_SHOW_DEVICES_IN_USE to include
> + *                 devices already in use).
> + * @RequiredCaps: Filter to list only devices with specific capabilities.
> + * @UnallowedCaps: Filter to list only devices without specific capabilities.
> + *
> + * Returns: >=0 in case of success.

The returned value is not the amount of devices found? It's just some
arbitrary non-negative number?

Being a closed source blob I can well understand a "don't know" answer of
course.

Also, maybe add "<0 on error"?

> + *
> + * This function should be called every time you need to update the list of connected devices,
> + * and it must be called at least once before calling TSI_DEV_GetDeviceCount.
> + */
> +TSI_RESULT TSIX_DEV_RescanDevices(TSI_SEARCH_OPTIONS SearchOptions,
> +				  TSI_DEVICE_CAPS RequiredCaps,
> +				  TSI_DEVICE_CAPS UnallowedCaps);
> +/**
> + * TSIX_DEV_GetDeviceCount() - Get the count of scanned devices
> + * Returns: the number of devices that the previous call to TSIX_DEV_RescanDevices() detected
> + *
> + * Must be called after a TSIX_DEV_RescanDevices.
> + */
> +TSI_RESULT TSIX_DEV_GetDeviceCount(void);
> +
> +/**
> + * TSIX_DEV_OpenDevice() - Open a device from the scanned list
> + * @DeviceID: index in the TSI_DEV_RescanDevices list
> + * @Result: Pointer to store the error code returned while opening the device
> + * Returns: if the device is found, an opaque pointer that can be used for other
> + * API calls. If some error occurred during the detection, the status code is
> + * written in the pointer @Result.

Not in the pointer, I believe! :-)

Maybe "is written in *@Result."? But the sentence is actually redundant,
it's implicit in the @Result parameter description. I'd rather add what is
returned on error. Just guessing that's NULL:

 * Returns: if the device is found, an opaque pointer that can be used for other
 * API calls, or NULL on error.


> + */
> +TSI_HANDLE TSIX_DEV_OpenDevice(TSI_DEVICE_ID DeviceID, TSI_RESULT *Result);
> +
> +/**
> + * TSIX_DEV_CloseDevice() - Close the device handle when finished
> + * @Device: Device handle to close
> + * Returns: >=0 in case of success
> + */
> +TSI_RESULT TSIX_DEV_CloseDevice(TSI_HANDLE Device);

Why not moving TSIX_TS_GetConfigItem() and TSIX_TS_SetConfigItem() here,
alsop keeping them nearby? It looks to me logical: first the init/open
functions, then the get/set config, then the various video operations.

> +
> +/**
> + * TSIX_VIN_Disable() - Disable video input on the specified device
> + * @Device: Device handle to disable video input on
> + * Returns: >=0 in case of success
> + */
> +TSI_RESULT TSIX_VIN_Disable(TSI_HANDLE Device);
> +
> +/**
> + * TSIX_VIN_Select() - Select a specific video input on the specified device
> + * @Device: Device handle on which to select the input
> + * @InputID: Identifier of the input to select
> + * Returns: >=0 in case of success
> + */
> +TSI_RESULT TSIX_VIN_Select(TSI_HANDLE Device, TSI_INPUT_ID InputID);
> +
> +/**
> + * TSIX_DEV_SelectRole() - Select a specific role for the specified device
> + * @Device: Device handle on which to assign the role
> + * @RoleIndex: Index of the role to assign

Is there an enum telling us which values mean what?

PS: I see you can get a list and the names from
TSIX_DEV_GetDeviceRoleCount/Name(), below. One more reason to keep related
functions together...

> +/**
> + * TSIX_DEV_GetDeviceRoleName() - Get the name of a specific role for a device
> + * @Device: Device handle to query
> + * @RoleIndex: Index of the role to get the name for
> + * @RoleNameString: Pointer to store the role name
> + * @RoleStringMaxLength: Size of the allocated memory for @RoleNameString
> + *
> + * Returns: >=0 in case of success, the length of the role name string
> + * Note: If the return value is larger than RoleStringMaxLength, the string may be truncated
> + */
> +TSI_RESULT TSIX_DEV_GetDeviceRoleName(TSI_HANDLE Device, int RoleIndex,
> +				      char *RoleNameString, unsigned int RoleStringMaxLength);
> +

...as said above, TSIX_DEV_SelectRole() should probably be here.

> +TSI_RESULT TSIX_VIN_GetInputName(TSI_HANDLE Device, TSI_INPUT_ID InputID,
> +				 char *InputNameString, unsigned int NameStringMaxLen);
> +
> +#endif

As for patch 17, I'd add:

   #endif /* TSI_H */



--
Luca Ceresoli, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com