[PATCH v3 3/6] iommu: Add return value rules to attach_dev op and APIs

[Nicolin Chen]

On Tue, Sep 20, 2022 at 06:24:58AM +0000, Tian, Kevin wrote:
> External email: Use caution opening links or attachments
> 
> 
> > From: Nicolin Chen <nicolinc at nvidia.com>
> > Sent: Thursday, September 15, 2022 3:54 PM
> >
> > +/**
> > + * iommu_attach_device - Attach a device to an IOMMU domain
> > + * @domain: IOMMU domain to attach
> > + * @dev: Device that will be attached
> > + *
> > + * Returns 0 on success and error code on failure
> > + *
> > + * Note that EINVAL may be returned as a soft failure if the domain and
> > device
> > + * are incompatible: if the domain has already been used or configured in
> > some
> 
> I didn't get the meaning of the 'if' part.

It means that the failure of attaching the device to the domain is
due to the domain configuration.

> > + * way, attaching the same device to a different domain may succeed.
> > Otherwise,
> > + * it may still represent some fundamental problem.
> 
> I'm not sure what the sentence after 'otherwise' actually adds to the
> caller. There is no way to differentiate incompatibility vs. fundamental
> problem, hence pointless for the caller to know this fact.
> 
> IMHO just state that the caller can treat -EINVAL as soft failure indicating
> incompatibility issue between domain and device.

OK. I changed to:
+ * Note that EINVAL may be returned as a soft failure if the domain and device
+ * are incompatible due to some previous configuration of the domain, in which
+ * case attaching the same device to a different domain may succeed.

> Later for @attach_dev you can add that driver may return (but not
> recommend) -EINVAL for some fundamental problems.

OK.