kernel/api: add API specification for sys_madvise

Add KAPI-annotated kerneldoc for the sys_madvise system call in
mm/madvise.c.

The specification documents the parameters (start, len_in, behavior),
per-behavior error conditions, lock acquisition (mmap_lock read and
write modes plus the per-VMA fast path, mmu_gather and mmu_notifier
brackets), signal handling, side effects, capability requirements
(CAP_SYS_ADMIN for MADV_HWPOISON and MADV_SOFT_OFFLINE), mseal
interaction, and how each behavior skips pages or reports errors.

Assisted-by: LLM
Signed-off-by: Sasha Levin <sashal@kernel.org>