| Message ID | 20210722021843.2336117-1-willy@infradead.org (mailing list archive) |
|---|---|
| State | New |
| Headers | show |
| Series | mm/doc: Include highmem.h in kernel-doc | expand |
On Thu, 22 Jul 2021 03:18:42 +0100 "Matthew Wilcox (Oracle)" <willy@infradead.org> wrote: > There is lots of good documentation in highmem.h that isn't being pulled > into the html documentation. Fix up a couple of minor glitches and > include it. > > --- a/include/linux/highmem.h > +++ b/include/linux/highmem.h > > ... > > @@ -156,6 +156,7 @@ static inline void *kmap_atomic(struct page *page); > * the side effects of kmap_atomic(), i.e. reenabling pagefaults and > * preemption. > */ > +static inline void kunmap_atomic(void *addr); > > /* Highmem related interfaces for management code */ > static inline unsigned int nr_free_highpages(void); This hunk broke the i386 allmodconfig build. In file included from ./include/linux/highmem.h:14, from ./include/linux/bio.h:8, from ./include/linux/blkdev.h:18, from ./include/linux/blk-cgroup.h:23, from ./include/linux/writeback.h:14, from ./include/linux/memcontrol.h:22, from ./include/linux/swap.h:9, from ./include/linux/suspend.h:5, from arch/x86/kernel/asm-offsets.c:13: ./include/linux/highmem-internal.h:216:1: error: expected identifier or '(' before 'do' 216 | do { \ | ^~ ./include/linux/highmem.h:122:20: note: in expansion of macro 'kunmap_atomic' 122 | static inline void kunmap_atomic(void *addr); | ^~~~~~~~~~~~~ ./include/linux/highmem-internal.h:219:3: error: expected identifier or '(' before 'while' 219 | } while (0) | ^~~~~ ./include/linux/highmem.h:122:20: note: in expansion of macro 'kunmap_atomic' 122 | static inline void kunmap_atomic(void *addr); | ^~~~~~~~~~~~~ make[1]: *** [scripts/Makefile.build:117: arch/x86/kernel/asm-offsets.s] Error 1 make: *** [Makefile:1213: prepare0] Error 2 I think I can see what you were trying to do there. How about we instead move the kunmap_atomic() kerneldoc to an appropriate place?
diff --git a/Documentation/core-api/mm-api.rst b/Documentation/core-api/mm-api.rst index 395835f9289f..2027aee5f2d9 100644 --- a/Documentation/core-api/mm-api.rst +++ b/Documentation/core-api/mm-api.rst @@ -54,6 +54,7 @@ Virtually Contiguous Mappings .. kernel-doc:: mm/vmalloc.c :export: +.. kernel-doc:: include/linux/highmem.h File Mapping and Page Cache =========================== diff --git a/include/linux/highmem.h b/include/linux/highmem.h index 861ad00fb32a..fc43e81cf4db 100644 --- a/include/linux/highmem.h +++ b/include/linux/highmem.h @@ -37,8 +37,8 @@ static inline void *kmap(struct page *page); /** - * kunmap - Unmap the virtual address mapped by kmap() - * @addr: Virtual address to be unmapped + * kunmap - Unmap the page mapped by kmap() + * @page: Page to be unmapped * * Counterpart to kmap(). A NOOP for CONFIG_HIGHMEM=n and for mappings of * pages in the low memory area. @@ -69,13 +69,13 @@ static inline void kmap_flush_unused(void); * * Requires careful handling when nesting multiple mappings because the map * management is stack based. The unmap has to be in the reverse order of - * the map operation: + * the map operation:: * - * addr1 = kmap_local_page(page1); - * addr2 = kmap_local_page(page2); - * ... - * kunmap_local(addr2); - * kunmap_local(addr1); + * addr1 = kmap_local_page(page1); + * addr2 = kmap_local_page(page2); + * ... + * kunmap_local(addr2); + * kunmap_local(addr1); * * Unmapping addr1 before addr2 is invalid and causes malfunction. * @@ -156,6 +156,7 @@ static inline void *kmap_atomic(struct page *page); * the side effects of kmap_atomic(), i.e. reenabling pagefaults and * preemption. */ +static inline void kunmap_atomic(void *addr); /* Highmem related interfaces for management code */ static inline unsigned int nr_free_highpages(void);
There is lots of good documentation in highmem.h that isn't being pulled into the html documentation. Fix up a couple of minor glitches and include it. Signed-off-by: Matthew Wilcox (Oracle) <willy@infradead.org> --- Documentation/core-api/mm-api.rst | 1 + include/linux/highmem.h | 17 +++++++++-------- 2 files changed, 10 insertions(+), 8 deletions(-)