[libc] Make errno an entrypoint.

[sivachandra]

Summary

The entrypoint has been added to the various entrypoint lists. The libc
code style doc has been updated with information on how errno should be
set from the libc runtime code.

[sivachandra]

Exclude errno from api-test.

libc/cmake/modules/LLVMLibCLibraryRules.cmake

 function(collect_object_file_deps target result)
+  # NOTE: This function does add entrypoint targets to |result|.
+  # It is expected that the caller adds them separately.
   set(all_deps "")
   get_target_property(target_type ${target} "TARGET_TYPE")
   if(NOT target_type)
     return()
   endif()
 
   if(${target_type} STREQUAL ${OBJECT_LIBRARY_TARGET_TYPE})
     list(APPEND all_deps ${target})
if(${target_type} STREQUAL ${ENTRYPOINT_OBJ_TARGET_TYPE})
     if(is_alias)
       get_target_property(aliasee ${entrypoint_target} "DEPS")
       if(NOT aliasee)
         message(FATAL_ERROR
                 "Entrypoint alias ${entrypoint_target} does not have an aliasee.")
       endif()
       set(entrypoint_target ${aliasee})
     endif()
-    list(APPEND all_deps ${entrypoint_target})
     get_target_property(deps ${target} "DEPS")
     foreach(dep IN LISTS deps)
       collect_object_file_deps(${dep} dep_targets)
       list(APPEND all_deps ${dep_targets})
     endforeach(dep)
     list(REMOVE_DUPLICATES all_deps)
     set(${result} ${all_deps} PARENT_SCOPE)
     return()
function(add_entrypoint_library target_name)
   foreach(dep IN LISTS fq_deps_list)
     get_target_property(dep_type ${dep} "TARGET_TYPE")
     if(NOT ((${dep_type} STREQUAL ${ENTRYPOINT_OBJ_TARGET_TYPE}) OR (${dep_type} STREQUAL ${ENTRYPOINT_EXT_TARGET_TYPE})))
       message(FATAL_ERROR "Dependency '${dep}' of 'add_entrypoint_collection' is "
                           "not an 'add_entrypoint_object' or 'add_entrypoint_external' target.")
     endif()
     collect_object_file_deps(${dep} recursive_deps)
     list(APPEND all_deps ${recursive_deps})
