Difference between hipModule and hipLibrary

[rustic junco]

Hi all! Working on a HAL right now and trying to figure out what situations I would be trying to load a hipModule vs load a hipLibrary. Are these both device side? I'm looking at https://rocm.docs.amd.com/projects/HIP/en/latest/doxygen/html/group___module.html

[unique rose]

Hi @rustic junco
Both hipModule* and hipLibrary* APIs are host-side HIP runtime APIs. They are used to manage device code objects (kernels, globals, etc.), but they are not called from device code.

Roughly speaking:

• hipModule is the lower-level abstraction, very similar to CUDA’s driver API (cuModuleLoad, cuModuleGetFunction, cuModuleGetGlobal, …). You load a code object (HSACO / fatbin) into a hipModule_t and then fetch kernel or global symbols by name.
• hipLibrary is a higher-level kernel library abstraction. You load a library into a hipLibrary_t and can then enumerate kernels, query the kernel count, and retrieve kernel handles, etc. It’s more convenient when you want to treat a group of kernels as a single unit with metadata (names, count, enumeration).

In a HAL:
Use hipModule when you want a thin, CUDA-like driver-level abstraction for loading code objects and looking up functions/globals by name.
Use hipLibrary when you want to expose a “kernel library” concept (multiple kernels per library, enumeration, metadata, etc.) to the upper layers of your HAL.

In all cases, the APIs are executed on the host, but they manage code that runs on the device.

[rustic junco]

Hm, is this documented anywhere in the HIP docs? I'm not really finding anything that makes that distinction, so having something concrete for it to point to would help