blob: 9d9beb492a7edee2ddb7e4350e69389011cfb498 [file] [edit]
# ===----------------------------------------------------------------------===##
#
# Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
# See https://llvm.org/LICENSE.txt for license information.
# SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
#
# ===----------------------------------------------------------------------===##
from functools import lru_cache
from pathlib import Path
import re
from typing import Dict, Generator, Optional, Set, Tuple
import yaml
# Standard C freestanding headers (C23 4p6) provided directly by the compiler
# (clang/lib/Headers/) rather than generated by LLVM-libc. When building with
# Clang, their macros, types, and operations come from Clang's resource
# headers, so docgen treats them as implemented even when no file exists under
# libc/src/ or libc/include/llvm-libc-macros/.
CLANG_FREESTANDING_HEADERS = {
"float.h",
"iso646.h",
"limits.h",
"stdalign.h",
"stdarg.h",
"stdatomic.h",
"stdbool.h",
"stdckdint.h",
"stddef.h",
"stdint.h",
"stdnoreturn.h",
"tgmath.h",
}
def _is_stub_file(path: Path) -> bool:
text = path.read_text(encoding="utf-8")
if "todo" not in text.lower() and "unimplemented" not in text.lower():
return False
idx = text.find("LLVM_LIBC_FUNCTION")
if idx == -1:
return False
open_brace = text.find("{", idx)
if open_brace == -1:
return False
depth, body = 0, ""
for i in range(open_brace, len(text)):
if text[i] == "{":
depth += 1
elif text[i] == "}":
depth -= 1
if depth == 0:
body = text[open_brace + 1 : i]
break
clean = re.sub(r"//.*$", "", body, flags=re.MULTILINE)
clean = re.sub(r"/\*.*?\*/", "", clean, flags=re.DOTALL).strip()
stmts = [s.strip() for s in clean.split(";") if s.strip()]
if len(stmts) == 0:
return True
if len(stmts) > 2:
return False
for stmt in stmts:
if stmt.startswith(("libc_errno =", "return")):
no_cast = re.sub(
r"(const_cast|reinterpret_cast|static_cast)\s*<[^>]+>", "", stmt
)
if "::" in no_cast:
return False
ret = no_cast.replace("return", "").strip()
if re.search(r"\b[A-Za-z0-9_]+\s*\(", ret):
return False
else:
return False
return True
@lru_cache(maxsize=None)
def _load_implemented_functions(
libc_root: Path,
) -> Tuple[Set[str], Dict[str, Set[str]]]:
stubs, reals = set(), set()
src_dir = libc_root / "src"
if src_dir.exists():
for p in src_dir.rglob("*.cpp"):
(stubs if _is_stub_file(p) else reals).add(p.stem)
stub_only = stubs - reals
all_fns: Set[str] = set()
by_stem: Dict[str, Set[str]] = {}
config_dir = libc_root / "config"
if config_dir.exists():
for ep_file in config_dir.rglob("entrypoints.txt"):
for line in ep_file.read_text(encoding="utf-8").splitlines():
line = line.strip()
if line.startswith("libc.src."):
parts = line.split(".")
sym = parts[-1]
if sym not in stub_only:
all_fns.add(sym)
stem = "/".join(parts[2:-1])
by_stem.setdefault(stem, set()).add(sym)
return all_fns, by_stem
def _load_include_yaml(yaml_path: Path) -> Dict:
if not yaml_path.exists():
return {}
data = yaml.safe_load(yaml_path.read_text(encoding="utf-8")) or {}
for rel in data.get("merge_yaml_files", []):
merged = _load_include_yaml((yaml_path.parent / rel).resolve())
for key in ("macros", "types", "enums", "objects", "functions"):
if key in merged:
data.setdefault(key, []).extend(merged[key])
return data
class Header:
"""
Maintains implementation information about a standard header file:
* where does its implementation dir live
* where is its macros file
* where is its docgen yaml file
Macro implementation status is checked across header-specific
``*-macros.h`` files under ``$LLVM_PROJECT_ROOT/libc/include/llvm-libc-macros``,
macro and enum entries in ``$LLVM_PROJECT_ROOT/libc/include/<header>.yaml``
(including shared ``macro_header`` definitions), ``include/<header>.h.def``
templates, and compiler-provided freestanding headers.
Function implementation status is determined from the union of exported
entrypoints across ``$LLVM_PROJECT_ROOT/libc/config/**/entrypoints.txt``,
excluding source files under ``libc/src/`` whose only implementation is a
``TODO`` stub.
"""
def __init__(self, header_name: str, libc_root: Optional[Path] = None):
"""
:param header_name: e.g., ``"threads.h"`` or ``"signal.h"``
"""
self.name = header_name
self.stem = header_name[:-2] if header_name.endswith(".h") else header_name
self.docgen_root = Path(__file__).parent
self.libc_root = (
libc_root if libc_root is not None else self.docgen_root.parent.parent
)
self.docgen_yaml = self.docgen_root / Path(header_name).with_suffix(".yaml")
# Path to libc/include/<name>.yaml
self.include_yaml = Path(
self.libc_root, "include", Path(header_name).with_suffix(".yaml")
)
self.fns_dir = Path(self.libc_root, "src", self.stem)
self.macros_dir = Path(self.libc_root, "include", "llvm-libc-macros")
def is_clang_provided(self) -> bool:
return self.name in CLANG_FREESTANDING_HEADERS
@property
def api(self) -> Dict:
if not hasattr(self, "_api"):
self._api = (
yaml.safe_load(self.docgen_yaml.read_text(encoding="utf-8"))
if self.docgen_yaml.exists()
else {}
) or {}
return self._api
@property
def include_data(self) -> Dict:
if not hasattr(self, "_include_data"):
self._include_data = _load_include_yaml(self.include_yaml)
return self._include_data
def macro_file_exists(self) -> bool:
if self.is_clang_provided() or any(self.__get_macro_files()):
return True
return bool(self.include_data.get("macros"))
def fns_dir_exists(self) -> bool:
return self.fns_dir.exists() and self.fns_dir.is_dir()
def implements_fn(self, fn_name: str) -> bool:
if self.is_clang_provided():
return True
all_fns, by_stem = _load_implemented_functions(self.libc_root)
if fn_name in by_stem.get(self.stem, set()):
return True
if not hasattr(self, "_declared_fns"):
self._declared_fns = {
f["name"] for f in self.include_data.get("functions", []) if "name" in f
}
return fn_name in all_fns and fn_name in self._declared_fns
def implements_macro(self, m_name: str) -> bool:
"""
Some macro files are in, e.g.,
``$LLVM_PROJECT_ROOT/libc/include/llvm-libc-macros/fenv-macros.h``,
but others are in subdirectories, e.g., ``signal.h`` has the macro
definitions in
``$LLVM_PROJECT_ROOT/libc/include/llvm-libc-macros/linux/signal-macros.h``.
:param m_name: name of macro, e.g., ``FE_ALL_EXCEPT``
"""
if self.is_clang_provided():
return True
for f in self.__get_macro_files():
if f"#define {m_name}" in f.read_text(encoding="utf-8"):
return True
if any(
m.get("macro_name") == m_name
and ("macro_value" in m or "macro_header" in m)
for m in self.include_data.get("macros", [])
):
return True
if any(e.get("name") == m_name for e in self.include_data.get("enums", [])):
return True
def_file = self.libc_root / "include" / f"{self.name}.def"
if def_file.exists() and f"#define {m_name}" in def_file.read_text(
encoding="utf-8"
):
return True
return False
def __get_macro_files(self) -> Generator[Path, None, None]:
"""
This function uses a glob on, e.g., ``"**/fcntl.macros.h"`` because the
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
"""
stem = self.stem.replace("/", "-")
return self.macros_dir.glob(f"**/{stem}-macros.h")