Skip to content

Commit 12e8bda

Browse files
ldrummldrumm
committed
[NFC] Manual reflow of some awkward comments
The comments are now more left-aligned leaving more space for prose.
1 parent c02bf54 commit 12e8bda

23 files changed

+2663
-2364
lines changed

‎source/adapters/cuda/ur_interface_loader.cpp

+12-12
Original file line numberDiff line numberDiff line change
@@ -268,10 +268,10 @@ UR_DLLEXPORT ur_result_t UR_APICALL urGetDeviceProcAddrTable(
268268
}
269269

270270
UR_DLLEXPORT ur_result_t UR_APICALL urGetCommandBufferExpProcAddrTable(
271-
ur_api_version_t version, ///< [in] API version requested
272-
ur_command_buffer_exp_dditable_t
273-
*pDdiTable ///< [in,out] pointer to table of DDI function pointers
274-
) {
271+
/// [in] API version requested
272+
ur_api_version_t version,
273+
/// [in,out] pointer to table of DDI function pointers
274+
ur_command_buffer_exp_dditable_t *pDdiTable) {
275275
auto retVal = validateProcInputs(version, pDdiTable);
276276
if (UR_RESULT_SUCCESS != retVal) {
277277
return retVal;
@@ -368,10 +368,10 @@ UR_DLLEXPORT ur_result_t UR_APICALL urGetUSMExpProcAddrTable(
368368
}
369369

370370
UR_DLLEXPORT ur_result_t UR_APICALL urGetVirtualMemProcAddrTable(
371-
ur_api_version_t version, ///< [in] API version requested
372-
ur_virtual_mem_dditable_t
373-
*pDdiTable ///< [in,out] pointer to table of DDI function pointers
374-
) {
371+
/// [in] API version requested
372+
ur_api_version_t version,
373+
/// [in,out] pointer to table of DDI function pointers
374+
ur_virtual_mem_dditable_t *pDdiTable) {
375375
auto retVal = validateProcInputs(version, pDdiTable);
376376
if (UR_RESULT_SUCCESS != retVal) {
377377
return retVal;
@@ -389,10 +389,10 @@ UR_DLLEXPORT ur_result_t UR_APICALL urGetVirtualMemProcAddrTable(
389389
}
390390

391391
UR_DLLEXPORT ur_result_t UR_APICALL urGetPhysicalMemProcAddrTable(
392-
ur_api_version_t version, ///< [in] API version requested
393-
ur_physical_mem_dditable_t
394-
*pDdiTable ///< [in,out] pointer to table of DDI function pointers
395-
) {
392+
/// [in] API version requested
393+
ur_api_version_t version,
394+
/// [in,out] pointer to table of DDI function pointers
395+
ur_physical_mem_dditable_t *pDdiTable) {
396396
auto retVal = validateProcInputs(version, pDdiTable);
397397
if (UR_RESULT_SUCCESS != retVal) {
398398
return retVal;

‎source/adapters/cuda/usm.cpp

+21-18
Original file line numberDiff line numberDiff line change
@@ -439,12 +439,13 @@ bool ur_usm_pool_handle_t_::hasUMFPool(umf_memory_pool_t *umf_pool) {
439439
}
440440

441441
UR_APIEXPORT ur_result_t UR_APICALL urUSMPoolCreate(
442-
ur_context_handle_t Context, ///< [in] handle of the context object
443-
ur_usm_pool_desc_t
444-
*PoolDesc, ///< [in] pointer to USM pool descriptor. Can be chained with
445-
///< ::ur_usm_pool_limits_desc_t
446-
ur_usm_pool_handle_t *Pool ///< [out] pointer to USM memory pool
447-
) {
442+
/// [in] handle of the context object
443+
ur_context_handle_t Context,
444+
/// [in] pointer to USM pool descriptor. Can be chained with
445+
/// ::ur_usm_pool_limits_desc_t
446+
ur_usm_pool_desc_t *PoolDesc,
447+
/// [out] pointer to USM memory pool
448+
ur_usm_pool_handle_t *Pool) {
448449
// Without pool tracking we can't free pool allocations.
449450
#ifdef UMF_ENABLE_POOL_TRACKING
450451
if (PoolDesc->flags & UR_USM_POOL_FLAG_ZERO_INITIALIZE_BLOCK) {
@@ -470,15 +471,15 @@ UR_APIEXPORT ur_result_t UR_APICALL urUSMPoolCreate(
470471
}
471472

472473
UR_APIEXPORT ur_result_t UR_APICALL urUSMPoolRetain(
473-
ur_usm_pool_handle_t Pool ///< [in] pointer to USM memory pool
474-
) {
474+
/// [in] pointer to USM memory pool
475+
ur_usm_pool_handle_t Pool) {
475476
Pool->incrementReferenceCount();
476477
return UR_RESULT_SUCCESS;
477478
}
478479

479480
UR_APIEXPORT ur_result_t UR_APICALL urUSMPoolRelease(
480-
ur_usm_pool_handle_t Pool ///< [in] pointer to USM memory pool
481-
) {
481+
/// [in] pointer to USM memory pool
482+
ur_usm_pool_handle_t Pool) {
482483
if (Pool->decrementReferenceCount() > 0) {
483484
return UR_RESULT_SUCCESS;
484485
}
@@ -488,14 +489,16 @@ UR_APIEXPORT ur_result_t UR_APICALL urUSMPoolRelease(
488489
}
489490

490491
UR_APIEXPORT ur_result_t UR_APICALL urUSMPoolGetInfo(
491-
ur_usm_pool_handle_t hPool, ///< [in] handle of the USM memory pool
492-
ur_usm_pool_info_t propName, ///< [in] name of the pool property to query
493-
size_t propSize, ///< [in] size in bytes of the pool property value provided
494-
void *pPropValue, ///< [out][optional][typename(propName, propSize)] value
495-
///< of the pool property
496-
size_t *pPropSizeRet ///< [out][optional] size in bytes returned in pool
497-
///< property value
498-
) {
492+
/// [in] handle of the USM memory pool
493+
ur_usm_pool_handle_t hPool,
494+
/// [in] name of the pool property to query
495+
ur_usm_pool_info_t propName,
496+
/// [in] size in bytes of the pool property value provided
497+
size_t propSize,
498+
/// [out][optional][typename(propName, propSize)] value of the pool property
499+
void *pPropValue,
500+
/// [out][optional] size in bytes returned in pool property value
501+
size_t *pPropSizeRet) {
499502
UrReturnHelper ReturnValue(propSize, pPropValue, pPropSizeRet);
500503

501504
switch (propName) {

‎source/adapters/hip/ur_interface_loader.cpp

+8-8
Original file line numberDiff line numberDiff line change
@@ -335,10 +335,10 @@ urGetUSMExpProcAddrTable(ur_api_version_t, ur_usm_exp_dditable_t *) {
335335
}
336336

337337
UR_DLLEXPORT ur_result_t UR_APICALL urGetVirtualMemProcAddrTable(
338-
ur_api_version_t version, ///< [in] API version requested
339-
ur_virtual_mem_dditable_t
340-
*pDdiTable ///< [in,out] pointer to table of DDI function pointers
341-
) {
338+
/// [in] API version requested
339+
ur_api_version_t version,
340+
/// [in,out] pointer to table of DDI function pointers
341+
ur_virtual_mem_dditable_t *pDdiTable) {
342342
auto retVal = validateProcInputs(version, pDdiTable);
343343
if (UR_RESULT_SUCCESS != retVal) {
344344
return retVal;
@@ -356,10 +356,10 @@ UR_DLLEXPORT ur_result_t UR_APICALL urGetVirtualMemProcAddrTable(
356356
}
357357

358358
UR_DLLEXPORT ur_result_t UR_APICALL urGetPhysicalMemProcAddrTable(
359-
ur_api_version_t version, ///< [in] API version requested
360-
ur_physical_mem_dditable_t
361-
*pDdiTable ///< [in,out] pointer to table of DDI function pointers
362-
) {
359+
/// [in] API version requested
360+
ur_api_version_t version,
361+
/// [in,out] pointer to table of DDI function pointers
362+
ur_physical_mem_dditable_t *pDdiTable) {
363363
auto retVal = validateProcInputs(version, pDdiTable);
364364
if (UR_RESULT_SUCCESS != retVal) {
365365
return retVal;

‎source/adapters/hip/usm.cpp

+21-18
Original file line numberDiff line numberDiff line change
@@ -382,12 +382,13 @@ bool ur_usm_pool_handle_t_::hasUMFPool(umf_memory_pool_t *umf_pool) {
382382
}
383383

384384
UR_APIEXPORT ur_result_t UR_APICALL urUSMPoolCreate(
385-
ur_context_handle_t Context, ///< [in] handle of the context object
386-
ur_usm_pool_desc_t
387-
*PoolDesc, ///< [in] pointer to USM pool descriptor. Can be chained with
388-
///< ::ur_usm_pool_limits_desc_t
389-
ur_usm_pool_handle_t *Pool ///< [out] pointer to USM memory pool
390-
) {
385+
/// [in] handle of the context object
386+
ur_context_handle_t Context,
387+
/// [in] pointer to USM pool descriptor. Can be chained with
388+
/// ::ur_usm_pool_limits_desc_t
389+
ur_usm_pool_desc_t *PoolDesc,
390+
/// [out] pointer to USM memory pool
391+
ur_usm_pool_handle_t *Pool) {
391392
// Without pool tracking we can't free pool allocations.
392393
#ifdef UMF_ENABLE_POOL_TRACKING
393394
if (PoolDesc->flags & UR_USM_POOL_FLAG_ZERO_INITIALIZE_BLOCK) {
@@ -413,15 +414,15 @@ UR_APIEXPORT ur_result_t UR_APICALL urUSMPoolCreate(
413414
}
414415

415416
UR_APIEXPORT ur_result_t UR_APICALL urUSMPoolRetain(
416-
ur_usm_pool_handle_t Pool ///< [in] pointer to USM memory pool
417-
) {
417+
/// [in] pointer to USM memory pool
418+
ur_usm_pool_handle_t Pool) {
418419
Pool->incrementReferenceCount();
419420
return UR_RESULT_SUCCESS;
420421
}
421422

422423
UR_APIEXPORT ur_result_t UR_APICALL urUSMPoolRelease(
423-
ur_usm_pool_handle_t Pool ///< [in] pointer to USM memory pool
424-
) {
424+
/// [in] pointer to USM memory pool
425+
ur_usm_pool_handle_t Pool) {
425426
if (Pool->decrementReferenceCount() > 0) {
426427
return UR_RESULT_SUCCESS;
427428
}
@@ -431,14 +432,16 @@ UR_APIEXPORT ur_result_t UR_APICALL urUSMPoolRelease(
431432
}
432433

433434
UR_APIEXPORT ur_result_t UR_APICALL urUSMPoolGetInfo(
434-
ur_usm_pool_handle_t hPool, ///< [in] handle of the USM memory pool
435-
ur_usm_pool_info_t propName, ///< [in] name of the pool property to query
436-
size_t propSize, ///< [in] size in bytes of the pool property value provided
437-
void *pPropValue, ///< [out][optional][typename(propName, propSize)] value
438-
///< of the pool property
439-
size_t *pPropSizeRet ///< [out][optional] size in bytes returned in pool
440-
///< property value
441-
) {
435+
/// [in] handle of the USM memory pool
436+
ur_usm_pool_handle_t hPool,
437+
/// [in] name of the pool property to query
438+
ur_usm_pool_info_t propName,
439+
/// [in] size in bytes of the pool property value provided
440+
size_t propSize,
441+
/// [out][optional][typename(propName, propSize)] value of the pool property
442+
void *pPropValue,
443+
/// [out][optional] size in bytes returned in pool property value
444+
size_t *pPropSizeRet) {
442445
UrReturnHelper ReturnValue(propSize, pPropValue, pPropSizeRet);
443446

444447
switch (propName) {

‎source/adapters/level_zero/adapter.cpp

+18-19
Original file line numberDiff line numberDiff line change
@@ -626,19 +626,16 @@ ur_result_t adapterStateTeardown() {
626626

627627
namespace ur::level_zero {
628628
ur_result_t urAdapterGet(
629-
uint32_t NumEntries, ///< [in] the number of platforms to be added to
630-
///< phAdapters. If phAdapters is not NULL, then
631-
///< NumEntries should be greater than zero, otherwise
632-
///< ::UR_RESULT_ERROR_INVALID_SIZE, will be returned.
633-
ur_adapter_handle_t
634-
*Adapters, ///< [out][optional][range(0, NumEntries)] array of handle of
635-
///< adapters. If NumEntries is less than the number of
636-
///< adapters available, then
637-
///< ::urAdapterGet shall only retrieve that number of
638-
///< platforms.
639-
uint32_t *NumAdapters ///< [out][optional] returns the total number of
640-
///< adapters available.
641-
) {
629+
/// [in] the number of platforms to be added to phAdapters. If phAdapters is
630+
/// not NULL, then NumEntries should be greater than zero, otherwise
631+
/// ::UR_RESULT_ERROR_INVALID_SIZE, will be returned.
632+
uint32_t NumEntries,
633+
/// [out][optional][range(0, NumEntries)] array of handle of adapters.
634+
/// If NumEntries is less than the number of adapters available, then
635+
/// ::urAdapterGet shall only retrieve that number of platforms.
636+
ur_adapter_handle_t *Adapters,
637+
/// [out][optional] returns the total number of adapters available.
638+
uint32_t *NumAdapters) {
642639
if (NumEntries > 0 && Adapters) {
643640
if (GlobalAdapter) {
644641
std::lock_guard<std::mutex> Lock{GlobalAdapter->Mutex};
@@ -688,12 +685,14 @@ ur_result_t urAdapterRetain(ur_adapter_handle_t) {
688685
}
689686

690687
ur_result_t urAdapterGetLastError(
691-
ur_adapter_handle_t, ///< [in] handle of the platform instance
692-
const char **Message, ///< [out] pointer to a C string where the adapter
693-
///< specific error message will be stored.
694-
int32_t *Error ///< [out] pointer to an integer where the adapter specific
695-
///< error code will be stored.
696-
) {
688+
/// [in] handle of the platform instance
689+
ur_adapter_handle_t,
690+
/// [out] pointer to a C string where the adapter specific error message
691+
/// will be stored.
692+
const char **Message,
693+
/// [out] pointer to an integer where the adapter specific error code will
694+
/// be stored.
695+
int32_t *Error) {
697696
*Message = ErrorMessage;
698697
*Error = ErrorAdapterNativeCode;
699698

‎source/adapters/level_zero/context.cpp

+41-39
Original file line numberDiff line numberDiff line change
@@ -21,14 +21,14 @@
2121
namespace ur::level_zero {
2222

2323
ur_result_t urContextCreate(
24-
uint32_t DeviceCount, ///< [in] the number of devices given in phDevices
25-
const ur_device_handle_t
26-
*Devices, ///< [in][range(0, DeviceCount)] array of handle of devices.
27-
const ur_context_properties_t
28-
*Properties, ///< [in][optional] pointer to context creation properties.
29-
ur_context_handle_t
30-
*RetContext ///< [out] pointer to handle of context object created
31-
) {
24+
/// [in] the number of devices given in phDevices
25+
uint32_t DeviceCount,
26+
/// [in][range(0, DeviceCount)] array of handle of devices.
27+
const ur_device_handle_t *Devices,
28+
/// [in][optional] pointer to context creation properties.
29+
const ur_context_properties_t *Properties,
30+
/// [out] pointer to handle of context object created
31+
ur_context_handle_t *RetContext) {
3232
std::ignore = Properties;
3333

3434
ur_platform_handle_t Platform = Devices[0]->Platform;
@@ -58,16 +58,16 @@ ur_result_t urContextCreate(
5858
}
5959

6060
ur_result_t urContextRetain(
61-
ur_context_handle_t
62-
Context ///< [in] handle of the context to get a reference of.
63-
) {
61+
62+
/// [in] handle of the context to get a reference of.
63+
ur_context_handle_t Context) {
6464
Context->RefCount.increment();
6565
return UR_RESULT_SUCCESS;
6666
}
6767

6868
ur_result_t urContextRelease(
69-
ur_context_handle_t Context ///< [in] handle of the context to release.
70-
) {
69+
/// [in] handle of the context to release.
70+
ur_context_handle_t Context) {
7171
ur_platform_handle_t Plt = Context->getPlatform();
7272
std::unique_lock<ur_shared_mutex> ContextsLock(Plt->ContextsMutex,
7373
std::defer_lock);
@@ -90,18 +90,20 @@ static const bool UseMemcpy2DOperations = [] {
9090
}();
9191

9292
ur_result_t urContextGetInfo(
93-
ur_context_handle_t Context, ///< [in] handle of the context
94-
ur_context_info_t ContextInfoType, ///< [in] type of the info to retrieve
95-
size_t PropSize, ///< [in] the number of bytes of memory pointed to by
96-
///< pContextInfo.
97-
void *ContextInfo, ///< [out][optional] array of bytes holding the info.
98-
///< if propSize is not equal to or greater than the
99-
///< real number of bytes needed to return the info then
100-
///< the ::UR_RESULT_ERROR_INVALID_SIZE error is
101-
///< returned and pContextInfo is not used.
102-
size_t *PropSizeRet ///< [out][optional] pointer to the actual size in
103-
///< bytes of data queried by ContextInfoType.
104-
) {
93+
/// [in] handle of the context
94+
ur_context_handle_t Context,
95+
/// [in] type of the info to retrieve
96+
ur_context_info_t ContextInfoType,
97+
/// [in] the number of bytes of memory pointed to by pContextInfo.
98+
size_t PropSize,
99+
/// [out][optional] array of bytes holding the info. if propSize is not
100+
/// equal to or greater than the real number of bytes needed to return the
101+
/// info then the ::UR_RESULT_ERROR_INVALID_SIZE error is returned and
102+
/// pContextInfo is not used.
103+
void *ContextInfo,
104+
/// [out][optional] pointer to the actual size in bytes of data queried by
105+
/// ContextInfoType.
106+
size_t *PropSizeRet) {
105107
std::shared_lock<ur_shared_mutex> Lock(Context->Mutex);
106108
UrReturnHelper ReturnValue(PropSize, ContextInfo, PropSizeRet);
107109
switch (
@@ -141,22 +143,22 @@ ur_result_t urContextGetInfo(
141143
}
142144

143145
ur_result_t urContextGetNativeHandle(
144-
ur_context_handle_t Context, ///< [in] handle of the context.
145-
ur_native_handle_t *NativeContext ///< [out] a pointer to the native
146-
///< handle of the context.
147-
) {
146+
/// [in] handle of the context.
147+
ur_context_handle_t Context,
148+
/// [out] a pointer to the native handle of the context.
149+
ur_native_handle_t *NativeContext) {
148150
*NativeContext = reinterpret_cast<ur_native_handle_t>(Context->ZeContext);
149151
return UR_RESULT_SUCCESS;
150152
}
151153

152154
ur_result_t urContextCreateWithNativeHandle(
153155
ur_native_handle_t
154-
NativeContext, ///< [in] the native handle of the context.
156+
/// [in] the native handle of the context.
157+
NativeContext,
155158
ur_adapter_handle_t, uint32_t NumDevices, const ur_device_handle_t *Devices,
156159
const ur_context_native_properties_t *Properties,
157-
ur_context_handle_t
158-
*Context ///< [out] pointer to the handle of the context object created.
159-
) {
160+
/// [out] pointer to the handle of the context object created.
161+
ur_context_handle_t *Context) {
160162
bool OwnNativeHandle = Properties->isNativeHandleOwned;
161163
try {
162164
ze_context_handle_t ZeContext =
@@ -174,12 +176,12 @@ ur_result_t urContextCreateWithNativeHandle(
174176
}
175177

176178
ur_result_t urContextSetExtendedDeleter(
177-
ur_context_handle_t Context, ///< [in] handle of the context.
178-
ur_context_extended_deleter_t
179-
Deleter, ///< [in] Function pointer to extended deleter.
180-
void *UserData ///< [in][out][optional] pointer to data to be passed to
181-
///< callback.
182-
) {
179+
/// [in] handle of the context.
180+
ur_context_handle_t Context,
181+
/// [in] Function pointer to extended deleter.
182+
ur_context_extended_deleter_t Deleter,
183+
/// [in][out][optional] pointer to data to be passed to callback.
184+
void *UserData) {
183185
std::ignore = Context;
184186
std::ignore = Deleter;
185187
std::ignore = UserData;

0 commit comments

Comments
 (0)