drivers/usb/host/xhci.c | 1 + 1 file changed, 1 insertion(+)
Fix kernel-doc warning by documenting the @desc parameter:
drivers/usb/host/xhci.c:1369: warning: Function parameter or struct member
'desc' not described in 'xhci_get_endpoint_index'
Add detailed description of the @desc parameter and clarify the indexing
logic for control endpoints vs other types. This brings the documentation
in line with kernel-doc requirements while maintaining technical accuracy.
Signed-off-by: Hans Zhang <18255117159@163.com>
---
drivers/usb/host/xhci.c | 1 +
1 file changed, 1 insertion(+)
diff --git a/drivers/usb/host/xhci.c b/drivers/usb/host/xhci.c
index 90eb491267b5..dbe6f41202ca 100644
--- a/drivers/usb/host/xhci.c
+++ b/drivers/usb/host/xhci.c
@@ -1359,6 +1359,7 @@ static void xhci_unmap_urb_for_dma(struct usb_hcd *hcd, struct urb *urb)
* xhci_get_endpoint_index - Used for passing endpoint bitmasks between the core and
* HCDs. Find the index for an endpoint given its descriptor. Use the return
* value to right shift 1 for the bitmask.
+ * @desc: USB endpoint descriptor to determine index for
*
* Index = (epnum * 2) + direction - 1,
* where direction = 0 for OUT, 1 for IN.
base-commit: ca91b9500108d4cf083a635c2e11c884d5dd20ea
--
2.25.1On Mon, May 05, 2025 at 12:04:15AM +0800, Hans Zhang wrote: > Fix kernel-doc warning by documenting the @desc parameter: > > drivers/usb/host/xhci.c:1369: warning: Function parameter or struct member > 'desc' not described in 'xhci_get_endpoint_index' > > Add detailed description of the @desc parameter and clarify the indexing > logic for control endpoints vs other types. This brings the documentation > in line with kernel-doc requirements while maintaining technical accuracy. > > Signed-off-by: Hans Zhang <18255117159@163.com> What commit id does this fix? thanks, greg k-h
On 2025/5/5 13:00, Greg KH wrote: > On Mon, May 05, 2025 at 12:04:15AM +0800, Hans Zhang wrote: >> Fix kernel-doc warning by documenting the @desc parameter: >> >> drivers/usb/host/xhci.c:1369: warning: Function parameter or struct member >> 'desc' not described in 'xhci_get_endpoint_index' >> >> Add detailed description of the @desc parameter and clarify the indexing >> logic for control endpoints vs other types. This brings the documentation >> in line with kernel-doc requirements while maintaining technical accuracy. >> >> Signed-off-by: Hans Zhang <18255117159@163.com> > > What commit id does this fix? > Hi Greg, export ARCH=arm64 make defconfig make Image W=1 -j16 ./aarch64-none-linux-gnu-gcc -v Using built-in specs. COLLECT_GCC=./aarch64-none-linux-gnu-gcc COLLECT_LTO_WRAPPER=/media/zhb/hans/code/cix_linux_gcc/arm-gnu-toolchain-12.3.rel1-x86_64-aarch64-none-linux-gnu/bin/../libexec/gcc/aarch64-none-linux-gnu/12.3.1/lto-wrapper Target: aarch64-none-linux-gnu Configured with: /data/jenkins/workspace/GNU-toolchain/arm-12/src/gcc/configure --target=aarch64-none-linux-gnu --prefix= --with-sysroot=/aarch64-none-linux-gnu/libc --with-build-sysroot=/data/jenkins/workspace/GNU-toolchain/arm-12/build-aarch64-none-linux-gnu/install//aarch64-none-linux-gnu/libc --with-bugurl=https://bugs.linaro.org/ --enable-gnu-indirect-function --enable-shared --disable-libssp --disable-libmudflap --enable-checking=release --enable-languages=c,c++,fortran --with-gmp=/data/jenkins/workspace/GNU-toolchain/arm-12/build-aarch64-none-linux-gnu/host-tools --with-mpfr=/data/jenkins/workspace/GNU-toolchain/arm-12/build-aarch64-none-linux-gnu/host-tools --with-mpc=/data/jenkins/workspace/GNU-toolchain/arm-12/build-aarch64-none-linux-gnu/host-tools --with-isl=/data/jenkins/workspace/GNU-toolchain/arm-12/build-aarch64-none-linux-gnu/host-tools --enable-fix-cortex-a53-843419 --with-pkgversion='Arm GNU Toolchain 12.3.Rel1 (Build arm-12.35)' Thread model: posix Supported LTO compression algorithms: zlib gcc version 12.3.1 20230626 (Arm GNU Toolchain 12.3.Rel1 (Build arm-12.35)) I'm debugging the problem of pci and modified the iinclude/linux/pci.h file. If the above compilation method is adopted, the following warnings will occur. Use my patch and the warning disappears. Compilation warning: drivers/usb/host/xhci.c:1370: warning: Function parameter or struct member 'desc' not described in 'xhci_get_endpoint_index' The reproduction method can also be modified by modifying the drivers/usb/host/xhci.c file and then compiling, and the above warning will appear. Please review whether this needs to be fixed. If not, please ignore this patch. Best regards, Hans
On 2025/5/5 23:35, Hans Zhang wrote: > > > On 2025/5/5 13:00, Greg KH wrote: >> On Mon, May 05, 2025 at 12:04:15AM +0800, Hans Zhang wrote: >>> Fix kernel-doc warning by documenting the @desc parameter: >>> >>> drivers/usb/host/xhci.c:1369: warning: Function parameter or struct >>> member >>> 'desc' not described in 'xhci_get_endpoint_index' >>> >>> Add detailed description of the @desc parameter and clarify the indexing >>> logic for control endpoints vs other types. This brings the >>> documentation >>> in line with kernel-doc requirements while maintaining technical >>> accuracy. >>> >>> Signed-off-by: Hans Zhang <18255117159@163.com> >> >> What commit id does this fix? >> > > Hi Greg, > > export ARCH=arm64 > make defconfig > make Image W=1 -j16 > > ./aarch64-none-linux-gnu-gcc -v > Using built-in specs. > COLLECT_GCC=./aarch64-none-linux-gnu-gcc > COLLECT_LTO_WRAPPER=/media/zhb/hans/code/cix_linux_gcc/arm-gnu-toolchain-12.3.rel1-x86_64-aarch64-none-linux-gnu/bin/../libexec/gcc/aarch64-none-linux-gnu/12.3.1/lto-wrapper > Target: aarch64-none-linux-gnu > Configured with: > /data/jenkins/workspace/GNU-toolchain/arm-12/src/gcc/configure > --target=aarch64-none-linux-gnu --prefix= > --with-sysroot=/aarch64-none-linux-gnu/libc > --with-build-sysroot=/data/jenkins/workspace/GNU-toolchain/arm-12/build-aarch64-none-linux-gnu/install//aarch64-none-linux-gnu/libc --with-bugurl=https://bugs.linaro.org/ --enable-gnu-indirect-function --enable-shared --disable-libssp --disable-libmudflap --enable-checking=release --enable-languages=c,c++,fortran --with-gmp=/data/jenkins/workspace/GNU-toolchain/arm-12/build-aarch64-none-linux-gnu/host-tools --with-mpfr=/data/jenkins/workspace/GNU-toolchain/arm-12/build-aarch64-none-linux-gnu/host-tools --with-mpc=/data/jenkins/workspace/GNU-toolchain/arm-12/build-aarch64-none-linux-gnu/host-tools --with-isl=/data/jenkins/workspace/GNU-toolchain/arm-12/build-aarch64-none-linux-gnu/host-tools --enable-fix-cortex-a53-843419 --with-pkgversion='Arm GNU Toolchain 12.3.Rel1 (Build arm-12.35)' > Thread model: posix > Supported LTO compression algorithms: zlib > gcc version 12.3.1 20230626 (Arm GNU Toolchain 12.3.Rel1 (Build arm-12.35)) > > > I'm debugging the problem of pci and modified the iinclude/linux/pci.h > file. If the above compilation method is adopted, the following warnings > will occur. Use my patch and the warning disappears. > > Compilation warning: > drivers/usb/host/xhci.c:1370: warning: Function parameter or struct > member 'desc' not described in 'xhci_get_endpoint_index' > > > The reproduction method can also be modified by modifying the > drivers/usb/host/xhci.c file and then compiling, and the above warning > will appear. > > Please review whether this needs to be fixed. If not, please ignore this > patch. > > Hi Greg, This patch does not fix specific code errors. Instead, it improves the parameter documentation of the xhci_get_endpoint_index function (adding a description for @desc) to enhance code readability. Therefore, it does not fix any issues with historical submissions and is an independent document improvement patch. Best regards, Hans
On Mon, May 05, 2025 at 11:43:05PM +0800, Hans Zhang wrote: > > > On 2025/5/5 23:35, Hans Zhang wrote: > > > > > > On 2025/5/5 13:00, Greg KH wrote: > > > On Mon, May 05, 2025 at 12:04:15AM +0800, Hans Zhang wrote: > > > > Fix kernel-doc warning by documenting the @desc parameter: > > > > > > > > drivers/usb/host/xhci.c:1369: warning: Function parameter or > > > > struct member > > > > 'desc' not described in 'xhci_get_endpoint_index' > > > > > > > > Add detailed description of the @desc parameter and clarify the indexing > > > > logic for control endpoints vs other types. This brings the > > > > documentation > > > > in line with kernel-doc requirements while maintaining technical > > > > accuracy. > > > > > > > > Signed-off-by: Hans Zhang <18255117159@163.com> > > > > > > What commit id does this fix? > > > > > > > Hi Greg, > > > > export ARCH=arm64 > > make defconfig > > make Image W=1 -j16 > > > > ./aarch64-none-linux-gnu-gcc -v > > Using built-in specs. > > COLLECT_GCC=./aarch64-none-linux-gnu-gcc > > COLLECT_LTO_WRAPPER=/media/zhb/hans/code/cix_linux_gcc/arm-gnu-toolchain-12.3.rel1-x86_64-aarch64-none-linux-gnu/bin/../libexec/gcc/aarch64-none-linux-gnu/12.3.1/lto-wrapper > > Target: aarch64-none-linux-gnu > > Configured with: > > /data/jenkins/workspace/GNU-toolchain/arm-12/src/gcc/configure > > --target=aarch64-none-linux-gnu --prefix= > > --with-sysroot=/aarch64-none-linux-gnu/libc --with-build-sysroot=/data/jenkins/workspace/GNU-toolchain/arm-12/build-aarch64-none-linux-gnu/install//aarch64-none-linux-gnu/libc > > --with-bugurl=https://bugs.linaro.org/ --enable-gnu-indirect-function > > --enable-shared --disable-libssp --disable-libmudflap > > --enable-checking=release --enable-languages=c,c++,fortran --with-gmp=/data/jenkins/workspace/GNU-toolchain/arm-12/build-aarch64-none-linux-gnu/host-tools --with-mpfr=/data/jenkins/workspace/GNU-toolchain/arm-12/build-aarch64-none-linux-gnu/host-tools --with-mpc=/data/jenkins/workspace/GNU-toolchain/arm-12/build-aarch64-none-linux-gnu/host-tools --with-isl=/data/jenkins/workspace/GNU-toolchain/arm-12/build-aarch64-none-linux-gnu/host-tools > > --enable-fix-cortex-a53-843419 --with-pkgversion='Arm GNU Toolchain > > 12.3.Rel1 (Build arm-12.35)' > > Thread model: posix > > Supported LTO compression algorithms: zlib > > gcc version 12.3.1 20230626 (Arm GNU Toolchain 12.3.Rel1 (Build arm-12.35)) > > > > > > I'm debugging the problem of pci and modified the iinclude/linux/pci.h > > file. If the above compilation method is adopted, the following warnings > > will occur. Use my patch and the warning disappears. > > > > Compilation warning: > > drivers/usb/host/xhci.c:1370: warning: Function parameter or struct > > member 'desc' not described in 'xhci_get_endpoint_index' > > > > > > The reproduction method can also be modified by modifying the > > drivers/usb/host/xhci.c file and then compiling, and the above warning > > will appear. > > > > Please review whether this needs to be fixed. If not, please ignore this > > patch. > > > > > > Hi Greg, > > This patch does not fix specific code errors. Instead, it improves the > parameter documentation of the xhci_get_endpoint_index function (adding a > description for @desc) to enhance code readability. Therefore, it does not > fix any issues with historical submissions and is an independent document > improvement patch. It fixes when that parameter was added to that function, OR it fixes when the comment block was added to document that function, right? So either way, it does "Fix" something... thanks, greg k-h
On 2025/5/6 00:17, Greg KH wrote:
> On Mon, May 05, 2025 at 11:43:05PM +0800, Hans Zhang wrote:
>>
>>
>> On 2025/5/5 23:35, Hans Zhang wrote:
>>>
>>>
>>> On 2025/5/5 13:00, Greg KH wrote:
>>>> On Mon, May 05, 2025 at 12:04:15AM +0800, Hans Zhang wrote:
>>>>> Fix kernel-doc warning by documenting the @desc parameter:
>>>>>
>>>>> drivers/usb/host/xhci.c:1369: warning: Function parameter or
>>>>> struct member
>>>>> 'desc' not described in 'xhci_get_endpoint_index'
>>>>>
>>>>> Add detailed description of the @desc parameter and clarify the indexing
>>>>> logic for control endpoints vs other types. This brings the
>>>>> documentation
>>>>> in line with kernel-doc requirements while maintaining technical
>>>>> accuracy.
>>>>>
>>>>> Signed-off-by: Hans Zhang <18255117159@163.com>
>>>>
>>>> What commit id does this fix?
>>>>
>>>
>>> Hi Greg,
>>>
>>> export ARCH=arm64
>>> make defconfig
>>> make Image W=1 -j16
>>>
>>> ./aarch64-none-linux-gnu-gcc -v
>>> Using built-in specs.
>>> COLLECT_GCC=./aarch64-none-linux-gnu-gcc
>>> COLLECT_LTO_WRAPPER=/media/zhb/hans/code/cix_linux_gcc/arm-gnu-toolchain-12.3.rel1-x86_64-aarch64-none-linux-gnu/bin/../libexec/gcc/aarch64-none-linux-gnu/12.3.1/lto-wrapper
>>> Target: aarch64-none-linux-gnu
>>> Configured with:
>>> /data/jenkins/workspace/GNU-toolchain/arm-12/src/gcc/configure
>>> --target=aarch64-none-linux-gnu --prefix=
>>> --with-sysroot=/aarch64-none-linux-gnu/libc --with-build-sysroot=/data/jenkins/workspace/GNU-toolchain/arm-12/build-aarch64-none-linux-gnu/install//aarch64-none-linux-gnu/libc
>>> --with-bugurl=https://bugs.linaro.org/ --enable-gnu-indirect-function
>>> --enable-shared --disable-libssp --disable-libmudflap
>>> --enable-checking=release --enable-languages=c,c++,fortran --with-gmp=/data/jenkins/workspace/GNU-toolchain/arm-12/build-aarch64-none-linux-gnu/host-tools --with-mpfr=/data/jenkins/workspace/GNU-toolchain/arm-12/build-aarch64-none-linux-gnu/host-tools --with-mpc=/data/jenkins/workspace/GNU-toolchain/arm-12/build-aarch64-none-linux-gnu/host-tools --with-isl=/data/jenkins/workspace/GNU-toolchain/arm-12/build-aarch64-none-linux-gnu/host-tools
>>> --enable-fix-cortex-a53-843419 --with-pkgversion='Arm GNU Toolchain
>>> 12.3.Rel1 (Build arm-12.35)'
>>> Thread model: posix
>>> Supported LTO compression algorithms: zlib
>>> gcc version 12.3.1 20230626 (Arm GNU Toolchain 12.3.Rel1 (Build arm-12.35))
>>>
>>>
>>> I'm debugging the problem of pci and modified the iinclude/linux/pci.h
>>> file. If the above compilation method is adopted, the following warnings
>>> will occur. Use my patch and the warning disappears.
>>>
>>> Compilation warning:
>>> drivers/usb/host/xhci.c:1370: warning: Function parameter or struct
>>> member 'desc' not described in 'xhci_get_endpoint_index'
>>>
>>>
>>> The reproduction method can also be modified by modifying the
>>> drivers/usb/host/xhci.c file and then compiling, and the above warning
>>> will appear.
>>>
>>> Please review whether this needs to be fixed. If not, please ignore this
>>> patch.
>>>
>>>
>>
>> Hi Greg,
>>
>> This patch does not fix specific code errors. Instead, it improves the
>> parameter documentation of the xhci_get_endpoint_index function (adding a
>> description for @desc) to enhance code readability. Therefore, it does not
>> fix any issues with historical submissions and is an independent document
>> improvement patch.
>
> It fixes when that parameter was added to that function, OR it fixes
> when the comment block was added to document that function, right? So
> either way, it does "Fix" something...
>
Hi Greg,
Thank you for the feedback. This patch adds the missing documentation
for the `@desc` parameter in the `xhci_get_endpoint_index` function,
which was introduced in commit <d0e96f5a71a0> ("usb: xhci: Control
transfer support.") but lacked proper parameter description.
In the next version, I will add:
Fixes: d0e96f5a71a0 ("USB: xhci: Control transfer support.")
Is that so? If not, please correct me.
Best regards,
Hans
© 2016 - 2026 Red Hat, Inc.