[libc-commits] [libc] [libc][docgen] basic support for non-top-level headers (PR #119621)
Nick Desaulniers via libc-commits
libc-commits at lists.llvm.org
Wed Dec 11 14:20:32 PST 2024
https://github.com/nickdesaulniers updated https://github.com/llvm/llvm-project/pull/119621
>From fa78e8858d67525f8395485c69e8677c4da6d174 Mon Sep 17 00:00:00 2001
From: Nick Desaulniers <ndesaulniers at google.com>
Date: Wed, 11 Dec 2024 12:54:13 -0800
Subject: [PATCH 1/6] [libc][docgen] support non-top-level headers
such as arpa/inet, sys/*
---
libc/utils/docgen/docgen.py | 19 ++++++++++++++++---
1 file changed, 16 insertions(+), 3 deletions(-)
diff --git a/libc/utils/docgen/docgen.py b/libc/utils/docgen/docgen.py
index aa30a6e51ef870..24c115d4d8e79d 100755
--- a/libc/utils/docgen/docgen.py
+++ b/libc/utils/docgen/docgen.py
@@ -10,8 +10,9 @@
from argparse import ArgumentParser, Namespace
from pathlib import Path
from typing import Dict
-import sys
import json
+import os
+import sys
from header import Header
@@ -176,10 +177,22 @@ def print_impl_status_rst(header: Header, api: Dict):
print_functions_rst(header, api["functions"])
+# This code implicitly relies on docgen.py being in the same dir as the json
+# files and is likely to need to be fixed when re-integrating docgen into
+# hdrgen.
+def get_choices():
+ choices = []
+ for path in Path(__file__).parent.rglob("*.json"):
+ fname = path.with_suffix(".h").name
+ if path.parent != Path(__file__).parent:
+ fname = path.parent.name + os.sep + fname
+ choices.append(fname)
+ return choices
+
+
def parse_args() -> Namespace:
parser = ArgumentParser()
- choices = [p.with_suffix(".h").name for p in Path(__file__).parent.glob("*.json")]
- parser.add_argument("header_name", choices=choices)
+ parser.add_argument("header_name", choices=get_choices())
return parser.parse_args()
>From 4e0f51e179ea2ee87e39b4064608747ece425b36 Mon Sep 17 00:00:00 2001
From: Nick Desaulniers <ndesaulniers at google.com>
Date: Wed, 11 Dec 2024 12:54:56 -0800
Subject: [PATCH 2/6] add arpa/inet and sys/mman
---
libc/utils/docgen/arpa/inet.json | 28 +++++++++++++++++++++
libc/utils/docgen/sys/mman.json | 43 ++++++++++++++++++++++++++++++++
2 files changed, 71 insertions(+)
create mode 100644 libc/utils/docgen/arpa/inet.json
create mode 100644 libc/utils/docgen/sys/mman.json
diff --git a/libc/utils/docgen/arpa/inet.json b/libc/utils/docgen/arpa/inet.json
new file mode 100644
index 00000000000000..0e788c57d5f7ae
--- /dev/null
+++ b/libc/utils/docgen/arpa/inet.json
@@ -0,0 +1,28 @@
+{
+ "functions": {
+ "htonl" : {
+ "posix-definition": ""
+ },
+ "htons": {
+ "posix-definition": ""
+ },
+ "ntohl": {
+ "posix-definition": ""
+ },
+ "ntohs": {
+ "posix-definition": ""
+ },
+ "inet_addr": {
+ "posix-definition": ""
+ },
+ "inet_ntoa": {
+ "posix-definition": ""
+ },
+ "inet_ntop": {
+ "posix-definition": ""
+ },
+ "inet_pton": {
+ "posix-definition": ""
+ }
+ }
+}
diff --git a/libc/utils/docgen/sys/mman.json b/libc/utils/docgen/sys/mman.json
new file mode 100644
index 00000000000000..59f904fcfea975
--- /dev/null
+++ b/libc/utils/docgen/sys/mman.json
@@ -0,0 +1,43 @@
+{
+ "macros": {
+ "PROT_EXEC": { "posix-definition": "" },
+ "PROT_NONE": { "posix-definition": "" },
+ "PROT_READ": { "posix-definition": "" },
+ "PROT_WRITE": { "posix-definition": "" },
+ "MAP_ANON": { "posix-definition": "" },
+ "MAP_ANONYMOUS": { "posix-definition": "" },
+ "MAP_FIXED": { "posix-definition": "" },
+ "MAP_PRIVATE": { "posix-definition": "" },
+ "MAP_SHARED": { "posix-definition": "" },
+ "MS_ASYNC": { "posix-definition": "" },
+ "MS_INVALIDATE": { "posix-definition": "" },
+ "MS_SYNC": { "posix-definition": "" },
+ "MCL_CURRENT": { "posix-definition": "" },
+ "MCL_FUTURE": { "posix-definition": "" },
+ "MAP_FAILED": { "posix-definition": "" },
+ "POSIX_MADV_DONTNEED": { "posix-definition": "" },
+ "POSIX_MADV_NORMAL": { "posix-definition": "" },
+ "POSIX_MADV_RANDOM": { "posix-definition": "" },
+ "POSIX_MADV_SEQUENTIAL": { "posix-definition": "" },
+ "POSIX_MADV_WILLNEED": { "posix-definition": "" },
+ "POSIX_TYPED_MEM_ALLOCATE": { "posix-definition": "" },
+ "POSIX_TYPED_MEM_ALLOCATE_CONTIG": { "posix-definition": "" },
+ "POSIX_TYPED_MEM_MAP_ALLOCATABLE": { "posix-definition": "" }
+ },
+ "functions": {
+ "mlock": { "posix-definition": "" },
+ "mlockall": { "posix-definition": "" },
+ "mmap": { "posix-definition": "" },
+ "mprotect": { "posix-definition": "" },
+ "msync": { "posix-definition": "" },
+ "munlock": { "posix-definition": "" },
+ "munlockall": { "posix-definition": "" },
+ "munmap": { "posix-definition": "" },
+ "posix_madvise": { "posix-definition": "" },
+ "posix_mem_offset": { "posix-definition": "" },
+ "posix_typed_mem_get_info": { "posix-definition": "" },
+ "posix_typed_mem_open": { "posix-definition": "" },
+ "shm_open": { "posix-definition": "" },
+ "shm_unlink": { "posix-definition": "" }
+ }
+}
>From c76015161d9782b6c7434d7d2e08f846d6224469 Mon Sep 17 00:00:00 2001
From: Nick Desaulniers <ndesaulniers at google.com>
Date: Wed, 11 Dec 2024 14:02:18 -0800
Subject: [PATCH 3/6] print check path correctly
---
libc/utils/docgen/docgen.py | 5 ++++-
1 file changed, 4 insertions(+), 1 deletion(-)
diff --git a/libc/utils/docgen/docgen.py b/libc/utils/docgen/docgen.py
index 24c115d4d8e79d..3bff93be708109 100755
--- a/libc/utils/docgen/docgen.py
+++ b/libc/utils/docgen/docgen.py
@@ -162,7 +162,10 @@ def print_macros_rst(header: Header, macros: Dict):
def print_impl_status_rst(header: Header, api: Dict):
- print(".. include:: ../check.rst\n")
+ if (os.sep in header.name):
+ print(".. include:: ../../check.rst\n")
+ else:
+ print(".. include:: ../check.rst\n")
print("=" * len(header.name))
print(header.name)
>From 909fd858a396f0d56ceeb26a730e8a502f0b24ac Mon Sep 17 00:00:00 2001
From: Nick Desaulniers <ndesaulniers at google.com>
Date: Wed, 11 Dec 2024 14:19:21 -0800
Subject: [PATCH 4/6] support for macros
---
libc/utils/docgen/header.py | 7 ++++++-
1 file changed, 6 insertions(+), 1 deletion(-)
diff --git a/libc/utils/docgen/header.py b/libc/utils/docgen/header.py
index dde210078db278..7728a0f1d5b44c 100644
--- a/libc/utils/docgen/header.py
+++ b/libc/utils/docgen/header.py
@@ -83,5 +83,10 @@ def __get_macro_files(self) -> Generator[Path, None, None]:
macro file might be located in a subdirectory:
libc/include/llvm-libc-macros/fcntl-macros.h
libc/include/llvm-libc-macros/linux/fcntl-macros.h
+
+ When a header would be nested in a dir (such as arpa/, sys/, etc) we
+ instead use a hyphen in the name.
+ libc/include/llvm-libc-macros/sys-mman-macros.h
"""
- return self.macros_dir.glob(f"**/{self.stem}-macros.h")
+ stem = self.stem.replace("/", "-")
+ return self.macros_dir.glob(f"**/{stem}-macros.h")
>From b6698a5b80bcecde74371c1c4995b3e0a78b7cdf Mon Sep 17 00:00:00 2001
From: Nick Desaulniers <ndesaulniers at google.com>
Date: Wed, 11 Dec 2024 13:32:10 -0800
Subject: [PATCH 5/6] regen headers
---
libc/docs/headers/arpa/inet.rst | 50 +++++++++
libc/docs/headers/index.rst | 2 +
libc/docs/headers/sys/mman.rst | 179 ++++++++++++++++++++++++++++++++
3 files changed, 231 insertions(+)
create mode 100644 libc/docs/headers/arpa/inet.rst
create mode 100644 libc/docs/headers/sys/mman.rst
diff --git a/libc/docs/headers/arpa/inet.rst b/libc/docs/headers/arpa/inet.rst
new file mode 100644
index 00000000000000..c82ca5427fbbb7
--- /dev/null
+++ b/libc/docs/headers/arpa/inet.rst
@@ -0,0 +1,50 @@
+.. include:: ../../check.rst
+
+===========
+arpa/inet.h
+===========
+
+Functions
+=========
+
+.. list-table::
+ :widths: auto
+ :align: center
+ :header-rows: 1
+
+ * - Function
+ - Implemented
+ - C23 Standard Section
+ - POSIX.1-2024 Standard Section
+ * - htonl
+ - |check|
+ -
+ -
+ * - htons
+ - |check|
+ -
+ -
+ * - inet_addr
+ -
+ -
+ -
+ * - inet_ntoa
+ -
+ -
+ -
+ * - inet_ntop
+ -
+ -
+ -
+ * - inet_pton
+ -
+ -
+ -
+ * - ntohl
+ - |check|
+ -
+ -
+ * - ntohs
+ - |check|
+ -
+ -
diff --git a/libc/docs/headers/index.rst b/libc/docs/headers/index.rst
index 9bd6396843e786..07ab6dd9b26742 100644
--- a/libc/docs/headers/index.rst
+++ b/libc/docs/headers/index.rst
@@ -4,6 +4,7 @@ Implementation Status
.. toctree::
:maxdepth: 1
+ arpa/inet
assert
complex
ctype
@@ -21,6 +22,7 @@ Implementation Status
stdlib
string
strings
+ sys/mman
threads
time
uchar
diff --git a/libc/docs/headers/sys/mman.rst b/libc/docs/headers/sys/mman.rst
new file mode 100644
index 00000000000000..e3404205c07aca
--- /dev/null
+++ b/libc/docs/headers/sys/mman.rst
@@ -0,0 +1,179 @@
+.. include:: ../../check.rst
+
+==========
+sys/mman.h
+==========
+
+Macros
+======
+
+.. list-table::
+ :widths: auto
+ :align: center
+ :header-rows: 1
+
+ * - Macro
+ - Implemented
+ - C23 Standard Section
+ - POSIX.1-2024 Standard Section
+ * - MAP_ANON
+ -
+ -
+ -
+ * - MAP_ANONYMOUS
+ -
+ -
+ -
+ * - MAP_FAILED
+ - |check|
+ -
+ -
+ * - MAP_FIXED
+ -
+ -
+ -
+ * - MAP_PRIVATE
+ -
+ -
+ -
+ * - MAP_SHARED
+ -
+ -
+ -
+ * - MCL_CURRENT
+ -
+ -
+ -
+ * - MCL_FUTURE
+ -
+ -
+ -
+ * - MS_ASYNC
+ -
+ -
+ -
+ * - MS_INVALIDATE
+ -
+ -
+ -
+ * - MS_SYNC
+ -
+ -
+ -
+ * - POSIX_MADV_DONTNEED
+ - |check|
+ -
+ -
+ * - POSIX_MADV_NORMAL
+ - |check|
+ -
+ -
+ * - POSIX_MADV_RANDOM
+ - |check|
+ -
+ -
+ * - POSIX_MADV_SEQUENTIAL
+ - |check|
+ -
+ -
+ * - POSIX_MADV_WILLNEED
+ - |check|
+ -
+ -
+ * - POSIX_TYPED_MEM_ALLOCATE
+ -
+ -
+ -
+ * - POSIX_TYPED_MEM_ALLOCATE_CONTIG
+ -
+ -
+ -
+ * - POSIX_TYPED_MEM_MAP_ALLOCATABLE
+ -
+ -
+ -
+ * - PROT_EXEC
+ -
+ -
+ -
+ * - PROT_NONE
+ -
+ -
+ -
+ * - PROT_READ
+ -
+ -
+ -
+ * - PROT_WRITE
+ -
+ -
+ -
+
+Functions
+=========
+
+.. list-table::
+ :widths: auto
+ :align: center
+ :header-rows: 1
+
+ * - Function
+ - Implemented
+ - C23 Standard Section
+ - POSIX.1-2024 Standard Section
+ * - mlock
+ - |check|
+ -
+ -
+ * - mlockall
+ - |check|
+ -
+ -
+ * - mmap
+ - |check|
+ -
+ -
+ * - mprotect
+ - |check|
+ -
+ -
+ * - msync
+ - |check|
+ -
+ -
+ * - munlock
+ - |check|
+ -
+ -
+ * - munlockall
+ - |check|
+ -
+ -
+ * - munmap
+ - |check|
+ -
+ -
+ * - posix_madvise
+ - |check|
+ -
+ -
+ * - posix_mem_offset
+ -
+ -
+ -
+ * - posix_typed_mem_get_info
+ -
+ -
+ -
+ * - posix_typed_mem_open
+ -
+ -
+ -
+ * - shm_open
+ - |check|
+ -
+ -
+ * - shm_unlink
+ - |check|
+ -
+ -
>From 21a1130076e718b75c0005db9ed6721ae161395b Mon Sep 17 00:00:00 2001
From: Nick Desaulniers <ndesaulniers at google.com>
Date: Wed, 11 Dec 2024 14:20:09 -0800
Subject: [PATCH 6/6] appease linter
---
libc/utils/docgen/docgen.py | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/libc/utils/docgen/docgen.py b/libc/utils/docgen/docgen.py
index 3bff93be708109..9f95746b1d8ccf 100755
--- a/libc/utils/docgen/docgen.py
+++ b/libc/utils/docgen/docgen.py
@@ -162,7 +162,7 @@ def print_macros_rst(header: Header, macros: Dict):
def print_impl_status_rst(header: Header, api: Dict):
- if (os.sep in header.name):
+ if os.sep in header.name:
print(".. include:: ../../check.rst\n")
else:
print(".. include:: ../check.rst\n")
More information about the libc-commits
mailing list