+    # Add the entrypoint object target explicitly as collect_object_file_deps
+    # only collects object files from non-entrypoint targets.
+    if(${dep_type} STREQUAL ${ENTRYPOINT_OBJ_TARGET_TYPE})
+      set(entrypoint_target ${dep})
+      get_target_property(is_alias ${entrypoint_target} "IS_ALIAS")
+      if(is_alias)
+        get_target_property(aliasee ${entrypoint_target} "DEPS")
+        if(NOT aliasee)
+          message(FATAL_ERROR
+                  "Entrypoint alias ${entrypoint_target} does not have an aliasee.")
+        endif()
+        set(entrypoint_target ${aliasee})
+      endif()
+    endif()
+    list(APPEND all_deps ${entrypoint_target})
   endforeach(dep)
   list(REMOVE_DUPLICATES all_deps)
   set(objects "")
   foreach(dep IN LISTS all_deps)
     list(APPEND objects $<$<STREQUAL:$<TARGET_NAME_IF_EXISTS:${dep}>,${dep}>:$<TARGET_OBJECTS:${dep}>>)
   endforeach(dep)
 
   add_library(

libc/config/baremetal/entrypoints.txt

set(TARGET_LIBC_ENTRYPOINTS
     libc.src.ctype.ispunct
     libc.src.ctype.isspace
     libc.src.ctype.isupper
     libc.src.ctype.isxdigit
     libc.src.ctype.toascii
     libc.src.ctype.tolower
     libc.src.ctype.toupper
 
+    # errno.h entrypoints
+    libc.src.errno.errno
+
     # string.h entrypoints
     libc.src.string.bcmp
     libc.src.string.bcopy
     libc.src.string.bzero
     libc.src.string.memccpy
     libc.src.string.memchr
     libc.src.string.memcmp
     libc.src.string.memcpy

libc/config/linux/aarch64/entrypoints.txt

set(TARGET_LIBC_ENTRYPOINTS
     libc.src.ctype.ispunct
     libc.src.ctype.isspace
     libc.src.ctype.isupper
     libc.src.ctype.isxdigit
     libc.src.ctype.toascii
     libc.src.ctype.tolower
     libc.src.ctype.toupper
     
+    # errno.h entrypoints
+    libc.src.errno.errno
+
     # fcntl.h entrypoints
     libc.src.fcntl.creat
     libc.src.fcntl.open
     libc.src.fcntl.openat
 
     # sched.h entrypoints
     libc.src.sched.sched_getaffinity
     libc.src.sched.sched_setaffinity

libc/config/linux/arm/entrypoints.txt

set(TARGET_LIBC_ENTRYPOINTS
     libc.src.ctype.ispunct
     libc.src.ctype.isspace
     libc.src.ctype.isupper
     libc.src.ctype.isxdigit
     libc.src.ctype.toascii
     libc.src.ctype.tolower
     libc.src.ctype.toupper
 
+    # errno.h entrypoints
+    libc.src.errno.errno
+
     # string.h entrypoints
     libc.src.string.bcmp
     libc.src.string.bcopy
     libc.src.string.bzero
     libc.src.string.memccpy
     libc.src.string.memchr
     libc.src.string.memcmp
     libc.src.string.memcpy

libc/config/linux/x86_64/entrypoints.txt

set(TARGET_LIBC_ENTRYPOINTS
     libc.src.ctype.ispunct
     libc.src.ctype.isspace
     libc.src.ctype.isupper
     libc.src.ctype.isxdigit
     libc.src.ctype.toascii
     libc.src.ctype.tolower
     libc.src.ctype.toupper
 
+    # errno.h entrypoints
+    libc.src.errno.errno
+
     # fcntl.h entrypoints
     libc.src.fcntl.creat
     libc.src.fcntl.open
     libc.src.fcntl.openat
 
     # sched.h entrypoints
     libc.src.sched.sched_getaffinity
     libc.src.sched.sched_setaffinity

libc/docs/dev/code_style.rst

.. code-block:: c++
      LIBC_INLINE ReturnType function_defined_inline(ArgType arg) {
        ...
      }
 
 #. The ``LIBC_INLINE`` tag should also be added to functions which have
    definitions that are implicitly inline. Examples of such functions are
    class methods (static and non-static) defined inline and ``constexpr``
    functions.
+
+Setting ``errno`` from runtime code
+===================================
+
+Many libc functions set ``errno`` to indicate an error condition. If LLVM's libc
+is being used as the only libc, then the ``errno`` from LLVM's libc is affected.
+If LLVM's libc is being used in the :ref:`overlay_mode`, then the ``errno`` from
+the system libc is affected. When a libc function, which can potentially affect
+the ``errno``, is called from a unit test, we do not want the global ``errno``
+(as in, the ``errno`` of the process thread running the unit test) to be
+affected. If the global ``errno`` is affected, then the operation of the unit
+test infrastructure itself can be affected. To avoid perturbing the unit test
+infrastructure around the setting of ``errno``, the following rules are to be
+followed:
+
+#. A special macro named ``libc_errno`` defined in ``src/errno/libc_errno.h``
+   should be used when setting ``errno`` from libc runtime code. For example,
+   code to set ``errno`` to ``EINVAL`` should be:
+
+   .. code-block:: c++
+
+    libc_errno = EINVAL;
+
+#. ``errno`` should be set just before returning from the implementation of the
+   public function. It should not be set from within helper functions. Helper
+   functions should use idiomatic C++ constructs like
+   `cpp::optional <https://github.com/llvm/llvm-project/blob/main/libc/src/__support/CPP/optional.h>`_
+   and
+   `ErrorOr <https://github.com/llvm/llvm-project/blob/main/libc/src/__support/error_or.h>`_
+   to return error values.
+
+#. The header file ``src/errno/libc_errno.h`` is shipped as part of the target
+   corresponding to the ``errno`` entrypoint ``libc.src.errno.errno``. We do
+   not in general allow dependecies between entrypoints. However, the ``errno``
+   entrypoint is the only exceptional entrypoint on which other entrypoints
+   should explicitly depend on if they set ``errno`` to indicate error
+   conditions.

libc/src/errno/CMakeLists.txt

-add_object_library(
+add_entrypoint_object(
   errno
   SRCS
     libc_errno.cpp
   HDRS
     libc_errno.h     # Include this
     llvmlibc_errno.h # DEPRECATED: Will be removed soon
   DEPENDS
     libc.include.errno
 )

libc/utils/HdrGen/PrototypeTestGen/PrototypeTestGen.cpp

 
 } // anonymous namespace
 
 bool TestGeneratorMain(llvm::raw_ostream &OS, llvm::RecordKeeper &records) {
   OS << "#include \"src/__support/CPP/type_traits.h\"\n";
   llvm_libc::APIIndexer G(records);
   std::unordered_set<std::string> headerFileSet;
   for (const auto &entrypoint : EntrypointNamesOption) {
+    if (entrypoint == "errno")
+      continue;
     auto match = G.FunctionToHeaderMap.find(entrypoint);
     if (match == G.FunctionToHeaderMap.end()) {
       auto objectMatch = G.ObjectToHeaderMap.find(entrypoint);
       if (objectMatch != G.ObjectToHeaderMap.end()) {
         headerFileSet.insert(objectMatch->second);
         continue;
       }
 
       llvm::errs() << "ERROR: entrypoint '" << entrypoint
                    << "' could not be found in spec in any public header\n";
       return true;
     }
     headerFileSet.insert(match->second);
   }
   for (const auto &header : headerFileSet)
     OS << "#include <" << header << ">\n";
 
   OS << '\n';
 
   OS << "extern \"C\" int main() {\n";
   for (const auto &entrypoint : EntrypointNamesOption) {
+    if (entrypoint == "errno")
+      continue;
     auto match = G.FunctionSpecMap.find(entrypoint);
     if (match == G.FunctionSpecMap.end()) {
       auto objectMatch = G.ObjectSpecMap.find(entrypoint);
       if (objectMatch != G.ObjectSpecMap.end()) {
         auto entrypointPtr = entrypoint + "_ptr";
         llvm::Record *objectSpec = G.ObjectSpecMap[entrypoint];
         auto objectType = objectSpec->getValueAsString("Type");
         // We just make sure that the global object is present.