## On this page

  

 

 # Macros and specifiers

 Last update: 17.07.2025 

[CUDA](glossary.xhtml#cuda) is the parallel computing platform used by Rocky to enable the execution of simulations on CUDA-enabled GPU cards. In order to work properly on GPU simulations, custom [modules](glossary.xhtml#module) must perform some basic operations of memory management on [devices](glossary.xhtml#device) and data transfer between CPU and GPU.

*Note: Although on GPU simulations most of the heavy operations are processed on GPU, there are many operations, such as setup, initialization and output, that are always performed on CPU*

This section describes a set of available CUDA-related macros that may be used for performing basic memory operations in the code when implementing custom modules. It is worth noting that they must be used only in the CUDA-related [hooks](glossary.xhtml#hook)\*, and only when modules are intended to be used on simulations running on GPU. In order to enable CUDA-related macros and hooks, the `.cu` file implementing the module functionalities must define the preprocessor macro name `ROCKY_CUDA_API`.

\*\*Currently, the CUDA-related hooks are four: `ROCKY_PLUGIN_INITIALIZE_CUDA`, `ROCKY_PLUGIN_BEGIN_ITERATION_CUDA`, `ROCKY_PLUGIN_PRE_OUTPUT_CUDA_SYNC_DATA`, and `ROCKY_PLUGIN_TEAR_DOWN_CUDA`.\*

## <a class="anchor" id="autotoc_md7"></a>CUDA\_MALLOC

This macro must be used to allocate a block of memory in a device for storing custom data. This allocation must be made before any copy operation of custom data to a device.

**Parameters:**

- `device_ptr`
    
    A pointer that after successful memory allocation will point to the memory address in a device at which the custom data will be stored. Prior to its utilization in the macro, this pointer must be a null pointer, otherwise a runtime error will be thrown.
- `size`
    
    An integer value that indicates the number of bytes that must be allocated in the device.

## <a class="anchor" id="autotoc_md8"></a>CUDA\_MALLOC\_TYPE

A variant of `CUDA_MALLOC` that, instead of receiving the number of bytes that must be allocated in the device, receives the type of data that will be stored and the number of elements as parameters, if it happens to be an array.

**Parameters:**

- `device_ptr`
    
    A pointer that after successful memory allocation will point to the memory address in a device at which the custom data will be stored. Prior to its utilization in the macro, this pointer must be a null pointer, otherwise a runtime error will be thrown.
- `count`
    
    An integer value that indicates the number of elements of the same type that will be stored in the allocated memory.
- `type`
    
    The type of variable that will be stored in the device, which can be a C++ built-in type or a custom data structure.

## <a class="anchor" id="autotoc_md9"></a>CUDA\_COPY\_H2D

This macro must be used to copy custom data from the [host](glossary.xhtml#host) to a device. Prior to this copy operation, the right amount of memory must have already been allocated within the device, otherwise a segmentation fault will occur.

*Note: The data type being copied must be trivially copyable otherwise a compilation error will raise.*

**Parameters:**

- `device_ptr`
    
    Destination memory address within a device.
- `host_ptr`
    
    Source memory address within the host.
- `count`
    
    An integer value that indicates the number of elements of the same type that will be copied.

## <a class="anchor" id="autotoc_md10"></a>CUDA\_COPY\_D2H

This macro performs the inverse operation of `CUDA_COPY_H2D`, that is, it copies data from the device back to the host. This operation may be needed when processed data must be made available to the host in order to be saved or delivered to the Rocky UI for visualization.

*Note: The data type being copied must be trivially copyable otherwise a compilation error will raise.*

**Parameters:**

- `host_ptr`
    
    Destination memory address within the host.
- `device_ptr`
    
    Source memory address within a device.
- `count`
    
    An integer value that indicates the number of elements of the same type that will be copied.

## <a class="anchor" id="autotoc_md11"></a>CUDA\_MEMSET

This macro sets a memory block within a device to a given value. It is commonly used to reset a block of memory that previously contained some data to zero.

**Parameters:**

- `device_ptr`
    
    Memory address within the device where the block begins.
- `value`
    
    The value to be defined for each byte within the memory block.
- `count`
    
    An integer value that indicates the number of elements of the same type that currently occupy the memory block.

## <a class="anchor" id="autotoc_md12"></a>CUDA\_FREE

This macro must be used to free the memory block allocated previously by `CUDA_MALLOC`.

**Parameters:**

- `device_ptr`
    
    Device pointer that points to the memory block that must be freed.

## <a class="anchor" id="autotoc_md13"></a>ROCKY\_FUNCTIONS

This is a function specifier that enables a function to be executed on CPU or on GPU. Its use is mandatory in the declaration of auxiliary functions that are intended to be called from hooks executed on GPU. This is the case for almost all hooks other than the initialization and termination hooks.