blob: 6f8de1503554cdf760895d1238022cad4632d94f [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
import sys
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
_VARIABLE_RE = re.compile(
r"LLVM_LIBC_VARIABLE\s*\([^,]+,\s*([A-Za-z_][A-Za-z0-9_]*)\s*\)"
)
@lru_cache(maxsize=None)
def _load_implemented_functions(
libc_root: Path,
) -> Tuple[Set[str], Dict[str, Set[str]]]:
stubs, reals = set(), set()
vars_by_target: Dict[str, Set[str]] = {}
src_dir = libc_root / "src"
if src_dir.exists():
for p in src_dir.rglob("*.cpp"):
if _is_stub_file(p):
stubs.add(p.stem)
else:
reals.add(p.stem)
for var in _VARIABLE_RE.findall(p.read_text(encoding="utf-8")):
vars_by_target.setdefault(p.stem, set()).add(var)
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:
stem = "/".join(parts[2:-1])
exported = {sym} | vars_by_target.get(sym, set())
all_fns |= exported
by_stem.setdefault(stem, set()).update(exported)
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
or self.api.get("provider") == "clang"
)
@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 _load_exposed_types(self) -> Set[str]:
hdrgen_dir = str(self.docgen_root.parent / "hdrgen")
if hdrgen_dir not in sys.path:
sys.path.insert(0, hdrgen_dir)
from hdrgen.header import COMPILER_HEADER_TYPES, HeaderFile
from hdrgen.yaml_to_classes import load_yaml_file
queue = []
if self.include_yaml.exists() and "header" in self.include_data:
header_file = load_yaml_file(self.include_yaml, HeaderFile, None)
queue.extend(t.name for t in header_file.all_types())
else:
queue.extend(
t["type_name"]
for t in self.include_data.get("types", [])
if "type_name" in t
)
def_file = self.libc_root / "include" / f"{self.name}.def"
if def_file.exists():
queue.extend(
re.findall(
r"llvm-libc-types/([A-Za-z0-9_]+)\.h",
def_file.read_text(encoding="utf-8"),
)
)
found: Set[str] = set()
seen: Set[str] = set()
types_dir = self.libc_root / "include" / "llvm-libc-types"
while queue:
type_name = queue.pop()
if type_name in seen:
continue
seen.add(type_name)
type_path = types_dir / f"{type_name}.h"
if type_name in COMPILER_HEADER_TYPES or type_path.exists():
found.add(type_name)
if type_path.exists():
queue.extend(
re.findall(
r'#include\s+"(?:.*/)?([A-Za-z0-9_]+)\.h"',
type_path.read_text(encoding="utf-8"),
)
)
return found
def implements_type(self, t_name: str) -> bool:
if self.is_clang_provided():
return True
if not hasattr(self, "_exposed_types"):
self._exposed_types = self._load_exposed_types()
return (
t_name in self._exposed_types
or t_name.replace(" ", "_") in self._exposed_types
)
def implements_object(self, o_name: str) -> bool:
if self.is_clang_provided():
return True
if not any(
o.get("object_name") == o_name for o in self.include_data.get("objects", [])
):
return False
all_syms, by_stem = _load_implemented_functions(self.libc_root)
return o_name in by_stem.get(self.stem, set()) or o_name in all_syms
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")