dmaengine: ti-cppi5: fix all kernel-doc warnings

Add missing struct member, function parameter, and enum value descriptions.
Add missing function Returns: sections.
Use correct function name in kernel-doc to avoid mismatched prototypes.

These repair all kernel-doc warnings in ti-cppi5.h:

Warning: include/linux/dma/ti-cppi5.h:27 struct member 'pkt_info1' not
described in 'cppi5_desc_hdr_t'
Warning: include/linux/dma/ti-cppi5.h:27 struct member 'pkt_info2' not
described in 'cppi5_desc_hdr_t'
Warning: include/linux/dma/ti-cppi5.h:50 struct member 'epib' not
described in 'cppi5_host_desc_t'
Warning: include/linux/dma/ti-cppi5.h:142 struct member 'epib' not
described in 'cppi5_monolithic_desc_t'
Warning: include/linux/dma/ti-cppi5.h:413 function parameter 'pkt_len'
not described in 'cppi5_hdesc_set_pktlen'
Warning: include/linux/dma/ti-cppi5.h:436 function parameter 'ps_flags'
not described in 'cppi5_hdesc_set_psflags'
Warning: include/linux/dma/ti-cppi5.h:509 function parameter 'hbuf_desc'
not described in 'cppi5_hdesc_link_hbdesc'
Warning: include/linux/dma/ti-cppi5.h:839 struct member 'dicnt3' not
described in 'cppi5_tr_type15_t'
Warning: include/linux/dma/ti-cppi5.h:970 function parameter 'desc_hdr'
not described in 'cppi5_trdesc_init'
Warning: include/linux/dma/ti-cppi5.h:184 No description found for
return value of 'cppi5_desc_is_tdcm'
Warning: include/linux/dma/ti-cppi5.h:198 No description found for
return value of 'cppi5_desc_get_type'
Warning: include/linux/dma/ti-cppi5.h:210 No description found for
return value of 'cppi5_desc_get_errflags'
Warning: include/linux/dma/ti-cppi5.h:448 expecting prototype for
cppi5_hdesc_get_errflags(). Prototype was for cppi5_hdesc_get_pkttype()
instead
Warning: include/linux/dma/ti-cppi5.h:460 expecting prototype for
cppi5_hdesc_get_errflags(). Prototype was for cppi5_hdesc_set_pkttype()
instead
Warning: include/linux/dma/ti-cppi5.h:1053 expecting prototype for
cppi5_tr_cflag_set(). Prototype was for cppi5_tr_csf_set() instead
Warning: include/linux/dma/ti-cppi5.h:651 Enum value 'CPPI5_TR_TYPE_MAX'
not described in enum 'cppi5_tr_types'
Warning: include/linux/dma/ti-cppi5.h:676 Enum value
'CPPI5_TR_EVENT_SIZE_MAX' not described in enum 'cppi5_tr_event_size'
Warning: include/linux/dma/ti-cppi5.h:693 Enum value 'CPPI5_TR_TRIGGER_MAX'
not described in enum 'cppi5_tr_trigger'
Warning: include/linux/dma/ti-cppi5.h:714 Enum value
'CPPI5_TR_TRIGGER_TYPE_MAX' not described in enum 'cppi5_tr_trigger_type'
Warning: include/linux/dma/ti-cppi5.h:890 Enum value
'CPPI5_TR_RESPONSE_STATUS_MAX' not described in enum
'cppi5_tr_resp_status_type'
Warning: include/linux/dma/ti-cppi5.h:906 Enum value
'CPPI5_TR_RESPONSE_STATUS_SUBMISSION_MAX' not described in enum
'cppi5_tr_resp_status_submission'
Warning: include/linux/dma/ti-cppi5.h:934 Enum value
'CPPI5_TR_RESPONSE_STATUS_UNSUPPORTED_MAX' not described in enum
'cppi5_tr_resp_status_unsupported'

Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Link: https://patch.msgid.link/20260301011213.3063688-1-rdunlap@infradead.org
Signed-off-by: Vinod Koul <vkoul@kernel.org>

authored by

Randy Dunlap and committed by

Vinod Koul 3 months ago 70fbea9f fe8a56f0

+33 -20

