[PATCH] of/irq: Document of_irq_init() device node refcount contract

[PATCH] of/irq: Document of_irq_init() device node refcount contract

[Radu Rendec]

When a driver initialization function is successful, of_irq_init() keeps
a refcount on the device node it has passed, which makes it safe for the
driver to store a pointer to the device node and use it after the
initialization function returns.

This behavior is currently not documented anywhere, and only assumed.
Add a paragraph to the comment block preceding of_irq_init() to document
the behavior and turn it into a contract.

It is worth noting that of_irq_init() did leak device node refcounts in
the past, and this was addressed in multiple commits; most recently in
commit 708124d9e6e7 ("of/irq: Fix device node refcount leakages in
of_irq_init()"), which fixed the refcount leaks for the initialization
failure path only. That is an indirect confirmation that keeping the
refcount on the successful path is intentional.

Signed-off-by: Radu Rendec <radu@rendec.net>
---
 drivers/of/irq.c | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/drivers/of/irq.c b/drivers/of/irq.c
index ef1ed9743907..bf277781cdb6 100644
--- a/drivers/of/irq.c
+++ b/drivers/of/irq.c
@@ -647,6 +647,15 @@ struct of_intc_desc {
  *
  * This function scans the device tree for matching interrupt controller nodes,
  * and calls their initialization functions in order with parents first.
+ *
+ * The initialization functions are called while holding a refcount on the
+ * device node corresponding to the device that is being initialized (passed
+ * as the first parameter). If an initialization function is successful, the
+ * device node refcount is *not* dropped (ever); this is intentional and
+ * guarantees that the pointer passed to the initialization function is valid
+ * not only while the function runs, but also for the rest of the kernel
+ * lifetime (i.e. it is safe for a driver to store the device node pointer
+ * and use it *after* the initialization function returns).
  */
 void __init of_irq_init(const struct of_device_id *matches)
 {
-- 
2.55.0