IO helpers: clarify that some IO helpers return 0 on success and -1 on error

bgoglin · bgoglin · commit 8c49593311fa · 2023-04-27T14:04:53.000+02:00
Refs #578 Signed-off-by: Brice Goglin <Brice.Goglin@inria.fr>
diff --git a/include/hwloc/cuda.h b/include/hwloc/cuda.h
@@ -1,5 +1,5 @@
 /*
- * Copyright © 2010-2021 Inria.  All rights reserved.
+ * Copyright © 2010-2023 Inria.  All rights reserved.
  * Copyright © 2010-2011 Université Bordeaux
  * Copyright © 2011 Cisco Systems, Inc.  All rights reserved.
  * See COPYING in top-level directory.
@@ -42,6 +42,9 @@ extern "C" {
 /** \brief Return the domain, bus and device IDs of the CUDA device \p cudevice.
  *
  * Device \p cudevice must match the local machine.
+ *
+ * \return 0 on success.
+ * \return -1 on error, for instance if device information could not be found.
  */
 static __hwloc_inline int
 hwloc_cuda_get_device_pci_ids(hwloc_topology_t topology __hwloc_attribute_unused,
@@ -87,6 +90,9 @@ hwloc_cuda_get_device_pci_ids(hwloc_topology_t topology __hwloc_attribute_unused
  *
  * This function is currently only implemented in a meaningful way for
  * Linux; other systems will simply get a full cpuset.
+ *
+ * \return 0 on success.
+ * \return -1 on error, for instance if device information could not be found.
  */
 static __hwloc_inline int
 hwloc_cuda_get_device_cpuset(hwloc_topology_t topology __hwloc_attribute_unused,
diff --git a/include/hwloc/cudart.h b/include/hwloc/cudart.h
@@ -1,5 +1,5 @@
 /*
- * Copyright © 2010-2021 Inria.  All rights reserved.
+ * Copyright © 2010-2023 Inria.  All rights reserved.
  * Copyright © 2010-2011 Université Bordeaux
  * Copyright © 2011 Cisco Systems, Inc.  All rights reserved.
  * See COPYING in top-level directory.
@@ -43,6 +43,9 @@ extern "C" {
 /** \brief Return the domain, bus and device IDs of the CUDA device whose index is \p idx.
  *
  * Device index \p idx must match the local machine.
+ *
+ * \return 0 on success.
+ * \return -1 on error, for instance if device information could not be found.
  */
 static __hwloc_inline int
 hwloc_cudart_get_device_pci_ids(hwloc_topology_t topology __hwloc_attribute_unused,
@@ -84,6 +87,9 @@ hwloc_cudart_get_device_pci_ids(hwloc_topology_t topology __hwloc_attribute_unus
  *
  * This function is currently only implemented in a meaningful way for
  * Linux; other systems will simply get a full cpuset.
+ *
+ * \return 0 on success.
+ * \return -1 on error, for instance if device information could not be found.
  */
 static __hwloc_inline int
 hwloc_cudart_get_device_cpuset(hwloc_topology_t topology __hwloc_attribute_unused,
diff --git a/include/hwloc/gl.h b/include/hwloc/gl.h
@@ -1,6 +1,6 @@
 /*
  * Copyright © 2012 Blue Brain Project, EPFL. All rights reserved.
- * Copyright © 2012-2021 Inria.  All rights reserved.
+ * Copyright © 2012-2023 Inria.  All rights reserved.
  * See COPYING in top-level directory.
  */
 
@@ -102,7 +102,8 @@ hwloc_gl_get_display_osdev_by_name(hwloc_topology_t topology,
  * Retrieves the OpenGL display port (server) in \p port and device (screen)
  * in \p screen that correspond to the given hwloc OS device object.
  *
- * \return \c -1 if none could be found.
+ * \return 0 on success.
+ * \return -1 if none could be found.
  *
  * The topology \p topology does not necessarily have to match the current
  * machine. For instance the topology may be an XML import of a remote host.
diff --git a/include/hwloc/levelzero.h b/include/hwloc/levelzero.h
@@ -1,5 +1,5 @@
 /*
- * Copyright © 2021 Inria.  All rights reserved.
+ * Copyright © 2021-2023 Inria.  All rights reserved.
  * See COPYING in top-level directory.
  */
 
@@ -55,6 +55,9 @@ extern "C" {
  *
  * This function is currently only implemented in a meaningful way for
  * Linux; other systems will simply get a full cpuset.
+ *
+ * \return 0 on success.
+ * \return -1 on error, for instance if device information could not be found.
  */
 static __hwloc_inline int
 hwloc_levelzero_get_device_cpuset(hwloc_topology_t topology __hwloc_attribute_unused,
diff --git a/include/hwloc/nvml.h b/include/hwloc/nvml.h
@@ -1,5 +1,5 @@
 /*
- * Copyright © 2012-2021 Inria.  All rights reserved.
+ * Copyright © 2012-2023 Inria.  All rights reserved.
  * See COPYING in top-level directory.
  */
 
@@ -51,6 +51,9 @@ extern "C" {
  *
  * This function is currently only implemented in a meaningful way for
  * Linux; other systems will simply get a full cpuset.
+ *
+ * \return 0 on success.
+ * \return -1 on error, for instance if device information could not be found.
  */
 static __hwloc_inline int
 hwloc_nvml_get_device_cpuset(hwloc_topology_t topology __hwloc_attribute_unused,
diff --git a/include/hwloc/opencl.h b/include/hwloc/opencl.h
@@ -1,5 +1,5 @@
 /*
- * Copyright © 2012-2021 Inria.  All rights reserved.
+ * Copyright © 2012-2023 Inria.  All rights reserved.
  * Copyright © 2013, 2018 Université Bordeaux.  All right reserved.
  * See COPYING in top-level directory.
  */
@@ -69,6 +69,9 @@ typedef union {
 /** \brief Return the domain, bus and device IDs of the OpenCL device \p device.
  *
  * Device \p device must match the local machine.
+ *
+ * \return 0 on success.
+ * \return -1 on error, for instance if device information could not be found.
  */
 static __hwloc_inline int
 hwloc_opencl_get_device_pci_busid(cl_device_id device,
@@ -126,6 +129,9 @@ hwloc_opencl_get_device_pci_busid(cl_device_id device,
  * This function is currently only implemented in a meaningful way for
  * Linux with the AMD or NVIDIA OpenCL implementation; other systems will simply
  * get a full cpuset.
+ *
+ * \return 0 on success.
+ * \return -1 on error, for instance if the device could not be found.
  */
 static __hwloc_inline int
 hwloc_opencl_get_device_cpuset(hwloc_topology_t topology __hwloc_attribute_unused,
diff --git a/include/hwloc/openfabrics-verbs.h b/include/hwloc/openfabrics-verbs.h
@@ -1,6 +1,6 @@
 /*
  * Copyright © 2009 CNRS
- * Copyright © 2009-2021 Inria.  All rights reserved.
+ * Copyright © 2009-2023 Inria.  All rights reserved.
  * Copyright © 2009-2010 Université Bordeaux
  * Copyright © 2009-2011 Cisco Systems, Inc.  All rights reserved.
  * See COPYING in top-level directory.
@@ -57,6 +57,9 @@ extern "C" {
  *
  * This function is currently only implemented in a meaningful way for
  * Linux; other systems will simply get a full cpuset.
+ *
+ * \return 0 on success.
+ * \return -1 on error, for instance if device information could not be found.
  */
 static __hwloc_inline int
 hwloc_ibv_get_device_cpuset(hwloc_topology_t topology __hwloc_attribute_unused,
diff --git a/include/hwloc/rsmi.h b/include/hwloc/rsmi.h
@@ -1,5 +1,5 @@
 /*
- * Copyright © 2012-2021 Inria.  All rights reserved.
+ * Copyright © 2012-2023 Inria.  All rights reserved.
  * Copyright (c) 2020, Advanced Micro Devices, Inc. All rights reserved.
  * Written by Advanced Micro Devices,
  * See COPYING in top-level directory.
@@ -55,6 +55,9 @@ extern "C" {
  *
  * This function is currently only implemented in a meaningful way for
  * Linux; other systems will simply get a full cpuset.
+ *
+ * \return 0 on success.
+ * \return -1 on error, for instance if device information could not be found.
  */
 static __hwloc_inline int
 hwloc_rsmi_get_device_cpuset(hwloc_topology_t topology __hwloc_attribute_unused,
