liveBook · Manning

cudaMemcpyToSymbol

As explained in Grokking GPU Programming

cudaMemcpyToSymbol is a CUDA runtime API function that copies data to a named device symbol.

When a GPU kernel needs a shared read-only value, cudaMemcpyToSymbol copies data into a named device variable. A common use is loading a __constant__ variable before launching a kernel: declare the variable, copy its value, then read it directly in the kernel. section 13.4

The basic call is cudaMemcpyToSymbol(symbol, source, size). Give the symbol name directly, without & or *. The source is a pointer: use &h_scale for a scalar, or an array name such as h_filter for an array. The size is the number of bytes to copy. Host-to-device is the default direction. section 13.4

float h_scale = 2.5f;
cudaMemcpyToSymbol(scaleFactor, &h_scale, sizeof(float));
 
float h_filter[25] = { /* Gaussian values */ };
cudaMemcpyToSymbol(filter, h_filter, sizeof(float) * 25);

These scalar and array copies show how the source pointer differs while the destination remains a symbol name. section 13.4

The copy is synchronous: it blocks the CPU until it finishes. In the default-stream setup, it also waits for preceding GPU operations before copying. A constant value stays available across kernel launches until it is overwritten, so it need not be copied again for every launch. section 13.4

Scale an array

Declare a constant scale factor and copy 2.5 into it once. A kernel can then multiply [1.0, 2.0, 3.0, 4.0] to produce [2.5, 5.0, 7.5, 10.0]. Each thread reads the same factor, allowing a constant-cache broadcast. For just one scalar, a kernel argument is usually the simpler choice unless persistence or an addressable symbol is useful. section 13.8 section 13.11

The full argument form is cudaMemcpyToSymbol(symbol, src, count, offset = 0, kind = cudaMemcpyHostToDevice). Use a byte offset to update part of a symbol; specify cudaMemcpyDeviceToDevice as the kind to copy from device memory instead. section 13.14

__constant__ float params[7];    #A
 
cudaMemcpyToSymbol(params, h_all, sizeof(float) * 7);    #B
 
size_t offset = 4 * sizeof(float);    #C
cudaMemcpyToSymbol(params, h_newLighting, sizeof(float) * 3, offset);    #D

After copying seven floats at startup, this example updates only the last three by skipping four floats in the destination. section 13.14

A common mistake is using ordinary cudaMemcpy with a __constant__ symbol. That call expects a device pointer such as one returned by cudaMalloc, not the symbol name. It can report an invalid-argument error, leaving the kernel to read stale values. Use cudaMemcpyToSymbol and check its return status. Also, plain const does not place data in constant memory; declare the device variable with __constant__. section 13.14 section 13.15

How Grokking GPU Programming covers it

How deep it goes
Explains arguments, source pointers, defaults, partial updates, synchronous behavior, and the wrong-copy-function failure.
Examples
Uses scalar and array copies, an array-scaling kernel, and a partial update of lighting values.
What you can do after
Apply it via the CUDA runtime to load or partially update a device symbol and recognize an incorrect cudaMemcpy call.
How it connects
Connects constant memory with kernel launches, device pointers, cache broadcast, and kernel arguments.

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Grokking GPU Programming. The section links point to the parts of the book it draws on.