Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20;
Date:   Thu, 28 Apr 2022 11:11:46 +0200
From:   Sebastian Andrzej Siewior <bigeasy@linutronix.de>
To:     "Fabio M. De Francesco" <fmdefrancesco@gmail.com>
Cc:     Ira Weiny <ira.weiny@intel.com>,
        Andrew Morton <akpm@linux-foundation.org>,
        Catalin Marinas <catalin.marinas@arm.com>,
        "Matthew Wilcox (Oracle)" <willy@infradead.org>,
        Will Deacon <will@kernel.org>,
        Peter Collingbourne <pcc@google.com>,
        Vlastimil Babka <vbabka@suse.cz>, linux-kernel@vger.kernel.org,
        linux-doc@vger.kernel.org, outreachy@lists.linux.dev,
        Mike Rapoport <rppt@linux.ibm.com>
Subject: Re: [PATCH v3 1/4] mm/highmem: Fix kernel-doc warnings in highmem*.h
Message-ID: <YmpaUgxIk0rrwt2G@linutronix.de>
References: <20220427183821.1979-1-fmdefrancesco@gmail.com>
 <20220427183821.1979-2-fmdefrancesco@gmail.com>
MIME-Version: 1.0
Content-Type: text/plain; charset=utf-8
Content-Disposition: inline
Content-Transfer-Encoding: quoted-printable
In-Reply-To: <20220427183821.1979-2-fmdefrancesco@gmail.com>
Precedence: bulk

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; }
> =20
>  #endif /* CONFIG_HIGHMEM */
> =20
> -/*
> - * Prevent people trying to call kunmap_atomic() as if it were kunmap()
> - * kunmap_atomic() should get the return value of kmap_atomic, not the p=
age.
> +/**
> + * kunmap_atomic - Unmap the virtual address mapped by kmap_atomic() - d=
eprecated!
> + * @__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.
=E2=80=A6
> --- 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 pagefau=
lts
> - * 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