Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20;
Received-SPF: Pass (protection.outlook.com: domain of nvidia.com designates
 12.22.5.238 as permitted sender) receiver=protection.outlook.com;
 client-ip=12.22.5.238; helo=mail.nvidia.com; pr=C
Date:   Tue, 13 Sep 2022 13:00:27 -0700
From:   Nicolin Chen <nicolinc@nvidia.com>
To:     Jeff Johnson <quic_jjohnson@quicinc.com>
CC:     <joro@8bytes.org>, <suravee.suthikulpanit@amd.com>,
        <will@kernel.org>, <robin.murphy@arm.com>, <robdclark@gmail.com>,
        <dwmw2@infradead.org>, <baolu.lu@linux.intel.com>,
        <agross@kernel.org>, <bjorn.andersson@linaro.org>,
        <konrad.dybcio@somainline.org>, <matthias.bgg@gmail.com>,
        <heiko@sntech.de>, <orsonzhai@gmail.com>,
        <baolin.wang@linux.alibaba.com>, <zhang.lyra@gmail.com>,
        <thierry.reding@gmail.com>, <jean-philippe@linaro.org>,
        <jgg@nvidia.com>, <sricharan@codeaurora.org>,
        <yong.wu@mediatek.com>, <vdumpa@nvidia.com>,
        <jonathanh@nvidia.com>, <tglx@linutronix.de>,
        <shameerali.kolothum.thodi@huawei.com>,
        <thunder.leizhen@huawei.com>, <christophe.jaillet@wanadoo.fr>,
        <yangyingliang@huawei.com>, <jon@solid-run.com>,
        <iommu@lists.linux.dev>, <linux-kernel@vger.kernel.org>,
        <linux-arm-kernel@lists.infradead.org>,
        <linux-arm-msm@vger.kernel.org>,
        <linux-mediatek@lists.infradead.org>,
        <linux-rockchip@lists.infradead.org>,
        <linux-tegra@vger.kernel.org>,
        <virtualization@lists.linux-foundation.org>
Subject: Re: [PATCH 3/5] iommu: Add return errno rules to ->attach_dev ops
Message-ID: <YyDhW/HJaKMygccm@Asurada-Nvidia>
References: <20220913082448.31120-1-nicolinc@nvidia.com>
 <20220913082448.31120-4-nicolinc@nvidia.com>
 <cd92cfec-0a68-a42d-1fa4-a16e37e59d53@quicinc.com>
MIME-Version: 1.0
Content-Type: text/plain; charset="us-ascii"
Content-Disposition: inline
In-Reply-To: <cd92cfec-0a68-a42d-1fa4-a16e37e59d53@quicinc.com>
X-MS-Exchange-CrossTenant-OriginalArrivalTime: 13 Sep 2022 20:00:31.1582
 (UTC)
X-MS-Exchange-CrossTenant-Network-Message-Id: eb3b88e3-1aa6-47b3-b11a-08da95c29cc4
X-MS-Exchange-CrossTenant-Id: 43083d15-7273-40c1-b7db-39efd9ccc17a
X-MS-Exchange-CrossTenant-OriginalAttributedTenantConnectingIp: TenantId=43083d15-7273-40c1-b7db-39efd9ccc17a;Ip=[12.22.5.238];Helo=[mail.nvidia.com]
X-MS-Exchange-CrossTenant-AuthSource: DM6NAM11FT040.eop-nam11.prod.protection.outlook.com
X-MS-Exchange-CrossTenant-AuthAs: Anonymous
X-MS-Exchange-CrossTenant-FromEntityHeader: HybridOnPrem
X-MS-Exchange-Transport-CrossTenantHeadersStamped: DM4PR12MB5167
X-Spam-Status: No, score=-1.1 required=5.0 tests=BAYES_00,DKIMWL_WL_HIGH,
        DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,DKIM_VALID_EF,FORGED_SPF_HELO,
        RCVD_IN_DNSWL_NONE,RCVD_IN_MSPIKE_H2,SPF_HELO_PASS,SPF_NONE,
        T_SCC_BODY_TEXT_LINE autolearn=no autolearn_force=no version=3.4.6
X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on
        lindbergh.monkeyblade.net
Precedence: bulk
List-ID: <linux-kernel.vger.kernel.org>
X-Mailing-List: linux-kernel@vger.kernel.org

Hi Jeff,

On Tue, Sep 13, 2022 at 11:41:35AM -0700, Jeff Johnson wrote:
> > diff --git a/include/linux/iommu.h b/include/linux/iommu.h
> > index ea30f00dc145..c5d7ec0187c7 100644
> > --- a/include/linux/iommu.h
> > +++ b/include/linux/iommu.h
> > @@ -266,6 +266,17 @@ struct iommu_ops {
> >   /**
> >    * struct iommu_domain_ops - domain specific operations
> >    * @attach_dev: attach an iommu domain to a device
> > + *              Rules of its return errno:
> > + *               EINVAL  - Exclusively, device and domain are incompatible. Must
> > + *                         avoid kernel prints along with this errno. Any EINVAL
> > + *                         returned from kAPIs must be converted to ENODEV if it
> > + *                         is device-specific, or to some other reasonable errno
> > + *                         being listed below
> > + *               ENOMEM  - Out of memory
> > + *               ENOSPC  - No space left on device
> > + *               EBUSY   - Device is attached to a domain and cannot be changed
> > + *               ENODEV  - Device specific errors, not able to be attached
> > + *              <others> - Treated as ENODEV by the caller. Use is discouraged
> 
> It is my understanding that kernel-doc won't preserve your formatting
> without extra directives. See the "Note" after
> <https://www.kernel.org/doc/html/latest/doc-guide/kernel-doc.html#return-values>

Thanks for the review!

Perhaps the following one would work:

diff --git a/include/linux/iommu.h b/include/linux/iommu.h
index ea30f00dc145..14f078b58e17 100644
--- a/include/linux/iommu.h
+++ b/include/linux/iommu.h
@@ -266,6 +266,17 @@ struct iommu_ops {
 /**
  * struct iommu_domain_ops - domain specific operations
  * @attach_dev: attach an iommu domain to a device
+ *  Return:
+ * * 0         - success
+ * * EINVAL    - Exclusively, device and domain are incompatible. Must avoid
+ *               kernel prints along with this errno. Any EINVAL returned from
+ *               a kAPI must be converted to ENODEV if it is device-specific,
+ *               or to some other reasonable errno being listed below
+ * * ENOMEM    - Out of memory
+ * * ENOSPC    - No space left on device
+ * * EBUSY     - Device is attached to a domain and cannot be changed
+ * * ENODEV    - Device specific errors, not able to be attached
+ * * <others>  - Treated as ENODEV by the caller. Use is discouraged
  * @detach_dev: detach an iommu domain from a device
  * @map: map a physically contiguous memory region to an iommu domain
  * @map_pages: map a physically contiguous set of pages of the same size to