🚸 Support for "Bring-your-own-tokens" Driver

[ystade]

What's the problem this feature will solve?

Right now, when the driver establishes a connection to a device, i.e., a Device_Session it must know the respective authentication information for the device. However, in a scenario, where the client, not the driver, bought the compute power of the quantum resources and, hence, owns the respective tokens, it must be able to provide the tokens to the driver so that they can be forwarded to the device. Moreover, this must happen on a per-device basis.

Describe the solution you'd like

Consequently, this issue proposes a new function for the client interface:

/**
 * @brief Set a parameter for a session between the driver and a device.
 * @param[in] device A handle to the device of a client session. Must not be @c NULL.
 * @param[in] param The parameter to set. Must be one of the values specified
 * for @ref QDMI_Device_Parameter.
 * @param[in] size The size of the data pointed to by @p value in bytes. Must
 * not be zero, except when @p value is @c NULL, in which case it is ignored.
 * @param[in] value A pointer to the memory location that contains the value of
 * the parameter to be set. The data pointed to by @p value is copied and can be
 * safely reused after this function returns. If this is @c NULL, it is ignored.
 * @return @ref QDMI_SUCCESS if the driver supports the specified @p param and,
 * when @p value is not @c NULL, the value of the parameter was set
 * successfully.
 * @return @ref QDMI_ERROR_NOTSUPPORTED if the driver does not support the
 * parameter or the value of the parameter.
 * @return @ref QDMI_ERROR_INVALIDARGUMENT if
 *  - @p session is @c NULL,
 *  - @p param is invalid, or
 *  - @p value is not @c NULL and @p size is zero or not the expected size for
 *    the parameter (if specified by the @ref QDMI_Device_Parameter
 *    documentation).
 * @return @ref QDMI_ERROR_BADSTATE if the parameter cannot be set in the
 * current state of the session.
 * todo: What is a bad state here?
 * @return @ref QDMI_ERROR_FATAL if an unexpected error occurred.
 *
 * @note By calling this function with @p value set to @c NULL, the function can
 * be used to check if the driver supports the specified parameter without
 * setting a value.
 */
int QDMI_device_set_parameter(QDMI_Session session,
                               QDMI_Device_Parameter param, size_t size,
                               const void *value);

[burgholzer]

Thanks for pulling out this issue!
I like that this already has a concrete proposal here 👍🏼

Just to add to the proposal:

• This proposal not only entails the new function, it probably also requires a new enumeration. At least, if we do not want to reuse an existing enum.
• In order to stick with the naming scheme of QDMI, the function name most likely would have to start with "QDMI_session_set_XXX_parameter", where XXX could be "device".

Somehow that proposal does not quite fit perfectly. We already have a setter for session parameters. But this is more so a setter for parameters of a specific device session.
We would have the QDMI_DEVICE_SESSION_PARAMETER enum for that. It's just an open question how to tie that to particular devices given a session.

[ystade]

I agree that it requires also the corresponding enum but regarding the naming, I think my proposal makes sense. The part after the Prefix QDMI_ always denotes the entity that is passed as the first argument. Since the device contains the information about the corresponding (client) session, it suffices to pass here the device, and passing the session is not necessary (as it can be derived from the device). Hence, the name QDMI_device_set_parameter

[burgholzer]

I agree that it requires also the corresponding enum but regarding the naming, I think my proposal makes sense. The part after the Prefix QDMI_ always denotes the entity that is passed as the first argument. Since the device contains the information about the corresponding (client) session, it suffices to pass here the device, and passing the session is not necessary (as it can be derived from the device). Hence, the name QDMI_device_set_parameter

Then the signature in the issue description is wrong ;o)

The proposal still does not fully work. You can only have a device handle if a session has already been established. You'd need the information this function is supposed to provide to make that happen though.

[ystade]

Just to clarify because I was confused myself at first: The problem is that in order to retrieve the available devices from the session (after the session is initialized), the information, i.e., the tokens for each device must already be known to the driver. Note, that before the driver returns the list of available devices, the driver establishes a QDMI_Device_Session to each device. Consequently, in the current state of the interface, every device handle that the client receives corresponds to an established QDMI_Device_Session. Hence, the client would need to provide the credentials for a certain device in another way and must tell the driver in some way to which device the piece of information belongs.