diff --git a/extensions/cl_ext_device_side_abort.asciidoc b/extensions/cl_ext_device_side_abort.asciidoc new file mode 100644 index 00000000..9d29d8ab --- /dev/null +++ b/extensions/cl_ext_device_side_abort.asciidoc @@ -0,0 +1,125 @@ +cl_ext_device_side_abort +========================= + +// This section needs to be after the document title. +:doctype: book +:toc2: +:toc: left +:encoding: utf-8 +:lang: en +:blank: pass:[ +] +:data-uri: +:icons: font +include::../config/attribs.txt[] +:source-highlighter: coderay + +== Name Strings + ++cl_ext_device_side_abort+ + +== Contact + +Pekka Jääskeläinen, Parmance (pekka /at/ parmance /dot/ com) + +== Contributors + +Pekka Jääskeläinen, Parmance + +Henry Linjamäki, Parmance + +Brice Videau, Argonne National Laboratory + +== Notice + +Copyright (c) 2021-2022 Parmance and Argonne National Laboratory. + +== Status + +Draft + +== Version + +Built On: {docdate} + +Revision: 3 + +== Dependencies + +This extension is written against the OpenCL Specification Version 1.2, Revision 19. + +This extension requires OpenCL 1.2. + +== Overview + +With the device side abort extension, a work-item (WI) can return from the kernel +execution at any point and cause abnormal unrecoverable termination of the host +process. + +This extension differs from the cl_arm_controlled_kernel_termination extension +in that the abort in the device side is expected to behave like a call to the +POSIX abort() in the host side, terminating also the host process immediately. + +== New OpenCL C Types and Functions + +[source,c] +---- +void abort_platform(void); +---- + +== Modifications to the OpenCL C Specification + +=== Add a new Section 6.12.X - "Device-side invoked platform-wide program abort" + +A new function: :: ++ +-- + +[source,c] +---- +void abort_platform(void); +---- + +Stops the kernel execution and causes an abnormal unrecoverable termination of +the host process, thus causing abortion of execution of the whole program at +the platform level. + +Calling the device side abort also causes the printf buffer to be flushed on the +host program's standard output before aborting the host process. This allows to +implement device side assertion functionality by using the OpenCL C printf +function and this extension. + +The host should abort the process at latest when the kernel command that called +the function has finished execution, which means that all the WIs will +either call abort_platform() or return from the kernel command otherwise. + +The host process is expected to call the standard abort function of the host +operating system. In POSIX/C99-compliant systems, this must be implemented by +a call to abort() which implies that the SIGABRT signal is raised and can be +caught by defining a signal handler. This means that a minimal implementation +of a device-side abort with a CPU device can simply call the standard abort() +directly to implement compliant behavior. + +The results of an aborted kernel command are undefined. Device side abort is +guaranteed to stop the kernel command as soon as possible, even in the presence +of deadlocks or partially reached barriers in the kernel command. + +The control flow behavior within the work-group of a kernel command with +a WI that called the device side abort is the same as immediately +returning from the kernel for the abort-calling WI at the abort call site. +For possible WIs that do not call abort, the return time is undefined and can +adhere to the original control flow of the kernel as long as all the WIs +eventually finish the execution and allow the host runtime to abort the +process also in a single-threaded/non-interrupting implementation. + +-- + +== Version History + +[cols="5,15,15,70"] +[grid="rows"] +[options="header"] +|==== +| Version | Date | Author | Changes +| 3 | 2022-05-14 | Pekka Jääskeläinen, Brice Videau | +*Changed to an 'ext' extension to promote multi-vendor adoption.* +| 2 | 2022-04-25 | Pekka Jääskeläinen, Brice Videau, Henry Linjamäki | +State explicitly that a compliant CPU device implementation can call abort() directly. Clarified the control flow behavior. +| 1 | 2022-04-08 | Pekka Jääskeläinen | *Initial revision for comments* +|==== diff --git a/extensions/cl_ext_device_side_abort.html b/extensions/cl_ext_device_side_abort.html new file mode 100644 index 00000000..9f3968f1 --- /dev/null +++ b/extensions/cl_ext_device_side_abort.html @@ -0,0 +1,641 @@ + + + + + + + +cl_ext_device_side_abort + + + + + +
+
+

