clarify library search order rule.

contrib/hipew/src/hipew.cpp

@@ -614,13 +614,22 @@ static int hipewHasOldDriver(const char *hip_path) {
 void hipewInit( int* resultDriver, int* resultRtc, uint32_t flags, const char** customPaths_Hip, const char** customPaths_Hiprtc )
 {
 
-  // Library paths.
-  // All those fixed paths can be overridden by the arguments of hipewInit/oroInitialize
+  // Search existing HIP libraries.
+  // A general rule is that we search in descending order, starting with the most recent versions.
+  //
+  // The HIP libraries are backward compatible, examples:
+  // - If you are using the 5.7 HIP API, then any library above 5.7 (like 6.0) should be able to run your program correctly.
+  // - However, if you use the 6.0 HIP API, then loading older library (like 5.7) will fail to run API that has been introduced in HIP 6.0.
+  // 
+  // All those fixed paths search can be overridden by the arguments of hipewInit/oroInitialize.
+  // This is important to keep in mind as depending on your project you may want to search in custom order.
+  //
+
 #ifdef _WIN32
   // Expected in C:/Windows/System32 or similar, no path needed.
   const char* hip_paths[] = {
+      "amdhip64_6.dll", 
       "amdhip64.dll",   // <- hip '5.x' DLL.
-      "amdhip64_6.dll", // <- if the hip 5 doesn't exist, try the hip '6.x' DLL. This newer DLL will be able to run HIP 5 code.
       NULL };
   const char* hiprtc_paths[] = {
       "hiprtc0605.dll",
@@ -642,7 +651,7 @@ void hipewInit( int* resultDriver, int* resultRtc, uint32_t flags, const char**
 #else
   const char *hip_paths[] = { 
 
-      // we first try the specific '5.x' or '6.x' version
+      // we first try the specific versions
       "/opt/rocm/hip/lib/libamdhip64.so.6",
       "/opt/rocm/lib/libamdhip64.so.6", 
       "libamdhip64.so.6",
@@ -652,7 +661,6 @@ void hipewInit( int* resultDriver, int* resultRtc, uint32_t flags, const char**
       "libamdhip64.so.5",
 
       // .. if it doesn't exist, we take the generic symbolic link.
-      // if it links to any version above 5, it will be able to run HIP 5 code.
       "/opt/rocm/hip/lib/libamdhip64.so",
       "/opt/rocm/lib/libamdhip64.so", 
       "libamdhip64.so",
@@ -661,7 +669,7 @@ void hipewInit( int* resultDriver, int* resultRtc, uint32_t flags, const char**
 
   const char* hiprtc_paths[] = { 
 
-      // we first try the specific '5.x' or '6.x' version
+      // we first try the specific versions
       "/opt/rocm/hip/lib/libhiprtc.so.6",
       "/opt/rocm/lib/libhiprtc.so.6", 
       "libhiprtc.so.6",
@@ -671,7 +679,6 @@ void hipewInit( int* resultDriver, int* resultRtc, uint32_t flags, const char**
       "libhiprtc.so.5",
 
       // .. if it doesn't exist, we take the generic symbolic link.
-      // if it links to any version above 5, it will be able to run HIP 5 code.
       "/opt/rocm/hip/lib/libhiprtc.so",
       "/opt/rocm/lib/libhiprtc.so", 
       "libhiprtc.so",