Skip to content

Commit d47bd7e

Browse files
aarongreigaarongreig
committed
Fix a few small spec issues:
* Clarify INVALID_SIZE return for PlatformGet * Add PROFILING_INFO_NOT_AVAILABLE to GetProfilingInfo returns * Make WriteHostPipe's phEvent param optional (matches other phEvent params)
1 parent dcbf226 commit d47bd7e

File tree

10 files changed

+32
-19
lines changed

10 files changed

+32
-19
lines changed

‎include/ur_api.h

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -946,6 +946,7 @@ typedef enum ur_adapter_backend_t {
946946
/// - ::UR_RESULT_ERROR_INVALID_NULL_POINTER
947947
/// + `NULL == phAdapters`
948948
/// - ::UR_RESULT_ERROR_INVALID_SIZE
949+
/// + `NumEntries == 0 && phPlatforms != NULL`
949950
UR_APIEXPORT ur_result_t UR_APICALL
950951
urPlatformGet(
951952
ur_adapter_handle_t *phAdapters, ///< [in][range(0, NumAdapters)] array of adapters to query for platforms.
@@ -5521,6 +5522,8 @@ urEventGetInfo(
55215522
/// + `NULL == hEvent`
55225523
/// - ::UR_RESULT_ERROR_INVALID_ENUMERATION
55235524
/// + `::UR_PROFILING_INFO_COMMAND_COMPLETE < propName`
5525+
/// - ::UR_RESULT_ERROR_PROFILING_INFO_NOT_AVAILABLE
5526+
/// + If `hEvent`s associated queue was not created with `UR_QUEUE_FLAG_PROFILING_ENABLE`.
55245527
/// - ::UR_RESULT_ERROR_INVALID_VALUE
55255528
/// + `pPropValue && propSize == 0`
55265529
/// - ::UR_RESULT_ERROR_INVALID_EVENT
@@ -6937,7 +6940,6 @@ urEnqueueReadHostPipe(
69376940
/// - ::UR_RESULT_ERROR_INVALID_NULL_POINTER
69386941
/// + `NULL == pipe_symbol`
69396942
/// + `NULL == pSrc`
6940-
/// + `NULL == phEvent`
69416943
/// - ::UR_RESULT_ERROR_INVALID_EVENT_WAIT_LIST
69426944
/// + `phEventWaitList == NULL && numEventsInWaitList > 0`
69436945
/// + `phEventWaitList != NULL && numEventsInWaitList == 0`
@@ -6958,7 +6960,7 @@ urEnqueueWriteHostPipe(
69586960
const ur_event_handle_t *phEventWaitList, ///< [in][optional][range(0, numEventsInWaitList)] pointer to a list of
69596961
///< events that must be complete before the host pipe write.
69606962
///< If nullptr, the numEventsInWaitList must be 0, indicating that no wait event.
6961-
ur_event_handle_t *phEvent ///< [out] returns an event object that identifies this write command
6963+
ur_event_handle_t *phEvent ///< [out][optional] returns an event object that identifies this write command
69626964
///< and can be used to query or queue a wait for this command to complete.
69636965
);
69646966

‎scripts/core/enqueue.yml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1458,7 +1458,7 @@ params:
14581458
- type: $x_event_handle_t*
14591459
name: phEvent
14601460
desc: |
1461-
[out] returns an event object that identifies this write command
1461+
[out][optional] returns an event object that identifies this write command
14621462
and can be used to query or queue a wait for this command to complete.
14631463
returns:
14641464
- $X_RESULT_ERROR_INVALID_EVENT_WAIT_LIST:

‎scripts/core/event.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -185,6 +185,8 @@ params:
185185
name: pPropSizeRet
186186
desc: "[out][optional] pointer to the actual size in bytes returned in propValue"
187187
returns:
188+
- $X_RESULT_ERROR_PROFILING_INFO_NOT_AVAILABLE:
189+
- "If `hEvent`s associated queue was not created with `UR_QUEUE_FLAG_PROFILING_ENABLE`."
188190
- $X_RESULT_ERROR_INVALID_VALUE:
189191
- "`pPropValue && propSize == 0`"
190192
- $X_RESULT_ERROR_INVALID_EVENT

‎scripts/core/platform.yml

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -46,7 +46,8 @@ params:
4646
desc: |
4747
[out][optional] returns the total number of platforms available.
4848
returns:
49-
- $X_RESULT_ERROR_INVALID_SIZE
49+
- $X_RESULT_ERROR_INVALID_SIZE:
50+
- "`NumEntries == 0 && phPlatforms != NULL`"
5051
--- #--------------------------------------------------------------------------
5152
type: enum
5253
desc: "Supported platform info"

‎source/adapters/null/ur_nullddi.cpp

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3832,7 +3832,7 @@ __urdlllocal ur_result_t UR_APICALL urEnqueueWriteHostPipe(
38323832
///< events that must be complete before the host pipe write.
38333833
///< If nullptr, the numEventsInWaitList must be 0, indicating that no wait event.
38343834
ur_event_handle_t *
3835-
phEvent ///< [out] returns an event object that identifies this write command
3835+
phEvent ///< [out][optional] returns an event object that identifies this write command
38363836
///< and can be used to query or queue a wait for this command to complete.
38373837
) try {
38383838
ur_result_t result = UR_RESULT_SUCCESS;
@@ -3845,7 +3845,9 @@ __urdlllocal ur_result_t UR_APICALL urEnqueueWriteHostPipe(
38453845
phEvent);
38463846
} else {
38473847
// generic implementation
3848-
*phEvent = reinterpret_cast<ur_event_handle_t>(d_context.get());
3848+
if (nullptr != phEvent) {
3849+
*phEvent = reinterpret_cast<ur_event_handle_t>(d_context.get());
3850+
}
38493851
}
38503852

38513853
return result;

‎source/loader/layers/tracing/ur_trcddi.cpp

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4338,7 +4338,7 @@ __urdlllocal ur_result_t UR_APICALL urEnqueueWriteHostPipe(
43384338
///< events that must be complete before the host pipe write.
43394339
///< If nullptr, the numEventsInWaitList must be 0, indicating that no wait event.
43404340
ur_event_handle_t *
4341-
phEvent ///< [out] returns an event object that identifies this write command
4341+
phEvent ///< [out][optional] returns an event object that identifies this write command
43424342
///< and can be used to query or queue a wait for this command to complete.
43434343
) {
43444344
auto pfnWriteHostPipe = context.urDdiTable.Enqueue.pfnWriteHostPipe;

‎source/loader/layers/validation/ur_valddi.cpp

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -214,6 +214,10 @@ __urdlllocal ur_result_t UR_APICALL urPlatformGet(
214214
if (NULL == phAdapters) {
215215
return UR_RESULT_ERROR_INVALID_NULL_POINTER;
216216
}
217+
218+
if (NumEntries == 0 && phPlatforms != NULL) {
219+
return UR_RESULT_ERROR_INVALID_SIZE;
220+
}
217221
}
218222

219223
ur_result_t result =
@@ -5520,7 +5524,7 @@ __urdlllocal ur_result_t UR_APICALL urEnqueueWriteHostPipe(
55205524
///< events that must be complete before the host pipe write.
55215525
///< If nullptr, the numEventsInWaitList must be 0, indicating that no wait event.
55225526
ur_event_handle_t *
5523-
phEvent ///< [out] returns an event object that identifies this write command
5527+
phEvent ///< [out][optional] returns an event object that identifies this write command
55245528
///< and can be used to query or queue a wait for this command to complete.
55255529
) {
55265530
auto pfnWriteHostPipe = context.urDdiTable.Enqueue.pfnWriteHostPipe;
@@ -5546,10 +5550,6 @@ __urdlllocal ur_result_t UR_APICALL urEnqueueWriteHostPipe(
55465550
return UR_RESULT_ERROR_INVALID_NULL_POINTER;
55475551
}
55485552

5549-
if (NULL == phEvent) {
5550-
return UR_RESULT_ERROR_INVALID_NULL_POINTER;
5551-
}
5552-
55535553
if (phEventWaitList == NULL && numEventsInWaitList > 0) {
55545554
return UR_RESULT_ERROR_INVALID_EVENT_WAIT_LIST;
55555555
}

‎source/loader/ur_ldrddi.cpp

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -5271,7 +5271,7 @@ __urdlllocal ur_result_t UR_APICALL urEnqueueWriteHostPipe(
52715271
///< events that must be complete before the host pipe write.
52725272
///< If nullptr, the numEventsInWaitList must be 0, indicating that no wait event.
52735273
ur_event_handle_t *
5274-
phEvent ///< [out] returns an event object that identifies this write command
5274+
phEvent ///< [out][optional] returns an event object that identifies this write command
52755275
///< and can be used to query or queue a wait for this command to complete.
52765276
) {
52775277
ur_result_t result = UR_RESULT_SUCCESS;
@@ -5308,8 +5308,10 @@ __urdlllocal ur_result_t UR_APICALL urEnqueueWriteHostPipe(
53085308

53095309
try {
53105310
// convert platform handle to loader handle
5311-
*phEvent = reinterpret_cast<ur_event_handle_t>(
5312-
ur_event_factory.getInstance(*phEvent, dditable));
5311+
if (nullptr != phEvent) {
5312+
*phEvent = reinterpret_cast<ur_event_handle_t>(
5313+
ur_event_factory.getInstance(*phEvent, dditable));
5314+
}
53135315
} catch (std::bad_alloc &) {
53145316
result = UR_RESULT_ERROR_OUT_OF_HOST_MEMORY;
53155317
}

‎source/loader/ur_libapi.cpp

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -453,6 +453,7 @@ ur_result_t UR_APICALL urAdapterGetInfo(
453453
/// - ::UR_RESULT_ERROR_INVALID_NULL_POINTER
454454
/// + `NULL == phAdapters`
455455
/// - ::UR_RESULT_ERROR_INVALID_SIZE
456+
/// + `NumEntries == 0 && phPlatforms != NULL`
456457
ur_result_t UR_APICALL urPlatformGet(
457458
ur_adapter_handle_t *
458459
phAdapters, ///< [in][range(0, NumAdapters)] array of adapters to query for platforms.
@@ -4332,6 +4333,8 @@ ur_result_t UR_APICALL urEventGetInfo(
43324333
/// + `NULL == hEvent`
43334334
/// - ::UR_RESULT_ERROR_INVALID_ENUMERATION
43344335
/// + `::UR_PROFILING_INFO_COMMAND_COMPLETE < propName`
4336+
/// - ::UR_RESULT_ERROR_PROFILING_INFO_NOT_AVAILABLE
4337+
/// + If `hEvent`s associated queue was not created with `UR_QUEUE_FLAG_PROFILING_ENABLE`.
43354338
/// - ::UR_RESULT_ERROR_INVALID_VALUE
43364339
/// + `pPropValue && propSize == 0`
43374340
/// - ::UR_RESULT_ERROR_INVALID_EVENT
@@ -6089,7 +6092,6 @@ ur_result_t UR_APICALL urEnqueueReadHostPipe(
60896092
/// - ::UR_RESULT_ERROR_INVALID_NULL_POINTER
60906093
/// + `NULL == pipe_symbol`
60916094
/// + `NULL == pSrc`
6092-
/// + `NULL == phEvent`
60936095
/// - ::UR_RESULT_ERROR_INVALID_EVENT_WAIT_LIST
60946096
/// + `phEventWaitList == NULL && numEventsInWaitList > 0`
60956097
/// + `phEventWaitList != NULL && numEventsInWaitList == 0`
@@ -6116,7 +6118,7 @@ ur_result_t UR_APICALL urEnqueueWriteHostPipe(
61166118
///< events that must be complete before the host pipe write.
61176119
///< If nullptr, the numEventsInWaitList must be 0, indicating that no wait event.
61186120
ur_event_handle_t *
6119-
phEvent ///< [out] returns an event object that identifies this write command
6121+
phEvent ///< [out][optional] returns an event object that identifies this write command
61206122
///< and can be used to query or queue a wait for this command to complete.
61216123
) try {
61226124
auto pfnWriteHostPipe =

‎source/ur_api.cpp

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -398,6 +398,7 @@ ur_result_t UR_APICALL urAdapterGetInfo(
398398
/// - ::UR_RESULT_ERROR_INVALID_NULL_POINTER
399399
/// + `NULL == phAdapters`
400400
/// - ::UR_RESULT_ERROR_INVALID_SIZE
401+
/// + `NumEntries == 0 && phPlatforms != NULL`
401402
ur_result_t UR_APICALL urPlatformGet(
402403
ur_adapter_handle_t *
403404
phAdapters, ///< [in][range(0, NumAdapters)] array of adapters to query for platforms.
@@ -3664,6 +3665,8 @@ ur_result_t UR_APICALL urEventGetInfo(
36643665
/// + `NULL == hEvent`
36653666
/// - ::UR_RESULT_ERROR_INVALID_ENUMERATION
36663667
/// + `::UR_PROFILING_INFO_COMMAND_COMPLETE < propName`
3668+
/// - ::UR_RESULT_ERROR_PROFILING_INFO_NOT_AVAILABLE
3669+
/// + If `hEvent`s associated queue was not created with `UR_QUEUE_FLAG_PROFILING_ENABLE`.
36673670
/// - ::UR_RESULT_ERROR_INVALID_VALUE
36683671
/// + `pPropValue && propSize == 0`
36693672
/// - ::UR_RESULT_ERROR_INVALID_EVENT
@@ -5181,7 +5184,6 @@ ur_result_t UR_APICALL urEnqueueReadHostPipe(
51815184
/// - ::UR_RESULT_ERROR_INVALID_NULL_POINTER
51825185
/// + `NULL == pipe_symbol`
51835186
/// + `NULL == pSrc`
5184-
/// + `NULL == phEvent`
51855187
/// - ::UR_RESULT_ERROR_INVALID_EVENT_WAIT_LIST
51865188
/// + `phEventWaitList == NULL && numEventsInWaitList > 0`
51875189
/// + `phEventWaitList != NULL && numEventsInWaitList == 0`
@@ -5208,7 +5210,7 @@ ur_result_t UR_APICALL urEnqueueWriteHostPipe(
52085210
///< events that must be complete before the host pipe write.
52095211
///< If nullptr, the numEventsInWaitList must be 0, indicating that no wait event.
52105212
ur_event_handle_t *
5211-
phEvent ///< [out] returns an event object that identifies this write command
5213+
phEvent ///< [out][optional] returns an event object that identifies this write command
52125214
///< and can be used to query or queue a wait for this command to complete.
52135215
) {
52145216
ur_result_t result = UR_RESULT_SUCCESS;

0 commit comments

Comments
 (0)