* [PATCH] xhci: Add missing parameter description to xhci_get_endpoint_index() @ 2025-05-04 16:04 Hans Zhang 2025-05-05 5:00 ` Greg KH 0 siblings, 1 reply; 6+ messages in thread From: Hans Zhang @ 2025-05-04 16:04 UTC (permalink / raw) To: mathias.nyman, gregkh; +Cc: linux-usb, linux-kernel, Hans Zhang 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.1 ^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [PATCH] xhci: Add missing parameter description to xhci_get_endpoint_index() 2025-05-04 16:04 [PATCH] xhci: Add missing parameter description to xhci_get_endpoint_index() Hans Zhang @ 2025-05-05 5:00 ` Greg KH 2025-05-05 15:35 ` Hans Zhang 0 siblings, 1 reply; 6+ messages in thread From: Greg KH @ 2025-05-05 5:00 UTC (permalink / raw) To: Hans Zhang; +Cc: mathias.nyman, linux-usb, linux-kernel 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? thanks, greg k-h ^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [PATCH] xhci: Add missing parameter description to xhci_get_endpoint_index() 2025-05-05 5:00 ` Greg KH @ 2025-05-05 15:35 ` Hans Zhang 2025-05-05 15:43 ` Hans Zhang 0 siblings, 1 reply; 6+ messages in thread From: Hans Zhang @ 2025-05-05 15:35 UTC (permalink / raw) To: Greg KH; +Cc: mathias.nyman, linux-usb, linux-kernel 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 ^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [PATCH] xhci: Add missing parameter description to xhci_get_endpoint_index() 2025-05-05 15:35 ` Hans Zhang @ 2025-05-05 15:43 ` Hans Zhang 2025-05-05 16:17 ` Greg KH 0 siblings, 1 reply; 6+ messages in thread From: Hans Zhang @ 2025-05-05 15:43 UTC (permalink / raw) To: Greg KH; +Cc: mathias.nyman, linux-usb, linux-kernel 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 ^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [PATCH] xhci: Add missing parameter description to xhci_get_endpoint_index() 2025-05-05 15:43 ` Hans Zhang @ 2025-05-05 16:17 ` Greg KH 2025-05-05 16:30 ` Hans Zhang 0 siblings, 1 reply; 6+ messages in thread From: Greg KH @ 2025-05-05 16:17 UTC (permalink / raw) To: Hans Zhang; +Cc: mathias.nyman, linux-usb, linux-kernel 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 ^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [PATCH] xhci: Add missing parameter description to xhci_get_endpoint_index() 2025-05-05 16:17 ` Greg KH @ 2025-05-05 16:30 ` Hans Zhang 0 siblings, 0 replies; 6+ messages in thread From: Hans Zhang @ 2025-05-05 16:30 UTC (permalink / raw) To: Greg KH; +Cc: mathias.nyman, linux-usb, linux-kernel 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 ^ permalink raw reply [flat|nested] 6+ messages in thread
end of thread, other threads:[~2025-05-05 16:30 UTC | newest] Thread overview: 6+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- 2025-05-04 16:04 [PATCH] xhci: Add missing parameter description to xhci_get_endpoint_index() Hans Zhang 2025-05-05 5:00 ` Greg KH 2025-05-05 15:35 ` Hans Zhang 2025-05-05 15:43 ` Hans Zhang 2025-05-05 16:17 ` Greg KH 2025-05-05 16:30 ` Hans Zhang
This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox
all inboxes | Powered by JetHome®