From nobody Tue Dec 16 15:29:23 2025 Received: from galois.linutronix.de (Galois.linutronix.de [193.142.43.55]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 0C2DC280CD5; Tue, 6 May 2025 13:20:18 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=193.142.43.55 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1746537620; cv=none; b=gfa3MqBnHM0Y9GvLKomsaPLShV+eriRZ5+aEQ3xWDhikjPrKdW1dDVcVxx877rs0Cak2SvMO/a8ZT6Oi4GjjT///SXst+5nZVY2rpXRKLNGMo+Mz51Yf9KTCIBeYGEteys5Djw5mKl08takDuySYHEx3a7S1yEFxfp2BD7YnNdg= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1746537620; c=relaxed/simple; bh=RvsVuGujSHQtmig217z3XNrHCmj7IBWToW0w8bv05GE=; h=Date:From:To:Subject:Cc:In-Reply-To:References:MIME-Version: Message-ID:Content-Type; b=eanxFvZ692b8XOPNts+OxGlpxiRV9LqwtpisKEF6HJPWH442JDKNJ8rU9IiqQ7BuiG8QJIahX7jPzRLHGwbAFyaWFS4Tc7Ncxvofp3RY/1fF4s+3mPtlbHp477aibW42Azo/CD7CsF1Fnt9YX3dvi8EAsPZczj/9Wjk5GnXCnqQ= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=linutronix.de; spf=pass smtp.mailfrom=linutronix.de; dkim=pass (2048-bit key) header.d=linutronix.de header.i=@linutronix.de header.b=nZC9SoK5; dkim=permerror (0-bit key) header.d=linutronix.de header.i=@linutronix.de header.b=tyI8uoQE; arc=none smtp.client-ip=193.142.43.55 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=linutronix.de Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=linutronix.de Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=linutronix.de header.i=@linutronix.de header.b="nZC9SoK5"; dkim=permerror (0-bit key) header.d=linutronix.de header.i=@linutronix.de header.b="tyI8uoQE" Date: Tue, 06 May 2025 13:20:16 -0000 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linutronix.de; s=2020; t=1746537617; h=from:from:sender:sender:reply-to:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:cc:mime-version:mime-version: content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=I2bPPN+EoLSzveyxmINkawO+O20Vv0D+hNig6cFYGIE=; b=nZC9SoK50BEolyfs/pYAPjhhTgV81l8VRMqHQ6bGp5l9Zq07dQYbsiydLq7K8HRXY1vbQW UNoPsUO/hr80AUhyXIsm/BAHdPsRZICxs58BaJ6xqn5XyszGecvGFGJe+FOz0Qz08VzB01 jbBal4G+quRSHv8I7SdfkId1oMBQxAUJLnczn7aYOoeacv5kEbxNx893pxP/CIw4BUSjr9 6mDv4QPGIYwRWaEtj8ven3/940wVQiIYnbr5k27RH/GuC/UzXIGHO0ANj2VfDYTiz6DBm0 78TmqL2D+rt1b0dPSqD82KBFXKQDm84OWAZafjgH1WlEjAHu58iRyhl3bPVPqQ== DKIM-Signature: v=1; a=ed25519-sha256; c=relaxed/relaxed; d=linutronix.de; s=2020e; t=1746537617; h=from:from:sender:sender:reply-to:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:cc:mime-version:mime-version: content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=I2bPPN+EoLSzveyxmINkawO+O20Vv0D+hNig6cFYGIE=; b=tyI8uoQEg2Dv5XCVgy7ySwbORV51Ph3x87bq0FHWzNXS19/EP3or4uA2n9vUPUPcYQXc8p Lnmd/IjEwGIFyfBg== From: "tip-bot2 for Jiri Slaby (SUSE)" Sender: tip-bot2@linutronix.de Reply-to: linux-kernel@vger.kernel.org To: linux-tip-commits@vger.kernel.org Subject: [tip: irq/cleanups] irqdomain: Improve kernel-docs of functions Cc: "Jiri Slaby (SUSE)" , Thomas Gleixner , x86@kernel.org, linux-kernel@vger.kernel.org In-Reply-To: <20250319092951.37667-53-jirislaby@kernel.org> References: <20250319092951.37667-53-jirislaby@kernel.org> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Message-ID: <174653761649.406.11365759912285901770.tip-bot2@tip-bot2> Robot-ID: Robot-Unsubscribe: Contact to get blacklisted from these emails Precedence: bulk Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable The following commit has been merged into the irq/cleanups branch of tip: Commit-ID: fad0b7bbf9a698b4655efd49fca6926f664f9d02 Gitweb: https://git.kernel.org/tip/fad0b7bbf9a698b4655efd49fca6926f6= 64f9d02 Author: Jiri Slaby (SUSE) AuthorDate: Wed, 19 Mar 2025 10:29:45 +01:00 Committer: Thomas Gleixner CommitterDate: Tue, 06 May 2025 14:59:09 +02:00 irqdomain: Improve kernel-docs of functions Many of irqdomain.h's functions are referenced in Documentation/ but are not properly documented. Therefore, document these. And use "Returns:" tag consistently, so that it is properly generated in the resulting docs. Signed-off-by: Jiri Slaby (SUSE) Signed-off-by: Thomas Gleixner Link: https://lore.kernel.org/all/20250319092951.37667-53-jirislaby@kernel.= org --- include/linux/irqdomain.h | 42 +++++++++++++++++++++++++++++++++++++- 1 file changed, 41 insertions(+), 1 deletion(-) diff --git a/include/linux/irqdomain.h b/include/linux/irqdomain.h index 66a26df..a70e2ba 100644 --- a/include/linux/irqdomain.h +++ b/include/linux/irqdomain.h @@ -411,6 +411,15 @@ static inline struct irq_domain *irq_domain_create_nom= ap(struct fwnode_handle *f unsigned int irq_create_direct_mapping(struct irq_domain *domain); #endif =20 +/** + * irq_domain_create_linear - Allocate and register a linear revmap irq_do= main. + * @fwnode: pointer to interrupt controller's FW node. + * @size: Number of interrupts in the domain. + * @ops: map/unmap domain callbacks + * @host_data: Controller private data pointer + * + * Returns: Newly created irq_domain + */ static inline struct irq_domain *irq_domain_create_linear(struct fwnode_ha= ndle *fwnode, unsigned int size, const struct irq_domain_ops *ops, @@ -457,6 +466,18 @@ unsigned int irq_create_mapping_affinity(struct irq_do= main *domain, unsigned int irq_create_fwspec_mapping(struct irq_fwspec *fwspec); void irq_dispose_mapping(unsigned int virq); =20 +/** + * irq_create_mapping - Map a hardware interrupt into linux irq space + * @domain: domain owning this hardware interrupt or NULL for default doma= in + * @hwirq: hardware irq number in that domain space + * + * Only one mapping per hardware interrupt is permitted. + * + * If the sense/trigger is to be specified, set_irq_type() should be called + * on the number returned from that call. + * + * Returns: Linux irq number or 0 on error + */ static inline unsigned int irq_create_mapping(struct irq_domain *domain, irq_hw_number_t hwirq) { @@ -467,6 +488,13 @@ struct irq_desc *__irq_resolve_mapping(struct irq_doma= in *domain, irq_hw_number_t hwirq, unsigned int *irq); =20 +/** + * irq_resolve_mapping - Find a linux irq from a hw irq number. + * @domain: domain owning this hardware interrupt + * @hwirq: hardware irq number in that domain space + * + * Returns: Interrupt descriptor + */ static inline struct irq_desc *irq_resolve_mapping(struct irq_domain *doma= in, irq_hw_number_t hwirq) { @@ -477,6 +505,8 @@ static inline struct irq_desc *irq_resolve_mapping(stru= ct irq_domain *domain, * irq_find_mapping() - Find a linux irq from a hw irq number. * @domain: domain owning this hardware interrupt * @hwirq: hardware irq number in that domain space + * + * Returns: Linux irq number or 0 if not found */ static inline unsigned int irq_find_mapping(struct irq_domain *domain, irq_hw_number_t hwirq) @@ -539,7 +569,8 @@ void irq_domain_reset_irq_data(struct irq_data *irq_dat= a); * * If successful the parent is associated to the new domain and the * domain flags are set. - * Returns pointer to IRQ domain, or NULL on failure. + * + * Returns: A pointer to IRQ domain, or %NULL on failure. */ static inline struct irq_domain *irq_domain_create_hierarchy(struct irq_do= main *parent, unsigned int flags, @@ -570,6 +601,15 @@ void irq_domain_free_irqs(unsigned int virq, unsigned = int nr_irqs); int irq_domain_activate_irq(struct irq_data *irq_data, bool early); void irq_domain_deactivate_irq(struct irq_data *irq_data); =20 +/** + * irq_domain_alloc_irqs - Allocate IRQs from domain + * @domain: domain to allocate from + * @nr_irqs: number of IRQs to allocate + * @node: NUMA node id for memory allocation + * @arg: domain specific argument + * + * See __irq_domain_alloc_irqs()' documentation. + */ static inline int irq_domain_alloc_irqs(struct irq_domain *domain, unsigned int nr_irqs, int node, void *arg) {