Skip to main content
`Ctrl`+`K`

# rocSOLVER library and logging functions

These are helper functions that retrieve information and control some functions of the library. The helper functions are divided into the following categories:

- Library information: Return information about the library version.

- Algorithm selection: Select different algorithm modes of certain APIs.

- Logging functions: Control the rocSOLVER multi-level logging capabilities.

## Library information

### rocsolver_get_version_string()

rocblas_status rocsolver_get_version_string(char *buf, size_t len)

  GET_VERSION_STRING Queries the library version.

  Parameters:

    - buf – [out] A buffer that the version string will be written into.

    - len – [in] The size of the given buffer in bytes.

### rocsolver_get_version_string_size()

rocblas_status rocsolver_get_version_string_size(size_t *len)

  GET_VERSION_STRING_SIZE Queries the minimum buffer size for a successful call to rocsolver_get_version_string.

  Parameters:

    len – [out] pointer to size_t. The minimum length of buffer to pass to rocsolver_get_version_string.

## Algorithm selection

### rocsolver_set_alg_mode()

rocblas_status rocsolver_set_alg_mode(rocblas_handle handle, const rocsolver_function func, const rocsolver_alg_mode mode)

  SET_ALG_MODE sets the algorithm mode to be used by the specified function.

  Parameters:

    - handle – [in] rocblas_handle.

    - func – [in] rocsolver_function. The function that will use the selected algorithm mode.

    - mode – [in] rocsolver_alg_mode. The algorithm mode that will be used by the specified function. rocsolver_alg_mode_mixed is not supported.

### rocsolver_get_alg_mode()

rocblas_status rocsolver_get_alg_mode(rocblas_handle handle, const rocsolver_function func, rocsolver_alg_mode *mode)

  GET_ALG_MODE gets the algorithm mode being used by the specified function.

  Parameters:

    - handle – [in] rocblas_handle.

    - func – [in] rocsolver_function. The specified function.

    - mode – [out] pointer to rocsolver_alg_mode. On exit, the value is overwritten by the algorithm mode used by the specified function.

## Logging functions

### rocsolver_log_begin()

rocblas_status rocsolver_log_begin(void)

  LOG_BEGIN begins a rocSOLVER multi-level logging session.

  Initializes the rocSOLVER logging environment with default values (no logging and one level depth). Default mode can be overridden by using the environment variables ROCSOLVER_LAYER and ROCSOLVER_LEVELS.

  This function also sets the streams where the log results will be outputted. The default is STDERR for all the modes. This default can also be overridden using the environment variable ROCSOLVER_LOG_PATH, or specifically ROCSOLVER_LOG_TRACE_PATH, ROCSOLVER_LOG_BENCH_PATH, and/or ROCSOLVER_LOG_PROFILE_PATH.

### rocsolver_log_end()

rocblas_status rocsolver_log_end(void)

  LOG_END ends the multi-level rocSOLVER logging session.

  If applicable, this function also prints the profile logging results before cleaning the logging environment.

### rocsolver_log_set_layer_mode()

rocblas_status rocsolver_log_set_layer_mode(const rocblas_layer_mode_flags layer_mode)

  LOG_SET_LAYER_MODE sets the logging mode for the rocSOLVER multi-level logging environment.

  Parameters:

    layer_mode – [in] rocblas_layer_mode_flags. Specifies the logging mode.

### rocsolver_log_set_max_levels()

rocblas_status rocsolver_log_set_max_levels(const rocblas_int max_levels)

  LOG_SET_MAX_LEVELS sets the maximum trace log depth for the rocSOLVER multi-level logging environment.

  Parameters:

    max_levels – [in] rocblas_int. max_levels >= 1. Specifies the maximum depth at which nested function calls will appear in the trace and profile logs.

### rocsolver_log_restore_defaults()

rocblas_status rocsolver_log_restore_defaults(void)

  LOG_RESTORE_DEFAULTS restores the default values of the rocSOLVER multi-level logging environment.

  This function sets the logging mode and maximum trace log depth to their default values (no logging and one level depth).

### rocsolver_log_write_profile()

rocblas_status rocsolver_log_write_profile(void)

  LOG_WRITE_PROFILE prints the profile logging results.

### rocsolver_log_flush_profile()

rocblas_status rocsolver_log_flush_profile(void)

  LOG_FLUSH_PROFILE prints the profile logging results and clears the profile record.