42

I'm starting to program with CUDA, and in some examples I find the include files cuda.h, cuda_runtime.h and cuda_runtime_api.h included in the code. Can someone explain to me the difference between these files?

einpoklum
  • 118,144
  • 57
  • 340
  • 684
Renan
  • 1,910
  • 4
  • 22
  • 36

2 Answers2

52

In very broad terms:

  • cuda.h defines the public host functions and types for the CUDA driver API.
  • cuda_runtime_api.h defines the public host functions and types for the CUDA runtime API
  • cuda_runtime.h defines everything cuda_runtime_api.h does, as well as built-in type definitions and function overlays for the CUDA language extensions and device intrinsic functions.

If you were writing host code to be compiled with the host compiler which includes API calls, you would include either cuda.h or cuda_runtime_api.h. If you needed other CUDA language built-ins, like types, and were using the runtime API and compiling with the host compiler, you would include cuda_runtime.h. If you are writing code which will be compiled using nvcc, it is all irrelevant, because nvcc takes care of inclusion of all the required headers automatically without programmer intervention.

einpoklum
  • 118,144
  • 57
  • 340
  • 684
talonmies
  • 70,661
  • 34
  • 192
  • 269
  • 3
    What! So you don't need to put includes in the .cu files if you compile with `nvcc` ? – Ander Biguri Jul 22 '15 at 13:12
  • 3
    Not for those particular include files, no. – talonmies Jul 22 '15 at 13:16
  • 1
    Just curious (I can open a new question if needed): Just for those? Exactly those? – Ander Biguri Jul 22 '15 at 13:17
  • 2
    I haven't checked recently exactly what the import chain in recent toolkits is. But it is certainly possible to use any of the CUDA supported types and the whole of the runtime and device runtime APIs without requiring explicit import calls. If you want to use device standard library or math library functions (printf, memset, malloc, memcpy, etc), those must be specifically imported – talonmies Jul 22 '15 at 13:36
  • FYI: only when the **nvcc** is compiling `.cu` code will it include all the headers automatically. – Shuai Dec 08 '21 at 04:54
6

A few observations in addition to @talonmies answer:

  • cuda_runtime.h includes cuda_runtime_api.h internally, but not the other way around. So: "runtime includes all of runtime_api" is a mnemonic to remember.
  • cuda_runtime_api.h does not have the entire runtime API functions you'll find in the official documentation, while cuda_runtime.h will have it all (example: cudaEventCreate()). However, all API calls defined cuda_runtime.h are actually implemented, in the header file itself, using calls to functions in cuda_runtime_api.h. These are the "function overlays" that @talonmies mentioned.
  • cuda_runtime_api.h is a C-language header (IIANM) with only C-language function declarations; cuda_runtime.h is a C++ header file, with some templated functions implemented.
einpoklum
  • 118,144
  • 57
  • 340
  • 684