| # ===----------------------------------------------------------------------===## | |
| # | |
| # 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") |