Skip to content

Reconsider urProgramCreateWithBinary signature #95

@FranklandJack

Description

@FranklandJack

Issue

The piProgramCreateWithBinary and urProgramCreateWithBinary entry points have different semantics.

piProgramCreateWithBinary has the following signature:

__SYCL_EXPORT pi_result piProgramCreateWithBinary(
    pi_context context, pi_uint32 num_devices, const pi_device *device_list,
    const size_t *lengths, const unsigned char **binaries,
    size_t num_metadata_entries, const pi_device_binary_property *metadata,
    pi_int32 *binary_status, pi_program *ret_program);

and urProgramCreateWithBinary has the following signature:

UR_APIEXPORT ur_result_t UR_APICALL
urProgramCreateWithBinary(
    ur_context_handle_t hContext,                   ///< [in] handle of the context instance
    ur_device_handle_t hDevice,                     ///< [in] handle to device associated with binary.
    size_t size,                                    ///< [in] size in bytes.
    const uint8_t* pBinary,                         ///< [in] pointer to binary.
    ur_program_handle_t* phProgram                  ///< [out] pointer to handle of Program object created.
    );

From the above we can see the following differences:

  1. piProgramCreateWithBinary takes a list of devices to create the program for (via the num_devices & device_lists params) where urProgramCreateWithBinary just takes a single device (via hDevice).
  2. piProgramCreateWithBinary takes a list of binaries to create a program with (via lengths and binaries params) whereas urProgramCreateWithBinary takes single binary (via size and pBinary params).
  3. piProgramCreateWithBinary takes a list of metadata entries (via the num_metadata_entries and metadata params)
  4. piProgramCreateWithBinary takes a binary_status param.

Examining the usage of piProgramCreateWithBinary we see that the DPC++ only passes one device to the entry point and takes one binary so differences 1. and 2. are valid. We do see however that the DPC++ runtime passes a metadata argument to the entry point, so difference 3. is invalid. Finally, the binary_status out parameter is an array of statuses, one for each device in the input, if there is only ever one device then this argument is redundant and can be folded into the return value.

As an aside, it looks like some adapters may only be able to support a single device e.g. L0.

Task

Add the metadata arguments to the urProgramCreateWithBinary so that the UR entry point matches the requirements of the DPC++ runtime.

Metadata

Metadata

Labels

compilerModule, program, or kernel issues.needs-discussionThis needs further discussionpiDPC++ PI requirementspecificationChanges or additions to the specification

Type

No type

Projects

No projects

Milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions