ROCm Linux Filesystem Hierarchy Standard reorganization — ROCm Documentation (2024)

Introduction#

The ROCm Software has adopted the Linux Filesystem Hierarchy Standard (FHS) https://refspecs.linuxfoundation.org/FHS_3.0/fhs/index.html in order to to ensure ROCm is consistent with standard open source conventions. The following sections specify how current and future releases of ROCm adhere to FHS, how the previous ROCm file system is supported, and how improved versioning specifications are applied to ROCm.

Adopting the FHS#

In order to standardize ROCm directory structure and directory content layout ROCm has adopted the FHS, adhering to open source conventions for Linux-based distribution. FHS ensures internal consistency within the ROCm stack, as well as external consistency with other systems and distributions. The ROCm proposed file structure is outlined below:

/opt/rocm-<ver> | -- bin | -- all public binaries | -- lib | -- lib<soname>.so->lib<soname>.so.major->lib<soname>.so.major.minor.patch (public libaries to link with applications) | -- <component> | -- architecture dependent libraries and binaries used internally by components | -- cmake | -- <component> | --<component>-config.cmake | -- libexec | -- <component> | -- non ISA/architecture independent executables used internally by components | -- include | -- <component> | -- public header files | -- share | -- html | -- <component> | -- html documentation | -- info | -- <component> | -- info files | -- man | -- <component> | -- man pages | -- doc | -- <component> | -- license files | -- <component> | -- samples | -- architecture independent misc files

Changes from earlier ROCm versions#

The following table provides a brief overview of the new ROCm FHS layout, compared to the layout of earlier ROCm versions. Note that /opt/ is used to denote the default rocm-installation-path and should be replaced in case of a non-standard installation location of the ROCm distribution.

 ______________________________________________________| New ROCm Layout | Previous ROCm Layout ||_____________________________|________________________|| /opt/rocm-<ver> | /opt/rocm-<ver> || | -- bin | | -- bin || | -- lib | | -- lib || | -- cmake | | -- include || | -- libexec | | -- <component_1> || | -- include | | -- bin || | -- <component_1> | | -- cmake || | -- share | | -- doc || | -- html | | -- lib || | -- info | | -- include || | -- man | | -- samples || | -- doc | | -- <component_n> || | -- <component_1> | | -- bin || | -- samples | | -- cmake || | -- .. | | -- doc || | -- <component_n> | | -- lib || | -- samples | | -- include || | -- .. | | -- samples ||______________________________________________________|

ROCm FHS reorganization: backward compatibility#

The FHS file organization for ROCm was first introduced in the release of ROCm 5.2 . Backward compatibility was implemented to make sure users could still run their ROCm applications while transitioning to the new FHS. ROCm has moved header files and libraries to their new locations as indicated in the above structure, and included symbolic-links and wrapper header files in their old location for backward compatibility. The following sections detail ROCm backward compatibility implementation for wrapper header files, executable files, library files and CMake config files.

#pragma message "This file is deprecated. Use file from include path /opt/rocm-ver/include/ and prefix with hip."#include <hip/hip_runtime.h>

$ ls -l /opt/rocm/hip/bin/lrwxrwxrwx 1 root root 24 Jan 1 23:32 hipcc -> ../../bin/hipcc

$ ls -l /opt/rocm/hip/lib/drwxr-xr-x 4 root root 4096 Jan 1 10:45 cmakelrwxrwxrwx 1 root root 24 Jan 1 23:32 libamdhip64.so -> ../../lib/libamdhip64.so

$ ls -l /opt/rocm/hip/lib/cmake/hip/lrwxrwxrwx 1 root root 42 Jan 1 23:32 hip-config.cmake -> ../../../../lib/cmake/hip/hip-config.cmake

Changes required in applications using ROCm#

Applications using ROCm are advised to use the new file paths. As the old fileswill be deprecated in a future release. Applications have to make sure to includecorrect header file and use correct search paths.

1. #include<header_file.h> needs to be changed to#include <component/header_file.h>

   For example: #include <hip.h> needs to changeto #include <hip/hip.h>

2. Any variable in CMake or Makefiles pointing to component folder needs tochanged.

   For example: VAR1=/opt/rocm/hip needs to be changed to VAR1=/opt/rocmVAR2=/opt/rocm/hsa needs to be changed to VAR2=/opt/rocm

3. Any reference to /opt/rocm/<component>/bin or /opt/rocm/<component>/libneeds to be changed to /opt/rocm/bin and /opt/rocm/lib/, respectively.

Changes in versioning specifications#

In order to better manage ROCm dependencies specification and allow smoother releases of ROCm while avoiding dependency conflicts, ROCm software shall adhere to the following scheme when numbering and incrementing ROCm files versions:

rocm-<ver>, where <ver> = <x.y.z>

x.y.z denote: MAJOR.MINOR.PATCH

z: PATCH - increment z when implementing backward compatible bug fixes.

y: MINOR - increment y when implementing minor changes that add functionality but are still backward compatible.

x: MAJOR - increment x when implementing major changes that are not backward compatible.