intel / intel/opencl-intercept-layer

In API Trace Syntactic Consistency

Open
#28 6 comments 0 reactions 1 assignee Claimed by @trbauer View on GitHub
enhancement
Dominant language
C++
Stars
369
Forks
90
Avg merge
15h 13m
Merged PRs (30d)
10

Description

## Observed Behavior

For example clGetPlatformIDs omits arguments and uses `,` separator instead of `:` like all other API calls

>>>> clGetPlatformIDs, EnqueueCounter: 1
^ uses comma
Host Time for call 1: clGetPlatformIDs = 1114623933
<<<< clGetPlatformIDs
....
>>>> clGetDeviceIDs: platform = [ Intel(R) OpenCL ], device_type = CL_DEVICE_TYPE_GPU (4), EnqueueCounter: 1
Host Time for call 3: clGetDeviceIDs = 292
<<<< clGetDeviceIDs

Probably the `,` belongs to the `EnqueueCounter` suffix,

1. Another way to view this is `clGetPlatformIDs` omits its arguments.
2. Perhaps suggest we should change the API trace to a more consistent syntax so that it's more consumable by tools? See below for a suggestion.

## Desired Behavior

Perhaps we could use a syntax like the following.

::=
::= anything but '<<<<'
::= '>>>>' ? ':'
::= '<<<<' ? ' returned ' (':' )?
::= ' = ' (',' ' = ' )|
:: ':' // values returned via pointer or return value
::= | ';'
::= |
= | '{' (',' )* '}' // structs for things like float4's
= '[' ']' // means the value returned is indirect

This would give us.

>>>> clGetPlatformIds: num_entries = 10, platforms = [0x12345...], num_platforms = [0x22345...]; EnqueueCounter:1
....
<<<< clGetPlatformIds returned CL_SUCCESS: platforms[] = {...platform_id's...}, *num_platforms = 2
// note the return by ptr values are decoded to a minimal extent using API domain specific knowledge (e.g. num_platforms is a single int)

Note, I am not tied to the exact syntax, but am just proposing something consistent for tool consumability. Probably there are a lot of improvements we could apply to the above.

Regarding API's that return a pointer (e.g. `clCreateProgram`) and return the status via pointer, we _might_ consider untangling them logically to always present the cl_int (status) as the "returned" value and the new object allocated (e.g. program) as a pseudo argument like `new_program`. Or we just leave it alone and decode the status as a regular "return by pointer" argument (but decode it). I see benefits either way.

## Steps to Reproduce

Enable the API trace (with enqueue counters) and observe `clintercept_report.txt` calls.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.