kernel-doc headers for assembly language functions

kernel-doc headers for assembly language functions

[Elliott, Robert (Servers)]

Is there a recommended way to document assembly language functions
with the kernel-doc format?

scripts/kernel-doc doesn't understand assembly language files and
using SYM_FUNC_START to identify a function entry point. Unlike
a C function header, that line just identifies the function name,
not any of the arguments.

Example: arch/x86/crypto/crc32c-pcl-intel-asm_64.S provides a
function for use by C code:

    # unsigned int crc_pcl(u8 *buffer, int len, unsigned int crc_init);

    .text
    SYM_FUNC_START(crc_pcl)

Most of them have the recommended C prototype as a comment
somewhere nearby.

arch/x86/crypto/crc32c-intel_glue.c has a prototype for it (not in
a .h file):
    asmlinkage unsigned int crc_pcl(const u8 *buffer, int len,
                                    unsigned int crc_init);
    ...
        *crcp = crc_pcl(data, len, *crcp);

Perhaps scripts/kernel-doc could detect a special "Prototype" line
or look for a comment starting with "asmlinkage", something like:

/**
 * crc_pcl - Calculate crc32c using x86 CRC32 and PCLMULQDQ instructions
 * @buffer:   %rdi address of data
 * @len:      %rsi number of bytes of data
 * @crc_init: %rdx initial crc32c value
 * Return:    %eax crc32c checksum
 * Prototype: asmlinkage unsigned int crc_pcl(const u8 *buffer, int len, unsigned int crc_init);
 */
SYM_FUNC_START(crc_pcl)

Re: kernel-doc headers for assembly language functions

[Jonathan Corbet]

"Elliott, Robert (Servers)" <elliott@hpe.com> writes:

> Is there a recommended way to document assembly language functions
> with the kernel-doc format?
>
> scripts/kernel-doc doesn't understand assembly language files and
> using SYM_FUNC_START to identify a function entry point. Unlike
> a C function header, that line just identifies the function name,
> not any of the arguments.

As you note, it doesn't work currently.  The most common way of dealing
with this, I think, is to put the kerneldoc comments with the declaration
of the function that is (usually) found in a C header file somewhere.

Thanks,

jon