From patchwork Wed Mar 27 06:35:48 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Manivannan Sadhasivam X-Patchwork-Id: 13605646 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from bombadil.infradead.org (bombadil.infradead.org [198.137.202.133]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.lore.kernel.org (Postfix) with ESMTPS id 008C8C47DD9 for ; Wed, 27 Mar 2024 06:37:17 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=lists.infradead.org; s=bombadil.20210309; h=Sender: Content-Transfer-Encoding:Content-Type:List-Subscribe:List-Help:List-Post: List-Archive:List-Unsubscribe:List-Id:Cc:To:In-Reply-To:References:Message-Id :MIME-Version:Subject:Date:From:Reply-To:Content-ID:Content-Description: Resent-Date:Resent-From:Resent-Sender:Resent-To:Resent-Cc:Resent-Message-ID: List-Owner; bh=4V9u53P7C3M0D43qD4A0vy5A/broy6zYlsQjagv5IYM=; b=kxXpvD0OwXfz+w Fhmm9zR+zxjiVYw3oDsYR6OOLIwMorMnLvdkGjEAI4BxNfwYAbb16G/5yZQLRygS/BYnsF7sMyEIy N6FIFMgxuqvsj4crFnRMaXPwxrWEjCCJNOBdIX2ElWuPYI4/0iyCvsP9de3pfOirlsM1W7+CUmB6y 2+Wcuo2bNKnQqf87DTvJe3MvlCKizx8L/QsbmPiF2SbT+iYcILx2rX0nGu2b7hah7LedbU0IRhPw4 mdlnmTqf4qRvg69uLfZnzwefxoityAhp8Q/oCzMkZY7GlikJI+i1NQvHgJmD54cXypZuW+B4zSzRk ZsEy14rk49idZknraiEw==; Received: from localhost ([::1] helo=bombadil.infradead.org) by bombadil.infradead.org with esmtp (Exim 4.97.1 #2 (Red Hat Linux)) id 1rpMuP-00000007gEq-3bcT; Wed, 27 Mar 2024 06:37:13 +0000 Received: from mail-pl1-x634.google.com ([2607:f8b0:4864:20::634]) by bombadil.infradead.org with esmtps (Exim 4.97.1 #2 (Red Hat Linux)) id 1rpMuL-00000007gBy-41XB for linux-rockchip@lists.infradead.org; Wed, 27 Mar 2024 06:37:11 +0000 Received: by mail-pl1-x634.google.com with SMTP id d9443c01a7336-1e0411c0a52so47941435ad.0 for ; Tue, 26 Mar 2024 23:37:06 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; t=1711521425; x=1712126225; darn=lists.infradead.org; h=cc:to:in-reply-to:references:message-id:content-transfer-encoding :mime-version:subject:date:from:from:to:cc:subject:date:message-id :reply-to; bh=vSuAzm3XlMTAAcdumCZGFConMRf5KMVdOQSvok+2c9Q=; b=F9/gz+3a7ugIIMfG9Qp96Q1pL7RUsCy8SKi1Rb06wNPjdcOFMOp2d0qkrK//wzyEpu s9EqR3jQw+703tTvTpIq0o1pe2bq/h7wQmC95XsJBz1JKluv0HA895xV2tvRXYSMYQSs o2k9mbuw++/m8hAx8+SWAONT69Az6bV/EUetyokyl4vQZ9W/hZ5pjzPC+VpMybKyH/+Q 9+Kx1QJRQTFVKT0BMJSWsoFfMfr2sBxLe3M6+aMWiD5qZElkz30GDyOi6dcG/IZkOg+O UiGWw5SRZDq8WWT3JkMwQeevSftCEVO7z9hTt1nC//7gFbjOBr2h3LS0uE75wy/RwnRP 6/kg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1711521425; x=1712126225; h=cc:to:in-reply-to:references:message-id:content-transfer-encoding :mime-version:subject:date:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=vSuAzm3XlMTAAcdumCZGFConMRf5KMVdOQSvok+2c9Q=; b=tVzG9yOO2YRqMZaIB+QnWkY0mRtVf+K0IJ00uROVkge/8JuGcC8w6Ibtb5VgBKVsBX XzxcX8LqudXzhTMtfXmpgQTFt2XJgKAr/XaMCdHCpfgDNc1CrKQSoO0Cq6eVhXsBMFhg 6sASSK2canTcmMIa8DJSBtMkfxEoB1KDIbNrvSmdoybrFJIgt0kUGFVD/WC66Am7hwfJ svA1rXTF0WXthwb7YmKyeXWmsXqkfuj++QnlD88lJ9mc0OdVb2nKvFPcLvDE4t6kDEBp eY3lpE7VYh3Bq4eyAkEHGdJsafsrd/nwe3HE/Qyw6as3H2TR0FJZAFYcEqW1HRDvYwoR gMdQ== X-Forwarded-Encrypted: i=1; AJvYcCULORx79xSSqrG2dFFYWbg0QHexKwE7ClhZkBqMoSR5NApEeNqWWSSC1J+AppPt+S8AZN4k5+mG8JEs9gyJLDJ+PbjJsDzUNdcdH0Ue3AUSTgsc X-Gm-Message-State: AOJu0Yzu9wgsw7+OgZS8LYJZqo0w6xEfUin3WAy55qUbl5TPGEWqQEaA 9NE+G4Z9eT+bO4ae8oTfamSFBKLS8TYXvGYXsCkLeymWoXR0hF6ZaKaOC5zgCg== X-Google-Smtp-Source: AGHT+IE9haQycs9Q8Q91eSl39u1OR+cHsQ599mlCpTtsFK7kXWvuJosCxsQnSUeW61EadHaElyNhsg== X-Received: by 2002:a17:902:ce05:b0:1dd:de1a:bd02 with SMTP id k5-20020a170902ce0500b001ddde1abd02mr364190plg.41.1711521425358; Tue, 26 Mar 2024 23:37:05 -0700 (PDT) Received: from [127.0.1.1] ([117.207.28.168]) by smtp.gmail.com with ESMTPSA id r9-20020a170902be0900b001e14807c7dfsm602553pls.86.2024.03.26.23.36.44 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 26 Mar 2024 23:37:04 -0700 (PDT) From: Manivannan Sadhasivam Date: Wed, 27 Mar 2024 12:05:48 +0530 Subject: [PATCH v11 2/8] PCI: dwc: ep: Add Kernel-doc comments for APIs MIME-Version: 1.0 Message-Id: <20240327-pci-dbi-rework-v11-2-6f5259f90673@linaro.org> References: <20240327-pci-dbi-rework-v11-0-6f5259f90673@linaro.org> In-Reply-To: <20240327-pci-dbi-rework-v11-0-6f5259f90673@linaro.org> To: Jingoo Han , Gustavo Pimentel , Lorenzo Pieralisi , =?utf-8?q?Krzysztof_Wilczy?= =?utf-8?q?=C5=84ski?= , Rob Herring , Bjorn Helgaas , Marek Vasut , Yoshihiro Shimoda , Thierry Reding , Jonathan Hunter , Kishon Vijay Abraham I , Vidya Sagar , Vignesh Raghavendra , Richard Zhu , Lucas Stach , Shawn Guo , Sascha Hauer , Pengutronix Kernel Team , Fabio Estevam , NXP Linux Team , Minghuan Lian , Mingkai Hu , Roy Zang , Kunihiko Hayashi , Masami Hiramatsu , Kishon Vijay Abraham I , Jesper Nilsson , Srikanth Thokala , Shawn Lin , Heiko Stuebner Cc: linux-pci@vger.kernel.org, linux-kernel@vger.kernel.org, linux-renesas-soc@vger.kernel.org, linux-arm-msm@vger.kernel.org, linux-tegra@vger.kernel.org, linux-omap@vger.kernel.org, linux-arm-kernel@lists.infradead.org, linuxppc-dev@lists.ozlabs.org, Niklas Cassel , linux-arm-kernel@axis.com, linux-rockchip@lists.infradead.org, Manivannan Sadhasivam , Frank Li X-Mailer: b4 0.12.4 X-Developer-Signature: v=1; a=openpgp-sha256; l=5382; i=manivannan.sadhasivam@linaro.org; h=from:subject:message-id; bh=11bvpB29WOEPsNZgWi/F9cZ0k6NdPLVZ7xUwINuLjH8=; b=owGbwMvMwMUYOl/w2b+J574ynlZLYkhj3hcaXnph73rNP0ZBckdVuTJ6wtnYXU8tFizlnrzqI /PWRsZJnYzGLAyMXAyyYoos6UudtRo9Tt9YEqE+HWYQKxPIFAYuTgGYSNB99n+WZk42NTGsZ+e/ 27L+l5q25olUvTrdnU//mVhcWnFwQ+/zLOlbi16JXdd9/ZrhaeJv/m/l8404Nk4QqNSvc+xpqNh of+1bjXHCpDUMwfWWl6OW506Of8OcM+uNLPO56HnLBItd2Tf4zv3ipcN5+8tkx88F7FZdymL3hW +n5bSzCvadyEl+qXCn8YzvHhv/mvDfNQxz1VeFmlxkeeT4eaK1QkV7/roTe098UL90sNxU2+zbi 5jZC/PenZPpL4vysrf14Zj2pa7k7OUEh1B9dTc7/0S56NrtbD9W1im7Bhh8aVw03yeIRcyt8eXB Y6FNHwU3MbGL164uMM5cnhsnwjNvkjafeFZUTn78H7klAA== X-Developer-Key: i=manivannan.sadhasivam@linaro.org; a=openpgp; fpr=C668AEC3C3188E4C611465E7488550E901166008 X-CRM114-Version: 20100106-BlameMichelson ( TRE 0.8.0 (BSD) ) MR-646709E3 X-CRM114-CacheID: sfid-20240326_233710_046286_A18889B2 X-CRM114-Status: GOOD ( 14.25 ) X-BeenThere: linux-rockchip@lists.infradead.org X-Mailman-Version: 2.1.34 Precedence: list List-Id: Upstream kernel work for Rockchip platforms List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: "Linux-rockchip" Errors-To: linux-rockchip-bounces+linux-rockchip=archiver.kernel.org@lists.infradead.org All of the APIs are missing the Kernel-doc comments. Hence, add them. Reviewed-by: Frank Li Reviewed-by: Niklas Cassel Signed-off-by: Manivannan Sadhasivam --- drivers/pci/controller/dwc/pcie-designware-ep.c | 77 +++++++++++++++++++++++++ 1 file changed, 77 insertions(+) diff --git a/drivers/pci/controller/dwc/pcie-designware-ep.c b/drivers/pci/controller/dwc/pcie-designware-ep.c index c05304eabb89..c2a7653b7b9f 100644 --- a/drivers/pci/controller/dwc/pcie-designware-ep.c +++ b/drivers/pci/controller/dwc/pcie-designware-ep.c @@ -14,6 +14,10 @@ #include #include +/** + * dw_pcie_ep_linkup - Notify EPF drivers about Link Up event + * @ep: DWC EP device + */ void dw_pcie_ep_linkup(struct dw_pcie_ep *ep) { struct pci_epc *epc = ep->epc; @@ -22,6 +26,10 @@ void dw_pcie_ep_linkup(struct dw_pcie_ep *ep) } EXPORT_SYMBOL_GPL(dw_pcie_ep_linkup); +/** + * dw_pcie_ep_init_notify - Notify EPF drivers about EPC initialization complete + * @ep: DWC EP device + */ void dw_pcie_ep_init_notify(struct dw_pcie_ep *ep) { struct pci_epc *epc = ep->epc; @@ -30,6 +38,14 @@ void dw_pcie_ep_init_notify(struct dw_pcie_ep *ep) } EXPORT_SYMBOL_GPL(dw_pcie_ep_init_notify); +/** + * dw_pcie_ep_get_func_from_ep - Get the struct dw_pcie_ep_func corresponding to + * the endpoint function + * @ep: DWC EP device + * @func_no: Function number of the endpoint device + * + * Return: struct dw_pcie_ep_func if success, NULL otherwise. + */ struct dw_pcie_ep_func * dw_pcie_ep_get_func_from_ep(struct dw_pcie_ep *ep, u8 func_no) { @@ -60,6 +76,11 @@ static void __dw_pcie_ep_reset_bar(struct dw_pcie *pci, u8 func_no, dw_pcie_dbi_ro_wr_dis(pci); } +/** + * dw_pcie_ep_reset_bar - Reset endpoint BAR + * @pci: DWC PCI device + * @bar: BAR number of the endpoint + */ void dw_pcie_ep_reset_bar(struct dw_pcie *pci, enum pci_barno bar) { u8 func_no, funcs; @@ -439,6 +460,13 @@ static const struct pci_epc_ops epc_ops = { .get_features = dw_pcie_ep_get_features, }; +/** + * dw_pcie_ep_raise_intx_irq - Raise INTx IRQ to the host + * @ep: DWC EP device + * @func_no: Function number of the endpoint + * + * Return: 0 if success, errono otherwise. + */ int dw_pcie_ep_raise_intx_irq(struct dw_pcie_ep *ep, u8 func_no) { struct dw_pcie *pci = to_dw_pcie_from_ep(ep); @@ -450,6 +478,14 @@ int dw_pcie_ep_raise_intx_irq(struct dw_pcie_ep *ep, u8 func_no) } EXPORT_SYMBOL_GPL(dw_pcie_ep_raise_intx_irq); +/** + * dw_pcie_ep_raise_msi_irq - Raise MSI IRQ to the host + * @ep: DWC EP device + * @func_no: Function number of the endpoint + * @interrupt_num: Interrupt number to be raised + * + * Return: 0 if success, errono otherwise. + */ int dw_pcie_ep_raise_msi_irq(struct dw_pcie_ep *ep, u8 func_no, u8 interrupt_num) { @@ -498,6 +534,15 @@ int dw_pcie_ep_raise_msi_irq(struct dw_pcie_ep *ep, u8 func_no, } EXPORT_SYMBOL_GPL(dw_pcie_ep_raise_msi_irq); +/** + * dw_pcie_ep_raise_msix_irq_doorbell - Raise MSI-X to the host using Doorbell + * method + * @ep: DWC EP device + * @func_no: Function number of the endpoint device + * @interrupt_num: Interrupt number to be raised + * + * Return: 0 if success, errno otherwise. + */ int dw_pcie_ep_raise_msix_irq_doorbell(struct dw_pcie_ep *ep, u8 func_no, u16 interrupt_num) { @@ -517,6 +562,14 @@ int dw_pcie_ep_raise_msix_irq_doorbell(struct dw_pcie_ep *ep, u8 func_no, return 0; } +/** + * dw_pcie_ep_raise_msix_irq - Raise MSI-X to the host + * @ep: DWC EP device + * @func_no: Function number of the endpoint device + * @interrupt_num: Interrupt number to be raised + * + * Return: 0 if success, errno otherwise. + */ int dw_pcie_ep_raise_msix_irq(struct dw_pcie_ep *ep, u8 func_no, u16 interrupt_num) { @@ -564,6 +617,13 @@ int dw_pcie_ep_raise_msix_irq(struct dw_pcie_ep *ep, u8 func_no, return 0; } +/** + * dw_pcie_ep_exit - Deinitialize the endpoint device + * @ep: DWC EP device + * + * Deinitialize the endpoint device. EPC device is not destroyed since that will + * be taken care by Devres. + */ void dw_pcie_ep_exit(struct dw_pcie_ep *ep) { struct dw_pcie *pci = to_dw_pcie_from_ep(ep); @@ -599,6 +659,14 @@ static unsigned int dw_pcie_ep_find_ext_capability(struct dw_pcie *pci, int cap) return 0; } +/** + * dw_pcie_ep_init_complete - Complete DWC EP initialization + * @ep: DWC EP device + * + * Complete the initialization of the registers (CSRs) specific to DWC EP. This + * API should be called only when the endpoint receives an active refclk (either + * from host or generated locally). + */ int dw_pcie_ep_init_complete(struct dw_pcie_ep *ep) { struct dw_pcie *pci = to_dw_pcie_from_ep(ep); @@ -716,6 +784,15 @@ int dw_pcie_ep_init_complete(struct dw_pcie_ep *ep) } EXPORT_SYMBOL_GPL(dw_pcie_ep_init_complete); +/** + * dw_pcie_ep_init - Initialize the endpoint device + * @ep: DWC EP device + * + * Initialize the endpoint device. Allocate resources and create the EPC + * device with the endpoint framework. + * + * Return: 0 if success, errno otherwise. + */ int dw_pcie_ep_init(struct dw_pcie_ep *ep) { int ret;