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)
