c-extensions.texi 9.1 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288
  1. @c -*-texinfo-*-
  2. @c This file is part of the StarPU Handbook.
  3. @c Copyright (C) 2011 Institut National de Recherche en Informatique et Automatique
  4. @c See the file starpu.texi for copying conditions.
  5. @node C Extensions
  6. @chapter C Extensions
  7. @cindex C extensions
  8. @cindex GCC plug-in
  9. When configured with @code{--enable-gcc-extensions}, StarPU builds a
  10. plug-in for the GNU Compiler Collection (GCC), which defines extensions
  11. to languages of the C family (C, C++, Objective-C) that make it easier
  12. to write StarPU code@footnote{This feature is only available for GCC 4.5
  13. and later.}. Those extensions include syntactic sugar for defining
  14. tasks and their implementations, invoking a task, and manipulating data
  15. buffers. Use of these extensions can be made conditional on the
  16. availability of the plug-in, leading to valid C sequential code when the
  17. plug-in is not used (@pxref{Conditional Extensions}).
  18. This section does not require detailed knowledge of the StarPU library.
  19. Note: as of StarPU @value{VERSION}, this is still an area under
  20. development and subject to change.
  21. @menu
  22. * Defining Tasks:: Defining StarPU tasks
  23. * Registered Data Buffers:: Manipulating data buffers
  24. * Conditional Extensions:: Using C extensions only when available
  25. @end menu
  26. @node Defining Tasks
  27. @section Defining Tasks
  28. @cindex task
  29. @cindex task implementation
  30. The StarPU GCC plug-in views @dfn{tasks} as ``extended'' C functions:
  31. @enumerate
  32. @item
  33. tasks may have several implementations---e.g., one for CPUs, one written
  34. in OpenCL, one written in CUDA;
  35. @item
  36. tasks may have several implementations of the same target---e.g.,
  37. several CPU implementations;
  38. @item
  39. when a task is invoked, it may run in parallel, and StarPU is free to
  40. choose any of its implementations.
  41. @end enumerate
  42. Tasks and their implementations must be @emph{declared}. These
  43. declarations are annotated with @dfn{attributes} (@pxref{Attribute
  44. Syntax, attributes in GNU C,, gcc, Using the GNU Compiler Collection
  45. (GCC)}): the declaration of a task is a regular C function declaration
  46. with an additional @code{task} attribute, and task implementations are
  47. declared with a @code{task_implementation} attribute.
  48. The following function attributes are provided:
  49. @table @code
  50. @item task
  51. @cindex @code{task} attribute
  52. Declare the given function as a StarPU task. Its return type must be
  53. @code{void}, and it must not be defined---instead, a definition will
  54. automatically be provided by the compiler.
  55. Under the hood, declaring a task leads to the declaration of the
  56. corresponding @code{codelet} (@pxref{Codelet and Tasks}). If one or
  57. more task implementations are declared in the same compilation unit,
  58. then the codelet and the function itself are also defined; they inherit
  59. the scope of the task.
  60. Scalar arguments to the task are passed by value and copied to the
  61. target device if need be---technically, they are passed as the
  62. @code{cl_arg} buffer (@pxref{Codelets and Tasks, @code{cl_arg}}).
  63. Pointer arguments are assumed to be registered data buffers---the
  64. @code{buffers} argument of a task (@pxref{Codelets and Tasks,
  65. @code{buffers}}); @code{const}-qualified pointer arguments are viewed as
  66. read-only buffers (@code{STARPU_R}), and non-@code{const}-qualified
  67. buffers are assumed to be used read-write (@code{STARPU_RW}).
  68. @item task_implementation (@var{target}, @var{task})
  69. @cindex @code{task_implementation} attribute
  70. Declare the given function as an implementation of @var{task} to run on
  71. @var{target}. @var{target} must be a string, currently one of
  72. @code{"cpu"} or @code{"cuda"}.
  73. @c FIXME: Update when OpenCL support is ready.
  74. @end table
  75. Here is an example:
  76. @example
  77. static void matmul (const float *A, const float *B, float *C,
  78. size_t nx, size_t ny, size_t nz)
  79. __attribute__ ((task));
  80. static void matmul_cpu (const float *A, const float *B, float *C,
  81. size_t nx, size_t ny, size_t nz)
  82. __attribute__ ((task_implementation ("cpu", matmul)));
  83. static void
  84. matmul_cpu (const float *A, const float *B, float *C,
  85. size_t nx, size_t ny, size_t nz)
  86. @{
  87. size_t i, j, k;
  88. for (j = 0; j < ny; j++)
  89. for (i = 0; i < nx; i++)
  90. @{
  91. for (k = 0; k < nz; k++)
  92. C[j * nx + i] += A[j * nz + k] * B[k * nx + i];
  93. @}
  94. @}
  95. @end example
  96. @noindent
  97. A @code{matmult} task is defined; it has only one implementation,
  98. @code{matmult_cpu}, which runs on the CPU. Variables @var{A} and
  99. @var{B} are input buffers, whereas @var{C} is considered an input/output
  100. buffer.
  101. CUDA and OpenCL implementations can be declared in a similar way:
  102. @example
  103. static void matmul_cuda (const float *A, const float *B, float *C,
  104. size_t nx, size_t ny, size_t nz)
  105. __attribute__ ((task_implementation ("cuda", matmul)));
  106. static void matmul_opencl (const float *A, const float *B, float *C,
  107. size_t nx, size_t ny, size_t nz)
  108. __attribute__ ((task_implementation ("opencl", matmul)));
  109. @end example
  110. @noindent
  111. The CUDA and OpenCL implementations typically either invoke a kernel
  112. written in CUDA or OpenCL (for similar code, @pxref{CUDA Kernel}, and
  113. @pxref{OpenCL Kernel}), or call a library function that uses CUDA or
  114. OpenCL under the hood, such as CUBLAS functions:
  115. @example
  116. static void
  117. matmul_cuda (const float *A, const float *B, float *C,
  118. size_t nx, size_t ny, size_t nz)
  119. @{
  120. cublasSgemm ('n', 'n', nx, ny, nz,
  121. 1.0f, A, 0, B, 0,
  122. 0.0f, C, 0);
  123. cudaStreamSynchronize (starpu_cuda_get_local_stream ());
  124. @}
  125. @end example
  126. A task can be invoked like a regular C function:
  127. @example
  128. matmul (&A[i * zdim * bydim + k * bzdim * bydim],
  129. &B[k * xdim * bzdim + j * bxdim * bzdim],
  130. &C[i * xdim * bydim + j * bxdim * bydim],
  131. bxdim, bydim, bzdim);
  132. @end example
  133. @noindent
  134. This leads to an @dfn{asynchronous invocation}, whereby @code{matmult}'s
  135. implementation may run in parallel with the continuation of the caller.
  136. The next section describes how memory buffers must be handled in
  137. StarPU-GCC code.
  138. @node Registered Data Buffers
  139. @section Registered Data Buffers
  140. Data buffers such as matrices and vectors that are to be passed to tasks
  141. must be @dfn{registered}. Registration allows StarPU to handle data
  142. transfers among devices---e.g., transferring an input buffer from the
  143. CPU's main memory to a task scheduled to run a GPU (@pxref{StarPU Data
  144. Management Library}).
  145. The following pragmas are provided:
  146. @table @code
  147. @item #pragma starpu register @var{ptr} [@var{size}]
  148. Register @var{ptr} as a @var{size}-element buffer.
  149. @item #pragma starpu unregister @var{ptr}
  150. @item #pragma starpu acquire @var{ptr}
  151. @end table
  152. FIXME: finish
  153. @node Conditional Extensions
  154. @section Using C Extensions Conditionally
  155. The C extensions described in this chapter are only available when GCC
  156. and its StarPU plug-in are in use. Yet, it is possible to make use of
  157. these extensions when they are available---leading to hybrid CPU/GPU
  158. code---and discard them when they are not available---leading to valid
  159. sequential code.
  160. To that end, the GCC plug-in defines a C preprocessor macro when it is
  161. being used:
  162. @defmac STARPU_GCC_PLUGIN
  163. Defined for code being compiled with the StarPU GCC plug-in. When
  164. defined, this macro expands to an integer denoting the version of the
  165. supported C extensions.
  166. @end defmac
  167. The code below illustrates how to define a task and its implementations
  168. in a way that allows it to be compiled without the GCC plug-in:
  169. @example
  170. /* The macros below abstract over the attributes specific to
  171. StarPU-GCC and the name of the CPU implementation. */
  172. #ifdef STARPU_GCC_PLUGIN
  173. # define __task __attribute__ ((task))
  174. # define CPU_TASK_IMPL(task) task ## _cpu
  175. #else
  176. # define __task
  177. # define CPU_TASK_IMPL(task) task
  178. #endif
  179. #include <stdlib.h>
  180. static void matmul (const float *A, const float *B, float *C,
  181. size_t nx, size_t ny, size_t nz) __task;
  182. #ifdef STARPU_GCC_PLUGIN
  183. static void matmul_cpu (const float *A, const float *B, float *C,
  184. size_t nx, size_t ny, size_t nz)
  185. __attribute__ ((task_implementation ("cpu", matmul)));
  186. #endif
  187. static void
  188. CPU_TASK_IMPL (matmul) (const float *A, const float *B, float *C,
  189. size_t nx, size_t ny, size_t nz)
  190. @{
  191. /* Code of the CPU kernel here... */
  192. @}
  193. int
  194. main (int argc, char *argv[])
  195. @{
  196. /* The pragmas below are simply ignored when StarPU-GCC
  197. is not used. */
  198. #pragma starpu initialize
  199. float A[123][42][7], B[123][42][7], C[123][42][7];
  200. #pragma starpu register A
  201. #pragma starpu register B
  202. #pragma starpu register C
  203. /* When StarPU-GCC is used, the call below is asynchronous;
  204. otherwise, it is synchronous. */
  205. matmul (A, B, C, 123, 42, 7);
  206. #pragma starpu wait
  207. #pragma starpu shutdown
  208. return EXIT_SUCCESS;
  209. @}
  210. @end example
  211. Note that attributes such as @code{task} are simply ignored by GCC when
  212. the StarPU plug-in is not loaded, so the @code{__task} macro could be
  213. omitted altogether. However, @command{gcc -Wall} emits a warning for
  214. unknown attributes, which can be inconvenient, and other compilers may
  215. be unable to parse the attribute syntax. Thus, using macros such as
  216. @code{__task} above is recommended.
  217. @c Local Variables:
  218. @c TeX-master: "../starpu.texi"
  219. @c ispell-local-dictionary: "american"
  220. @c End: