Skip to content

[libc][docgen] support non-top-level headers #119621

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 7 commits into from
Dec 12, 2024
Merged

[libc][docgen] support non-top-level headers #119621

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
fa78e88
[libc][docgen] support non-top-level headers
nickdesaulniers Dec 11, 2024
4e0f51e
add arpa/inet and sys/mman
nickdesaulniers Dec 11, 2024
c760151
print check path correctly
nickdesaulniers Dec 11, 2024
909fd85
support for macros
nickdesaulniers Dec 11, 2024
b6698a5
regen headers
nickdesaulniers Dec 11, 2024
21a1130
appease linter
nickdesaulniers Dec 11, 2024
ba1d748
return type for get_choices
nickdesaulniers Dec 11, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 50 additions & 0 deletions libc/docs/headers/arpa/inet.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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|
-
-
2 changes: 2 additions & 0 deletions libc/docs/headers/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@ Implementation Status
.. toctree::
:maxdepth: 1

arpa/inet
assert
complex
ctype
Expand All @@ -21,6 +22,7 @@ Implementation Status
stdlib
string
strings
sys/mman
threads
time
uchar
Expand Down
179 changes: 179 additions & 0 deletions libc/docs/headers/sys/mman.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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|
-
-
28 changes: 28 additions & 0 deletions libc/utils/docgen/arpa/inet.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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": ""
}
}
}
24 changes: 20 additions & 4 deletions libc/utils/docgen/docgen.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -161,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)
Expand All @@ -176,10 +180,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() -> List:
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more. 

Traceback (most recent call last):
  File "/android0/llvm-project/./libc/utils/docgen/docgen.py", line 186, in <module>
    def get_choices() -> List:
                         ^^^^
NameError: name 'List' is not defined. Did you mean: 'list'?

sigh...

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

52db903

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()


Expand Down
7 changes: 6 additions & 1 deletion libc/utils/docgen/header.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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")
43 changes: 43 additions & 0 deletions libc/utils/docgen/sys/mman.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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": "" }
}
}
Loading