device_def_domain_type documentation header does not match implementation

device_def_domain_type documentation header does not match implementation

[Diederik de Haas]

[-- Attachment #1: Type: text/plain, Size: 650 bytes --]

Hi,

While looking into ``drivers/iommu/intel/iommu.c::device_def_domain_type`` 
function I noticed a discrepancy between the documentation header and the 
implementation.

``@startup: true if this is during early boot``
0e31a7266508 ("iommu/vt-d: Remove startup parameter from 
device_def_domain_type()")
removed the ``startup`` function parameter

returns ``IOMMU_DOMAIN_DMA: device requires a dynamic mapping domain``
28b41e2c6aeb ("iommu: Move def_domain type check for untrusted device into 
core") 
moved the possible return of ``IOMMU_DOMAIN_DMA`` to ``drivers/iommu/iommu.c``

But neither updated the documentation header.

Cheers,
  Diederik

[-- Attachment #2: This is a digitally signed message part. --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

Re: device_def_domain_type documentation header does not match implementation

[Robin Murphy]

On 30/05/2024 2:57 pm, Diederik de Haas wrote:
> Hi,
> 
> While looking into ``drivers/iommu/intel/iommu.c::device_def_domain_type``
> function I noticed a discrepancy between the documentation header and the
> implementation.
> 
> ``@startup: true if this is during early boot``
> 0e31a7266508 ("iommu/vt-d: Remove startup parameter from
> device_def_domain_type()")
> removed the ``startup`` function parameter
> 
> returns ``IOMMU_DOMAIN_DMA: device requires a dynamic mapping domain``
> 28b41e2c6aeb ("iommu: Move def_domain type check for untrusted device into
> core")
> moved the possible return of ``IOMMU_DOMAIN_DMA`` to ``drivers/iommu/iommu.c``
> 
> But neither updated the documentation header.

TBH it could probably just be deleted now, since the 
iommu_ops::def_domain_type callback is properly documented in iommu.h, 
so individual implementations shouldn't need to repeat that. It's also 
never been actual kerneldoc either, since it's a regular "/*" comment. 
Feel free to send a patch :)

Thanks,
Robin.

Re: device_def_domain_type documentation header does not match implementation

[Diederik de Haas]

[-- Attachment #1: Type: text/plain, Size: 516 bytes --]

On Thursday, 30 May 2024 17:49:17 CEST Robin Murphy wrote:
> > But neither updated the documentation header.
> 
> TBH it could probably just be deleted now, since the
> iommu_ops::def_domain_type callback is properly documented in iommu.h,
> so individual implementations shouldn't need to repeat that. It's also
> never been actual kerneldoc either, since it's a regular "/*" comment.
> Feel free to send a patch :)

I leave that to people who actually know what they're doing (I'm not a C dev).

Cheers,
  Diederik

[-- Attachment #2: This is a digitally signed message part. --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

Re: device_def_domain_type documentation header does not match implementation

[Baolu Lu]

On 5/30/24 11:49 PM, Robin Murphy wrote:
> On 30/05/2024 2:57 pm, Diederik de Haas wrote:
>> Hi,
>>
>> While looking into 
>> ``drivers/iommu/intel/iommu.c::device_def_domain_type``
>> function I noticed a discrepancy between the documentation header and the
>> implementation.
>>
>> ``@startup: true if this is during early boot``
>> 0e31a7266508 ("iommu/vt-d: Remove startup parameter from
>> device_def_domain_type()")
>> removed the ``startup`` function parameter
>>
>> returns ``IOMMU_DOMAIN_DMA: device requires a dynamic mapping domain``
>> 28b41e2c6aeb ("iommu: Move def_domain type check for untrusted device 
>> into
>> core")
>> moved the possible return of ``IOMMU_DOMAIN_DMA`` to 
>> ``drivers/iommu/iommu.c``
>>
>> But neither updated the documentation header.
> 
> TBH it could probably just be deleted now, since the 
> iommu_ops::def_domain_type callback is properly documented in iommu.h, 
> so individual implementations shouldn't need to repeat that. It's also 
> never been actual kerneldoc either, since it's a regular "/*" comment. 
> Feel free to send a patch 🙂

Agreed. I will make a patch to remove it later.

Best regards,
baolu

Re: device_def_domain_type documentation header does not match implementation

[Baolu Lu]

On 5/30/24 9:57 PM, Diederik de Haas wrote:
> While looking into ``drivers/iommu/intel/iommu.c::device_def_domain_type``
> function I noticed a discrepancy between the documentation header and the
> implementation.
> 
> ``@startup: true if this is during early boot``
> 0e31a7266508 ("iommu/vt-d: Remove startup parameter from
> device_def_domain_type()")
> removed the ``startup`` function parameter
> 
> returns ``IOMMU_DOMAIN_DMA: device requires a dynamic mapping domain``
> 28b41e2c6aeb ("iommu: Move def_domain type check for untrusted device into
> core")
> moved the possible return of ``IOMMU_DOMAIN_DMA`` to ``drivers/iommu/iommu.c``
> 
> But neither updated the documentation header.

Yeah, I think the @startup line should be removed. It is irrelevant.
Others remain good to me.

Best regards,
baolu