Confusing description of CL_DEVICE_PARTITION_PROPERTIES

[s-barannikov]

The return type of CL_DEVICE_PARTITION_PROPERTIES query is cl_device_partition_property[] (an array), but the description says:

If the device cannot be partitioned (i.e. there is no partitioning scheme supported by the device that will return at least two sub-devices), a value of 0 will be returned.

Should it instead say "an empty array will be returned"? Or does it mean the returned array should contain one element (0)?

[bashbaug]

Hmm, looking at a CTS test that performs this query, it seems like there are two possibilities if no partition properties are supported:

1. The query can return a size of zero to indicate that no partition properties are supported.
2. The query can return a a single element in the array consisting only of the list terminator 0.

All else being equal, I'd recommend (1) since it's more consistent with other array queries, such as CL_QUEUE_PROPERTIES_ARRAY, but I suppose either would be considered valid.

If this makes sense, we should probably clarify that either of the possibilities is valid, since they both could be considered "a value of 0".

[s-barannikov]

Thanks, I'll go for (1) then.

If this makes sense, we should probably clarify that either of the possibilities is valid, since they both could be considered "a value of 0".

CL_DEVICE_PARTITION_TYPE has a description similar to what you suggest:

Otherwise the implementation may either return a param_value_size_ret of 0 i.e. there is no partition type associated with device or can return a property value of 0 (where 0 is used to terminate the partition property list) in the memory that param_value points to.

Pedantic concern: allowing two possibilities requires library consumers to check both, not just one.

[bashbaug]

Yeah, I agree having two possibilities is undesirable.

FWIW, it looks like most (almost all?) implementations actually went with option (2), at least those in the database:

https://opencl.gpuinfo.org/displaydeviceinfo.php?name=CL_DEVICE_PARTITION_PROPERTIES

I'm not sure if we can mandate this behavior, but maybe we could insert some "should" language to nudge implementations in this direction.

[s-barannikov]

An odd thing about option (2) is that if the returned list is not empty, it is not [required to be] null-terminated.