linux-kernel - [PATCH v3 2/2] lib/logic_pio: add and clean up comment in logic

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [day] [month] [year] [list]

Message-Id: <56ded65af1f94894ce56cd83bf7c5edef20291bc.1745377493.git.xiaopei01@kylinos.cn>
Date: Wed, 23 Apr 2025 11:22:38 +0800
From: Pei Xiao <xiaopei01@...inos.cn>
To: xiaopei01@...inos.cn
Cc: andriy.shevchenko@...ux.intel.com,
	john.g.garry@...cle.com,
	linux-kernel@...r.kernel.org,
	robh@...nel.org,
	xiaopeitux@...mail.com,
	xuwei5@...ilicon.com
Subject: [PATCH v3 2/2] lib/logic_pio: add and clean up comment in logic_lib

1.Add comments that we were previously overlooked for find_io_range()
and logic_pio_trans_cpuaddr().
2.clean up other comment according to kernel-doc

Signed-off-by: Pei Xiao <xiaopei01@...inos.cn>
---
changes in v3: add Return section add cleanup
changes in v2: Returns to Return 
---
 lib/logic_pio.c | 37 ++++++++++++++++++++++++++++---------
 1 file changed, 28 insertions(+), 9 deletions(-)

diff --git a/lib/logic_pio.c b/lib/logic_pio.c
index e29496a38d06..5a080baf2001 100644
--- a/lib/logic_pio.c
+++ b/lib/logic_pio.c
@@ -24,11 +24,12 @@ static DEFINE_MUTEX(io_range_mutex);
  * logic_pio_register_range - register logical PIO range for a host
  * @new_range: pointer to the IO range to be registered.
  *
- * Returns 0 on success, the error code in case of failure.
+ * Register a new IO range node in the IO range list.
+ *
+ * Return: 0 on success, the error code in case of failure.
  * If the range already exists, -EEXIST will be returned, which should be
  * considered a success.
  *
- * Register a new IO range node in the IO range list.
  */
 int logic_pio_register_range(struct logic_pio_hwaddr *new_range)
 {
@@ -118,9 +119,9 @@ void logic_pio_unregister_range(struct logic_pio_hwaddr *range)
  * find_io_range_by_fwnode - find logical PIO range for given FW node
  * @fwnode: FW node handle associated with logical PIO range
  *
- * Returns pointer to node on success, NULL otherwise.
- *
  * Traverse the io_range_list to find the registered node for @fwnode.
+ *
+ * Return: pointer to node on success, NULL otherwise.
  */
 struct logic_pio_hwaddr *find_io_range_by_fwnode(const struct fwnode_handle *fwnode)
 {
@@ -138,7 +139,15 @@ struct logic_pio_hwaddr *find_io_range_by_fwnode(const struct fwnode_handle *fwn
 	return found_range;
 }
 
-/* Return a registered range given an input PIO token */
+/**
+ * find_io_range - find a registered range by PIO
+ * @pio: logical PIO value
+ *
+ * Traverse the io_range_list to find the registered node for @pio.
+ * The input PIO should be unique in the whole logical PIO space.
+ *
+ * Return: a registered range, NULL otherwise.
+ */
 static struct logic_pio_hwaddr *find_io_range(unsigned long pio)
 {
 	struct logic_pio_hwaddr *range, *found_range = NULL;
@@ -162,10 +171,10 @@ static struct logic_pio_hwaddr *find_io_range(unsigned long pio)
  * logic_pio_to_hwaddr - translate logical PIO to HW address
  * @pio: logical PIO value
  *
- * Returns HW address if valid, ~0 otherwise.
- *
  * Translate the input logical PIO to the corresponding hardware address.
  * The input PIO should be unique in the whole logical PIO space.
+ *
+ * Return: HW address if valid, ~0 otherwise.
  */
 resource_size_t logic_pio_to_hwaddr(unsigned long pio)
 {
@@ -179,12 +188,14 @@ resource_size_t logic_pio_to_hwaddr(unsigned long pio)
 }
 
 /**
- * logic_pio_trans_hwaddr - translate HW address to logical PIO
+ * logic_pio_trans_hwaddr - translate HW address to logical PIO by fwnode
  * @fwnode: FW node reference for the host
  * @addr: Host-relative HW address
  * @size: size to translate
  *
- * Returns Logical PIO value if successful, ~0UL otherwise
+ * Translate HW address by fwnode to logical PIO
+ *
+ * Return: Logical PIO value if successful, ~0UL otherwise
  */
 unsigned long logic_pio_trans_hwaddr(const struct fwnode_handle *fwnode,
 				     resource_size_t addr, resource_size_t size)
@@ -204,6 +215,14 @@ unsigned long logic_pio_trans_hwaddr(const struct fwnode_handle *fwnode,
 	return addr - range->hw_start + range->io_start;
 }
 
+/**
+ * logic_pio_trans_cpuaddr - translate CPU address to logical PIO
+ * @addr: Host-relative CPU address
+ *
+ * translate CPU address to logical PIO
+ *
+ * Return: Logical PIO value if successful, ~0UL otherwise
+ */
 unsigned long logic_pio_trans_cpuaddr(resource_size_t addr)
 {
 	struct logic_pio_hwaddr *range;
-- 
2.25.1