Name Strings

+
+
+

cl_ext_device_side_abort

+
+
+
+
+

Contact

+
+
+

Pekka Jääskeläinen, Parmance (pekka /at/ parmance /dot/ com)

+
+
+
+
+

Contributors

+
+
+

Pekka Jääskeläinen, Parmance
+Henry Linjamäki, Parmance
+Brice Videau, Argonne National Laboratory

+
+
+
+
+

Notice

+
+
+

Copyright (c) 2021-2022 Parmance and Argonne National Laboratory.

+
+
+
+
+

Status

+
+
+

Draft

+
+
+
+
+

Version

+
+
+

Built On: 2022-05-14
+Revision: 3

+
+
+
+
+

Dependencies

+
+
+

This extension is written against the OpenCL Specification Version 1.2, Revision 19.

+
+
+

This extension requires OpenCL 1.2.

+
+
+
+
+

Overview

+
+
+

With the device side abort extension, a work-item (WI) can return from the kernel +execution at any point and cause abnormal unrecoverable termination of the host +process.

+
+
+

This extension differs from the cl_arm_controlled_kernel_termination extension +in that the abort in the device side is expected to behave like a call to the +POSIX abort() in the host side, terminating also the host process immediately.

+
+
+
+
+

New OpenCL C Types and Functions

+
+
+
+
void abort_platform(void);
+
+
+
+
+
+

Modifications to the OpenCL C Specification

+
+
+

Add a new Section 6.12.X - "Device-side invoked platform-wide program abort"

+
+
+
A new function:
+
+
+
+
+
+
void abort_platform(void);
+
+
+
+

Stops the kernel execution and causes an abnormal unrecoverable termination of +the host process, thus causing abortion of execution of the whole program at +the platform level.

+
+
+

Calling the device side abort also causes the printf buffer to be flushed on the +host program’s standard output before aborting the host process. This allows to +implement device side assertion functionality by using the OpenCL C printf +function and this extension.

+
+
+

The host should abort the process at latest when the kernel command that called +the function has finished execution, which means that all the WIs will +either call abort_platform() or return from the kernel command otherwise.

+
+
+

The host process is expected to call the standard abort function of the host +operating system. In POSIX/C99-compliant systems, this must be implemented by +a call to abort() which implies that the SIGABRT signal is raised and can be +caught by defining a signal handler. This means that a minimal implementation +of a device-side abort with a CPU device can simply call the standard abort() +directly to implement compliant behavior.

+
+
+

The results of an aborted kernel command are undefined. Device side abort is +guaranteed to stop the kernel command as soon as possible, even in the presence +of deadlocks or partially reached barriers in the kernel command.

+
+
+

The control flow behavior within the work-group of a kernel command with +a WI that called the device side abort is the same as immediately +returning from the kernel for the abort-calling WI at the abort call site. +For possible WIs that do not call abort, the return time is undefined and can +adhere to the original control flow of the kernel as long as all the WIs +eventually finish the execution and allow the host runtime to abort the +process also in a single-threaded/non-interrupting implementation.

+
+
+
+
+
+
+
+
+
+
+

Version History

+
+ ++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
VersionDateAuthorChanges

3

2022-05-14

Pekka Jääskeläinen, Brice Videau

Changed to an ext extension to promote multi-vendor adoption.

2

2022-04-25

Pekka Jääskeläinen, Brice Videau, Henry Linjamäki

State explicitly that a compliant CPU device implementation can call abort() directly. Clarified the control flow behavior.

1

2022-04-08

Pekka Jääskeläinen

Initial revision for comments

+
+
+
+ + + \ No newline at end of file