1 changed file

expand all

include

linux

dma

ti-cppi5.h

+33 -20

include/linux/dma/ti-cppi5.h

··· 16 16 * struct cppi5_desc_hdr_t - Descriptor header, present in all types of 17 17 * descriptors 18 18 * @pkt_info0: Packet info word 0 (n/a in Buffer desc) 19 - * @pkt_info0: Packet info word 1 (n/a in Buffer desc) 20 - * @pkt_info0: Packet info word 2 (n/a in Buffer desc) 19 + * @pkt_info1: Packet info word 1 (n/a in Buffer desc) 20 + * @pkt_info2: Packet info word 2 (n/a in Buffer desc) 21 21 * @src_dst_tag: Packet info word 3 (n/a in Buffer desc) 22 22 */ 23 23 struct cppi5_desc_hdr_t { ··· 35 35 * @buf_info1: word 8: Buffer valid data length 36 36 * @org_buf_len: word 9: Original buffer length 37 37 * @org_buf_ptr: word 10/11: Original buffer pointer 38 - * @epib[0]: Extended Packet Info Data (optional, 4 words), and/or 38 + * @epib: Extended Packet Info Data (optional, 4 words), and/or 39 39 * Protocol Specific Data (optional, 0-128 bytes in 40 40 * multiples of 4), and/or 41 41 * Other Software Data (0-N bytes, optional) ··· 132 132 /** 133 133 * struct cppi5_monolithic_desc_t - Monolithic-mode packet descriptor 134 134 * @hdr: Descriptor header 135 - * @epib[0]: Extended Packet Info Data (optional, 4 words), and/or 135 + * @epib: Extended Packet Info Data (optional, 4 words), and/or 136 136 * Protocol Specific Data (optional, 0-128 bytes in 137 137 * multiples of 4), and/or 138 138 * Other Software Data (0-N bytes, optional) ··· 179 179 * cppi5_desc_is_tdcm - check if the paddr indicates Teardown Complete Message 180 180 * @paddr: Physical address of the packet popped from the ring 181 181 * 182 - * Returns true if the address indicates TDCM 182 + * Returns: true if the address indicates TDCM 183 183 */ 184 184 static inline bool cppi5_desc_is_tdcm(dma_addr_t paddr) 185 185 { ··· 190 190 * cppi5_desc_get_type - get descriptor type 191 191 * @desc_hdr: packet descriptor/TR header 192 192 * 193 - * Returns descriptor type: 193 + * Returns: descriptor type: 194 194 * CPPI5_INFO0_DESC_TYPE_VAL_HOST 195 195 * CPPI5_INFO0_DESC_TYPE_VAL_MONO 196 196 * CPPI5_INFO0_DESC_TYPE_VAL_TR ··· 205 205 * cppi5_desc_get_errflags - get Error Flags from Desc 206 206 * @desc_hdr: packet/TR descriptor header 207 207 * 208 - * Returns Error Flags from Packet/TR Descriptor 208 + * Returns: Error Flags from Packet/TR Descriptor 209 209 */ 210 210 static inline u32 cppi5_desc_get_errflags(struct cppi5_desc_hdr_t *desc_hdr) 211 211 { ··· 307 307 * @psdata_size: PSDATA size 308 308 * @sw_data_size: SWDATA size 309 309 * 310 - * Returns required Host Packet Descriptor size 310 + * Returns: required Host Packet Descriptor size 311 311 * 0 - if PSDATA > CPPI5_INFO0_HDESC_PSDATA_MAX_SIZE 312 312 */ 313 313 static inline u32 cppi5_hdesc_calc_size(bool epib, u32 psdata_size, ··· 381 381 /** 382 382 * cppi5_hdesc_get_psdata_size - get PSdata size in bytes 383 383 * @desc: Host packet descriptor 384 + * 385 + * Returns: PSdata size in bytes 384 386 */ 385 387 static inline u32 cppi5_hdesc_get_psdata_size(struct cppi5_host_desc_t *desc) 386 388 { ··· 400 398 * cppi5_hdesc_get_pktlen - get Packet Length from HDesc 401 399 * @desc: Host packet descriptor 402 400 * 403 - * Returns Packet Length from Host Packet Descriptor 401 + * Returns: Packet Length from Host Packet Descriptor 404 402 */ 405 403 static inline u32 cppi5_hdesc_get_pktlen(struct cppi5_host_desc_t *desc) 406 404 { ··· 410 408 /** 411 409 * cppi5_hdesc_set_pktlen - set Packet Length in HDesc 412 410 * @desc: Host packet descriptor 411 + * @pkt_len: Packet length to set 413 412 */ 414 413 static inline void cppi5_hdesc_set_pktlen(struct cppi5_host_desc_t *desc, 415 414 u32 pkt_len) ··· 423 420 * cppi5_hdesc_get_psflags - get Protocol Specific Flags from HDesc 424 421 * @desc: Host packet descriptor 425 422 * 426 - * Returns Protocol Specific Flags from Host Packet Descriptor 423 + * Returns: Protocol Specific Flags from Host Packet Descriptor 427 424 */ 428 425 static inline u32 cppi5_hdesc_get_psflags(struct cppi5_host_desc_t *desc) 429 426 { ··· 434 431 /** 435 432 * cppi5_hdesc_set_psflags - set Protocol Specific Flags in HDesc 436 433 * @desc: Host packet descriptor 434 + * @ps_flags: Protocol Specific flags to set 437 435 */ 438 436 static inline void cppi5_hdesc_set_psflags(struct cppi5_host_desc_t *desc, 439 437 u32 ps_flags) ··· 446 442 } 447 443 448 444 /** 449 - * cppi5_hdesc_get_errflags - get Packet Type from HDesc 445 + * cppi5_hdesc_get_pkttype - get Packet Type from HDesc 450 446 * @desc: Host packet descriptor 447 + * 448 + * Returns: Packet type 451 449 */ 452 450 static inline u32 cppi5_hdesc_get_pkttype(struct cppi5_host_desc_t *desc) 453 451 { ··· 458 452 } 459 453 460 454 /** 461 - * cppi5_hdesc_get_errflags - set Packet Type in HDesc 455 + * cppi5_hdesc_set_pkttype - set Packet Type in HDesc 462 456 * @desc: Host packet descriptor 463 457 * @pkt_type: Packet Type 464 458 */ ··· 507 501 /** 508 502 * cppi5_hdesc_link_hbdesc - link Host Buffer Descriptor to HDesc 509 503 * @desc: Host Packet Descriptor 510 - * @buf_desc: Host Buffer Descriptor physical address 504 + * @hbuf_desc: Host Buffer Descriptor physical address 511 505 * 512 506 * add and link Host Buffer Descriptor to HDesc 513 507 */ ··· 533 527 * cppi5_hdesc_epib_present - check if EPIB present 534 528 * @desc_hdr: packet descriptor/TR header 535 529 * 536 - * Returns true if EPIB present in the packet 530 + * Returns: true if EPIB present in the packet 537 531 */ 538 532 static inline bool cppi5_hdesc_epib_present(struct cppi5_desc_hdr_t *desc_hdr) 539 533 { ··· 544 538 * cppi5_hdesc_get_psdata - Get pointer on PSDATA 545 539 * @desc: Host packet descriptor 546 540 * 547 - * Returns pointer on PSDATA in HDesc. 541 + * Returns: pointer on PSDATA in HDesc. 548 542 * NULL - if ps_data placed at the start of data buffer. 549 543 */ 550 544 static inline void *cppi5_hdesc_get_psdata(struct cppi5_host_desc_t *desc) ··· 574 568 * cppi5_hdesc_get_swdata - Get pointer on swdata 575 569 * @desc: Host packet descriptor 576 570 * 577 - * Returns pointer on SWDATA in HDesc. 571 + * Returns: pointer on SWDATA in HDesc. 578 572 * NOTE. It's caller responsibility to be sure hdesc actually has swdata. 579 573 */ 580 574 static inline void *cppi5_hdesc_get_swdata(struct cppi5_host_desc_t *desc) ··· 654 648 CPPI5_TR_TYPE11, 655 649 /* type12-14: Reserved */ 656 650 CPPI5_TR_TYPE15 = 15, 651 + /* private: */ 657 652 CPPI5_TR_TYPE_MAX 658 653 }; 659 654 ··· 680 673 CPPI5_TR_EVENT_SIZE_ICNT1_DEC, 681 674 CPPI5_TR_EVENT_SIZE_ICNT2_DEC, 682 675 CPPI5_TR_EVENT_SIZE_ICNT3_DEC, 676 + /* private: */ 683 677 CPPI5_TR_EVENT_SIZE_MAX 684 678 }; 685 679 ··· 698 690 CPPI5_TR_TRIGGER_GLOBAL0, 699 691 CPPI5_TR_TRIGGER_GLOBAL1, 700 692 CPPI5_TR_TRIGGER_LOCAL_EVENT, 693 + /* private: */ 701 694 CPPI5_TR_TRIGGER_MAX 702 695 }; 703 696 ··· 720 711 CPPI5_TR_TRIGGER_TYPE_ICNT2_DEC, 721 712 CPPI5_TR_TRIGGER_TYPE_ICNT3_DEC, 722 713 CPPI5_TR_TRIGGER_TYPE_ALL, 714 + /* private: */ 723 715 CPPI5_TR_TRIGGER_TYPE_MAX 724 716 }; 725 717 ··· 825 815 * destination 826 816 * @dicnt1: Total loop iteration count for level 1 for destination 827 817 * @dicnt2: Total loop iteration count for level 2 for destination 828 - * @sicnt3: Total loop iteration count for level 3 (outermost) for 818 + * @dicnt3: Total loop iteration count for level 3 (outermost) for 829 819 * destination 830 820 */ 831 821 struct cppi5_tr_type15_t { ··· 897 887 CPPI5_TR_RESPONSE_STATUS_UNSUPPORTED_ERR, 898 888 CPPI5_TR_RESPONSE_STATUS_TRANSFER_EXCEPTION, 899 889 CPPI5_TR_RESPONSE_STATUS__TEARDOWN_FLUSH, 890 + /* private: */ 900 891 CPPI5_TR_RESPONSE_STATUS_MAX 901 892 }; 902 893 ··· 914 903 CPPI5_TR_RESPONSE_STATUS_SUBMISSION_ICNT0, 915 904 CPPI5_TR_RESPONSE_STATUS_SUBMISSION_FIFO_FULL, 916 905 CPPI5_TR_RESPONSE_STATUS_SUBMISSION_OWN, 906 + /* private: */ 917 907 CPPI5_TR_RESPONSE_STATUS_SUBMISSION_MAX 918 908 }; 919 909 ··· 943 931 CPPI5_TR_RESPONSE_STATUS_UNSUPPORTED_DFMT, 944 932 CPPI5_TR_RESPONSE_STATUS_UNSUPPORTED_SECTR, 945 933 CPPI5_TR_RESPONSE_STATUS_UNSUPPORTED_AMODE_SPECIFIC, 934 + /* private: */ 946 935 CPPI5_TR_RESPONSE_STATUS_UNSUPPORTED_MAX 947 936 }; 948 937 ··· 952 939 * @tr_count: number of TR records 953 940 * @tr_size: Nominal size of TR record (max) [16, 32, 64, 128] 954 941 * 955 - * Returns required TR Descriptor size 942 + * Returns: required TR Descriptor size 956 943 */ 957 944 static inline size_t cppi5_trdesc_calc_size(u32 tr_count, u32 tr_size) 958 945 { ··· 968 955 969 956 /** 970 957 * cppi5_trdesc_init - Init TR Descriptor 971 - * @desc: TR Descriptor 958 + * @desc_hdr: TR Descriptor 972 959 * @tr_count: number of TR records 973 960 * @tr_size: Nominal size of TR record (max) [16, 32, 64, 128] 974 961 * @reload_idx: Absolute index to jump to on the 2nd and following passes ··· 1057 1044 } 1058 1045 1059 1046 /** 1060 - * cppi5_tr_cflag_set - Update the Configuration specific flags 1047 + * cppi5_tr_csf_set - Update the Configuration specific flags 1061 1048 * @flags: Pointer to the TR's flags 1062 1049 * @csf: Configuration specific flags 1063 1050 *

Configure Feed

Configure Feed