Index: doc/theses/andrew_beach_MMath/cfalab.sty =================================================================== --- doc/theses/andrew_beach_MMath/cfalab.sty (revision 2c052c066d20fcbb9aba70ba84de9a93003f5a67) +++ doc/theses/andrew_beach_MMath/cfalab.sty (revision 2c052c066d20fcbb9aba70ba84de9a93003f5a67) @@ -0,0 +1,35 @@ +% Package for CFA Research Lab. +% +% Made by combining and updating + +% I don't know what the oldest LaTeX2e version with everything needed is. +\NeedsTeXFormat{LaTeX2e} +\ProvidesPackage{cfalab}[2020/03/09 v0.1 CFA Laboratory LaTeX Tools] + +% Other packages required. +\RequirePackage{etoolbox} +\RequirePackage{xspace} + +% Symbols: All symbols are zero argument robust commands with special rules +% about the space following the c.s. token. Normally the space might be +% re-added according to the rules of the xspace package. They may be followed +% by a star (which the command will consume) to disable this behaviour. + +% \newsymbolcmd{}{} +% Creates a symbol with that has the given . Note that +% the name must be given as a series of letters, not as an escaped name. +\newrobustcmd*\newsymbolcmd[2]{ + \csdef{#1}{\cfalab@symbol{#1}} + \expandafter\robustify\csname #1\endcsname + \csdef{cfalab@symbol@#1}{#2} +} +\def\cfalab@symbol#1{\@ifnextchar*{\cfalab@symstar{#1}}{\cfalab@symnostar{#1}}} +\def\cfalab@symstar#1*{\csuse{cfalab@symbol@#1}} +\def\cfalab@symnostar#1{\csuse{cfalab@symbol@#1}\xspace} + +% Cforall with the forall symbol. +\newsymbolcmd{CFA}{\textsf{C}\raisebox{\depth}{\rotatebox{180}{\textsf{A}}}} + +\newcommand\codeC[1]{\texttt{#1}} + +\endinput Index: doc/theses/andrew_beach_MMath/thesis.tex =================================================================== --- doc/theses/andrew_beach_MMath/thesis.tex (revision 3d3cbd09b970cf7985bfab5afe5453d45e24f422) +++ doc/theses/andrew_beach_MMath/thesis.tex (revision 2c052c066d20fcbb9aba70ba84de9a93003f5a67) @@ -13,4 +13,6 @@ % For including graphics, sets the pdftex graphics driver. \usepackage[pdftex]{graphicx} + +\usepackage{cfalab} \usehyperrefpackage[pdftex,pagebackref=false]{ @@ -43,9 +45,11 @@ type=nomenclature, name=dingledorf, -description={A person of supposed average intelligence who makes incredibly brainless misjudgments} +description={A person of supposed average intelligence who makes incredibly + brainless misjudgments} } % List of Abbreviations (abbreviations are from the glossaries-extra package) -\newabbreviation{aaaaz}{AAAAZ}{American Association of Amature Astronomers and Zoologists} +\newabbreviation{aaaaz}{AAAAZ}{American Association of Amature Astronomers + and Zoologists} % List of Symbols @@ -56,5 +60,6 @@ sort={label}, type=symbols, -description={Random vector: a location in n-dimensional Cartesian space, where each dimensional component is determined by a random process} +description={Random vector: a location in n-dimensional Cartesian space, where + each dimensional component is determined by a random process} } @@ -72,4 +77,6 @@ % MAIN BODY %---------------------------------------------------------------------- +\input{unwinding} + %====================================================================== \chapter{Introduction} Index: doc/theses/andrew_beach_MMath/unwinding.tex =================================================================== --- doc/theses/andrew_beach_MMath/unwinding.tex (revision 2c052c066d20fcbb9aba70ba84de9a93003f5a67) +++ doc/theses/andrew_beach_MMath/unwinding.tex (revision 2c052c066d20fcbb9aba70ba84de9a93003f5a67) @@ -0,0 +1,141 @@ +\chapter{Unwinding in \CFA} + +Stack unwinding is the process of removing things from the stack from outside +the functions there. In languages that don't provide a way to garrenty that +code will run when the program leaves a scope or finishes a function, this +can be relatively trivial. C does this with \codeC{longjmp} by setting the +stack pointer and a few other registers. + +\section{libunwind Usage} + +There are two primary functions that \CFA uses in libunwind that create most +of the control flow. These are \codeC{\_Unwind\_RaiseException} and +\codeC{\_Unwind\_ForcedUnwind}. + +Their operation is divided amoung two phases, search and clean-up. The search +phase -- phase 1 -- is used while scanning the stack while not actually +unwinding it while the clean-up phase -- phase 2 -- is used while the actual +unwinding is under way. + +% Somewhere around here I need to talk about the control structures. +% \codeC{\_Unwind\_Exception} is used to carry the API's universal data. Some +% of this is internal, other fields are used to communicate between different +% exception handling mechanisms in different runtimes. +% \codeC{\_Unwind\_Context} is an opaque data structure that is used to pass +% information to helper functions. + +Raise exception can cover both phases. It starts by searching for the handler +and if it finds it preforms a clean-up phase to unwind the stack to the +hander. If not it returns allowing the program to decide what to do with all +the state and stack that were in place before the call. During both phases +the raise exception function will search down the stack, calling each +function's personality function as they are found. + +Personality functions must be able to preform three tasks, although not all +of them have to be preformed in a given call. Which tasks must be preformed +are decided by the actions provided. +% Something argument something bitmask. +\begin{itemize} +\item\codeC{\_UA\_SEARCH\_PHASE} this is being called during the clean-up +phase and means search for handlers. If the hander is found the personality +function should return \codeC{\_URC\_HANDLER\_FOUND}, otherise it should +return \codeC{\_URC\_CONTINUE\_UNWIND}. +\item\codeC{\_UA\_CLEANUP\_PHASE} is passed in during the clean-up phase and +means that part or all of the stack frame is being removed. The personality +function should do whatever clean-up the language defines (such as running +destructors) and then generally returns \codeC{\_URC\_CONTINUE\_UNWIND}. +\item\codeC{\_UA\_HANDLER\_FRAME} means that the personality function must +install a handler. It is also passing in during the clean-up phase and will +be in addition to the clean-up action. Libunwind provides several helpers +for the personality function here. Once it is done the personality function +must return \codeC{\_URC\_INSTALL\_CONTEXT}. +\end{itemize} + +Forced unwind only preforms the clean-up phase. It is similar to the phase 2 +section of raise exception with a few changes. A simple one is that +it passes in an extra action to the personality function +\codeC{\_UA\_FORCE\_UNWIND} which means a handler cannot be installed. The +most significant is the addition of the stop function, which is passed in as +an argument to the forced unwind. + +The stop function is a lot like a personality function. It takes an extra +argument, a void pointer passed into force unwind. It may return +\codeC{\_URC\_NO\_REASON} to continue unwinding or it can transfer control +out of the unwind code using its own mechanism. +% Is there a reason that NO_REASON is used instead of CONTINUE_UNWIND? +The stop function is called once on every stack frame and once at the end of +the stack. In a stack frame it is called before the personality routine with +the same arguments (except for the extra void pointer). At the end of the +stack the arguments are mostly the same, except the stack pointer stored in +the context is set to null. Because of the significance of that change both +GCC and Clang add an extra action in this case \codeC{\_UA\_END\_OF\_STACK}. +The stop function may not return at the end of the stack. + +\section{\CFA Implementation} + +To use libunwind \CFA provides several wrappers, its own storage, the +personality functions and a stop function. + +The wrappers preform three tasks: set-up, clean-up and controlling the +unwinding. The set-up allocates a copy of the \CFA exception into the hander +so it can control its lifetime and stores it in the exception context while +clean-up -- run when control exits a catch clause and return to normal code -- +frees the exception copy. +% It however does not set up the unwind exception so we can't use any inter- +% runtime/language features. Also the exception context is global. + +The control code in the middle is run every time a throw or re-throw is +called. It uses raise exception to search for a hander and to run it if one +is found. Otherwise it uses forced unwind to unwind the stack, running all +destructors, before terminating the process. + +The stop function is very simple, it checks the end of stack flag to see if +it is finished unwinding. If so it calls exit to end the process, otherwise +it tells the system to continue unwinding. +% Yeah, this is going to have to change. + +The personality routine is much more complicated. +First because it has to get some information about the function by scanning +the LSDA (Language Specific Data Area). This allows a single personality +function to be used for multiple functions and it accounts for multiple +regions and possible handlers in a single function. +% Not that we do that yet. + +However generating the LSDA is very difficult. It requires a lot of knowledge +about the location of the instruction pointer and stack layout that can be +broken by optimization. So instead for frames where there are only destructors +we use GCC's attribute cleanup and the -fexception flag to handle unwinding +without adding our own functionality. + +For functions that do have handlers (defined in try statements) the function +is split into several functions. Everything outside the try statement is the +first function, which has then has only destructors to be run during +unwinding. The clauses of the try block are then converted into GCC inner +functions which can be passed around with function pointers while still having +access to the outer function's scope. \codeC{catchResume} and \codeC{finally} +clauses are handled seperately and will not be discussed here. + +The \codeC{try} clause is convered to a function directly. The \codeC{catch} +clauses are combined and then create two functions. The first is the match +function which is used during the search phase to see if any of the handler +here. The second it the catch function, which is a large switch-case block +with the different handlers. All of these function do not interact with +unwinding except for running destructors and so can be handled by GCC. + +These three functions are passed into \codeC{try\_terminate}, an internal +function that repersents the try statement. This is the only function with +our personality function as well as assembly statements that create the LSDA. +In normal execution all the function does is call the try block closure and +return once that has finished executing. However using libunwind its +personality function now handles exception matching and catching. + +During the search phase the personality function retreaves the match function +from the stack using the saved stack pointer. The function is called, either +returning 0 for no match or the index (a positive integer) of the handler +that will handle it. The if a handler was found the personality function +reports it after saving the index to the exception context. + +During the clean-up phase there is nothing for the personality function to +clean-up in \codeC{try\_terminate}. So if this is not the handler frame +unwinding continues. If this is the handler frame than control is transfered +to the catch function, giving it the exception and the handler index. Index: doc/theses/andrew_beach_MMath/uw-ethesis.cls =================================================================== --- doc/theses/andrew_beach_MMath/uw-ethesis.cls (revision 3d3cbd09b970cf7985bfab5afe5453d45e24f422) +++ doc/theses/andrew_beach_MMath/uw-ethesis.cls (revision 2c052c066d20fcbb9aba70ba84de9a93003f5a67) @@ -28,5 +28,5 @@ % with options in (set hyperref's \hypersetup for details). \NeedsTeXFormat{LaTeX2e} -\ProvidesClass{uw-ethesis} %[DATE VERSION NOTES] +\ProvidesClass{uw-ethesis}[2020/03/09 v0.1 UW E-Thesis Template Document Class] \RequirePackage{etoolbox}