Re: [PATCH v3 1/4] mm/highmem: Fix kernel-doc warnings in highmem*.h

[Sebastian Andrzej Siewior]

On 2022-04-27 20:38:18 [+0200], Fabio M. De Francesco wrote:
> --- a/include/linux/highmem-internal.h
> +++ b/include/linux/highmem-internal.h
> @@ -236,9 +236,18 @@ static inline unsigned long totalhigh_pages(void) { return 0UL; }
>  
>  #endif /* CONFIG_HIGHMEM */
>  
> -/*
> - * Prevent people trying to call kunmap_atomic() as if it were kunmap()
> - * kunmap_atomic() should get the return value of kmap_atomic, not the page.
> +/**
> + * kunmap_atomic - Unmap the virtual address mapped by kmap_atomic() - deprecated!
> + * @__addr:       Virtual address to be unmapped
> + *
> + * Unmaps an address previously mapped by kmap_atomic() and re-enables
> + * pagefaults, migration, preemption (the latter was disabled only for
> + * !PREEMP_RT configurations). Mappings should be unmapped in the reverse

Not sure how detailed you want to put it here as "reverses kmap_atomic()
doing." might be okay ;) This indicates the "migration" is disabled for
!PREEMPT_RT which is not the case. So maybe something like

 * Unmaps an address previously mapped by kmap_atomic() and re-enables
 * pagefaults, CPU migration (CONFIG_PREEMPT_RT) or preemption
 * (!CONFIG_PREEMPT_RT). Mappings should be unmapped in the reverse

will make it clear.
…
> --- a/include/linux/highmem.h
> +++ b/include/linux/highmem.h
> @@ -138,24 +138,14 @@ static inline void *kmap_local_folio(struct folio *folio, size_t offset);
>   *
>   * Returns: The virtual address of the mapping
>   *
> - * Effectively a wrapper around kmap_local_page() which disables pagefaults
> - * and preemption.
> + * In fact a wrapper around kmap_local_page() which disables pagefaults,
> + * migration, preemption (the latter disabled only for !PREEMP_RT
> + * configurations).

and here.

Sebastian