From 05a8bcfb9dc5f7e33d44d8ef808072b9aa176242 Mon Sep 17 00:00:00 2001 From: Chris B Date: Mon, 12 Aug 2024 15:10:29 -0500 Subject: [PATCH] Introduce program linkage (#295) The C++ specification talks in terms of module, external, internal, and no linkage. These linkages in C++ refer to translation units. For HLSL, we have some differences in how programs are built and linked that can't be fully expressed in that language. Specifically, we have a notion of a program-export (entry functions, export keyword), that denotes a linkage that is more external than just cross translation unit. This change introduces a term _program linkage_ to refer to names that have linkage outside a linked or freestanding program. --- specs/language/basic.tex | 77 ++++++++++++++++++++++++++++----- specs/language/declarations.tex | 4 +- 2 files changed, 68 insertions(+), 13 deletions(-) diff --git a/specs/language/basic.tex b/specs/language/basic.tex index 25ba1bf7..bb9d34bb 100644 --- a/specs/language/basic.tex +++ b/specs/language/basic.tex @@ -115,17 +115,74 @@ } \end{HLSL} -\Sec{Linkage}{Basic.Linkage} +\Sec{One-Definition Rule}{Basic.ODR} -\p An entity that denotes an object, reference, function, type, template, -namespace, or value, may have a \textit{linkage}. If a name has -\textit{linkage}, it refers to the same entity as the same name introduced by a -declaration in another scope. If a variable, function, or another entity with -the same name is declared in several scopes, but does not have sufficient -\textit{linkage}, then several instances of the entity are generated. +\p The \gls{isoCPP} \textit{One-definition rule} is adopted as defined in +\gls{isoCPP} \textbf{[basic.def.odr]}. -\p There are three linkages recognized: \textit{external linkage}, -\textit{internal linkage} and \textit{no linkage}. +\Sec{Scope}{Basic.Scope} + +\Sec{Name Lookup}{Basic.Lookup} + +\Sec{Program and linkage}{Basic.Linkage} + +\p A translation unit (\ref{Lex.Translation}) is comprised of a sequence of +declarations: + +\begin{grammar} + \define{translation-unit}\br + \opt{declaration-sequence} +\end{grammar} + +\p A \textit{program} is one or more translation units \textit{linked} together. +A program built from a single translation unit, bypassing a linking step is +called \textit{freestanding}. + +\p A program is said to be \textit{fully linked}, when it contains no +\textit{unresolved external} declarations, and all \textit{exported} +declarations are entry point declarations (\ref{Basic.Start}). A program is said +to be \textit{partially linked}, when it contains at least one unresolved +external declaration or at least one exported declaration that is not an entry +point. + +\p An implementation may generate programs as fully linked or partially linked +as requested by the user, and a runtime may allow fully linked or partially +linked programs as the implementation allows. + +\p A name has \textit{linkage} if it can refer to the same entity as a name +introduced by a declaration in another scope. If a variable, function, or +another entity with the same name is declared in several scopes, but does not +have sufficient \textit{linkage}, then several instances of the entity are +generated. + +\begin{itemize} +\item A name with \textit{no linkage} may not be referred to by names from +any other scope. +\item A name with \textit{internal linkage} may be referred to by names +from other scopes within the same translation unit. +\item A name with \textit{external linkage} may be referred to by names from +other scopes within the same translation unit, and by names from scopes of other +translation units. +\item A name with \textit{program linkage} may be referred to by names from +other scopes within the same translation unit, by names from scopes of other +translation units, by names from scopes of other programs, and by a runtime +implementation. +\end{itemize} + +\p When merging translation units through linking or generating a freestanding +program only names with program linkage must be retained in the final program. + +\Sub{Program Linkage}{Basic.Linkage.Program} + +\p Entities with \textit{program linkage} can be referred to from other +partially linked programs or a runtime implementation. + +\p The following entities have program linkage: +\begin{itemize} + \item entry point functions (\ref{Basic.Start}) + \item functions marked with \texttt{export} keyword (\ref{Decl.Export}) + \item declarations contained within an \textit{export-declaration-group} (\ref{Decl.Export}) +\end{itemize} \Sub{External Linkage}{Basic.Linkage.External} @@ -134,8 +191,6 @@ \p The following entities in HLSL have \textit{external linkage}: \begin{itemize} - \item entry point functions - \item functions marked with \texttt{export} keyword \item global variables that are not marked \texttt{static} or \texttt{groupshared} \footnote{These are not really linked with other translation units but rather their values are loaded indirectly based on diff --git a/specs/language/declarations.tex b/specs/language/declarations.tex index e3499ec9..67b62680 100644 --- a/specs/language/declarations.tex +++ b/specs/language/declarations.tex @@ -36,11 +36,11 @@ \texttt{export}\br \end{grammar} -\p The \texttt{export} specifier denotes that the function has \textit{external linkage} (\ref{Basic.Linkage.External}). +\p The \texttt{export} specifier denotes that the function has program linkage (\ref{Basic.Linkage.Program}). \p The \texttt{export} specifier cannot be used on functions directly or indirectly within an unnamed namespace. -\p Functions with \textit{external linkage} can also be specified in \textit{export-declaration-group} (\ref{Decl.Export}). +\p Functions with program linkage can also be specified in \textit{export-declaration-group} (\ref{Decl.Export}). \p If a function is declared with an \texttt{export} specifier then all redeclarations of the same function must also use the \texttt{export} specifier or be part of \textit{export-declaration-group} (\ref{Decl.Export}).