%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % Copyright (c) 2015, ETH Zurich. % All rights reserved. % % This file is distributed under the terms in the attached LICENSE file. % If you do not find this file, copies can be found by writing to: % ETH Zurich D-INFK, Universitaetstr 6, CH-8092 Zurich. Attn: Systems Group. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \providecommand{\pgfsyspdfmark}[3]{} \documentclass[a4paper,11pt,twoside]{report} \usepackage{amsmath} \usepackage{bftn} \usepackage{calc} \usepackage{verbatim} \usepackage{xspace} \usepackage{pifont} \usepackage{pxfonts} \usepackage{textcomp} \usepackage{multirow} \usepackage{listings} \usepackage{todonotes} \usepackage{hyperref} \title{Skate in Barrelfish} \author{Barrelfish project} % \date{\today} % Uncomment (if needed) - date is automatic \tnnumber{020} \tnkey{Skate} \lstdefinelanguage{skate}{ morekeywords={schema,typedef,fact,enum}, sensitive=true, morecomment=[l]{//}, morecomment=[s]{/*}{*/}, morestring=[b]", } \presetkeys{todonotes}{inline}{} \begin{document} \maketitle % Uncomment for final draft \begin{versionhistory} \vhEntry{0.1}{16.11.2015}{MH}{Initial Version} \vhEntry{0.2}{20.04.2017}{RA}{Renaming ot Skate and expanding.} \end{versionhistory} % \intro{Abstract} % Insert abstract here % \intro{Acknowledgements} % Uncomment (if needed) for acknowledgements \tableofcontents % Uncomment (if needed) for final draft % \listoffigures % Uncomment (if needed) for final draft % \listoftables % Uncomment (if needed) for final draft \cleardoublepage \setcounter{secnumdepth}{2} \newcommand{\fnname}[1]{\textit{\texttt{#1}}}% \newcommand{\datatype}[1]{\textit{\texttt{#1}}}% \newcommand{\varname}[1]{\texttt{#1}}% \newcommand{\keywname}[1]{\textbf{\texttt{#1}}}% \newcommand{\pathname}[1]{\texttt{#1}}% \newcommand{\tabindent}{\hspace*{3ex}}% \newcommand{\Skate}{\lstinline[language=skate]} \newcommand{\ccode}{\lstinline[language=C]} \lstset{ language=C, basicstyle=\ttfamily \small, keywordstyle=\bfseries, flexiblecolumns=false, basewidth={0.5em,0.45em}, boxpos=t, captionpos=b } %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \chapter{Introduction and usage} \label{chap:introduction} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \emph{Skate}\footnote{Skates are cartilaginous fish belonging to the family Rajidae in the superorder Batoidea of rays. More than 200 species have been described, in 32 genera. The two subfamilies are Rajinae (hardnose skates) and Arhynchobatinae (softnose skates). Source: \href{https://en.wikipedia.org/wiki/Skate_(fish)}{Wikipedia}} is a domain specific language to describe the schema of Barrelfish's System Knowledge Base (SKB)~\cite{skb}. The SKB stores all statically or dynamically discovered facts about the system. Static facts are known and exist already at compile time of the SKB ramdisk or are added through an initialization script or program. Examples for static facts include the device database, that associates known drivers with devices or the devices of a wellknown SoC. Dynamic facts, on the otherhand, are added to the SKB during and based on hardware discovery. Examples for dynamic facts include the number of processors or PCI Express devices. Inside the SKB, a prolog based constraint solver takes the added facts and computes a solution for hardware configuration such as PCI bridge programming, NUMA information for memory allocation or device driver lookup. Programs can query the SKB using Prolog statements and obtain device configuration and PCI bridge programming, interrupt routing and constructing routing trees for IPC. Applications can use information to determine hardware characteristics such as cores, nodes, caches and memory as well as their affinity. The Skate language is used to define format of those facts. The DSL is then compiled into a set of fact definitions and functions that are wrappers arround the SKB client functions, in particular \texttt{skb\_add\_fact()}, to ensure the correct format of the added facts. The intention when designing Skate is that the contents of system descriptor tables such as ACPI, hardware information obtained by CPUID or PCI discovery can be extracted from the respective manuals and easily specified in a Skate file. Skate complements the SKB by defining a \emph{schema} of the data stored in the SKB. A schema defines facts and their structure, which is similar to Prolog facts and their arity. A code-generation tool generates a C-API to populate the SKB according to a specific schema instance. The Skate compiler is written in Haskell using the Parsec parsing library. It generates C header files from the Skate files. In addition it supports the generation of Schema documentation. The source code for Skate can be found in \texttt{SOURCE/tools/skate}. \section{Use cases} We envision the following non exhausting list of possible use cases for Skate: \begin{itemize} \item A programmer is writing PCI discovery code or a device driver. The program inserts various facts about the discovered devices and the state of them into the SKB. To make the inserted facts usable to other programs running on the system, the format of the facts have to be known. For this purpose we need a common to specify the format of those facts and their meaning. \item Each program needs to ultimately deal with the issue of actually inserting the facts into the SKB or query them. For this purpose, the fact strings need to be formatted accordingly, and this may be done differently for various languages and is error prone to typos. Skate is intended to remove the burden from the programmer by providing a language native (e.g. C or Rust) to ensure a safe way of inserting facts into the SKB. \item Just knowing the format and the existence of certain facts is useless. A programmer needs to understand the meaning of them and their fields. It's not enough just to list the facts with the fields. Skate provides a way to generate a documentation about the specified facts. This enables programmers to reason about which facts should be used in particular selecting the right level of abstraction. This is important given that facts entered into the SKB from hardware discovery are intentionally as un-abstracted as possible. \item Documenting the available inference rules that the SKB implements to abstract facts into useful concepts for the OS. \end{itemize} \section{Command line options} \label{sec:cmdline} \begin{verbatim} $ skate INFILE.skt \end{verbatim} Where options is one of \begin{description} \item[-o] \textit{filename} The output file name \item[-L] generate latex documentation \item[-H] generate headerfile \item[-W] generate Wiki syntax documentation \end{description} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \chapter{Lexical Conventions} \label{chap:lexer} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% The Skate parser follows a similar convention as opted by modern day programming languages like C and Java. Hence, Skate uses a java-style-like parser based on the Haskell Parsec Library. The following conventions are used: \begin{description} \item[Encoding] The file should be encoded using plain text. \item[Whitespace:] As in C and Java, Skate considers sequences of space, newline, tab, and carriage return characters to be whitespace. Whitespace is generally not significant. \item[Comments:] Skate supports C-style comments. Single line comments start with \texttt{//} and continue until the end of the line. Multiline comments are enclosed between \texttt{/*} and \texttt{*/}; anything inbetween is ignored and treated as white space. \item[Identifiers:] Valid Skate identifiers are sequences of numbers (0-9), letters (a-z, A-Z) and the underscore character ``\texttt{\_}''. They must start with a letter or ``\texttt{\_}''. \begin{align*} identifier & \rightarrow ( letter \mid \_ ) (letter \mid digit \mid \_)^{\textrm{*}} \\ letter & \rightarrow (\textsf{A \ldots Z} \mid \textsf{a \ldots z})\\ digit & \rightarrow (\textsf{0 \ldots 9}) \end{align*} Note that a single underscore ``\texttt{\_}'' by itself is a special, ``don't care'' or anonymous identifier which is treated differently inside the language. \item[Case Sensitivity] Skate is not case sensitive hence identifiers \texttt{foo} and \texttt{Foo} will be the same. \item[Integer Literals:] A Skate integer literal is a sequence of digits, optionally preceded by a radix specifier. As in C, decimal (base 10) literals have no specifier and hexadecimal literals start with \texttt{0x}. Binary literals start with \texttt{0b}. In addition, as a special case the string \texttt{1s} can be used to indicate an integer which is composed entirely of binary 1's. \begin{align*} digit & \rightarrow (\textsf{0 \ldots 9})^{\textrm{1}}\\ hexadecimal & \rightarrow (\textsf{0x})(\textsf{0 \ldots 9} \mid \textsf{A \ldots F} \mid \textsf{a \ldots f})^{\textrm{1}}\\ binary & \rightarrow (\textsf{0b})(\textsf{0, 1})^{\textrm{1}}\\ \end{align*} \item[String Literals] String literals are enclosed in double quotes and should not span multiple lines. \item[Reserved words:] The following are reserved words in Skate: \begin{verbatim} schema, fact, flags, constants, enumeration, text, section \end{verbatim} \item[Special characters:] The following characters are used as operators, separators, terminators or other special purposes in Skate: \begin{alltt} \{ \} [ ] ( ) + - * / ; , . = \end{alltt} \end{description} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \chapter{Schema Declaration} \label{chap:declaration} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% In this chapter we define the layout of a Skate schema file, which declarations it must contain and what other declarations it can have. Each Skate schema file defines exactly one schema, which may refer to other schemas. \section{Syntax Highlights} In the following sections we use the syntax highlighting as follows: \begin{syntax} \synbf{bold}: Keywords \synit{italic}: Identifiers / strings chosen by the user \verb+verbatim+ constructs, symbols etc \end{syntax} \section{Conventions} There are a some conventions that should be followed when writing a schema declaration. Following the conventions ensures consistency among different schemas and allows generating a readable and well structured documentation. \begin{description} \item[Identifiers] Either camelcase or underscore can be used to separate words. Identifiers must be unique i.e. their fully qualified identifier must be unique. A fully qualified identifier can be constructed as $schema.(namespace.)*name.$ \item[Descriptions] The description fields of the declarations should be used as a more human readable representation of the identifier. No use of abbreviations or \item[Hierarchy/Grouping] Declarations of the same concept should be grouped in a schema file (e.g. a single ACPI table). The declarations may be grouped further using namespaces (e.g. IO or local interrupt controllers) \item[Sections/Text] Additional information can be provided using text blocks and sections. Each declaration can be wrapped in a section. \end{description} \todo{which conventions do we actually want} \section{The Skate File} A Skate file must consist of zero or more \emph{import} declarations (see Section~\ref{sec:decl:schema}) followed by a single \emph{schema} declaration (see Section~\ref{sec:decl:schema}) which contains the actual definitions. The Skate file typically has the extension \emph{*.sks}, referring to a Skate (or SKB) schema. \begin{syntax} /* Header comments */ (\synbf{import} schema)* /* the actual schema declaration */ \synbf{schema} theschema "" \verb+{+...\verb+}+ \end{syntax} Note that all imports must be stated at the beginning of the file. Comments can be inserted at any place. %\begin{align*} % skatefile & \rightarrow ( Import )^{\textrm{*}} (Schema) %\end{align*} \section{Imports}\label{sec:decl:import} An import statement makes the definitions in a different schema file available in the current schema definition, as described below. The syntax of an import declaration is as follows: \paragraph{Syntax} \begin{syntax} \synbf{import} \synit{schema}; \end{syntax} \paragraph{Fields} \begin{description} \item[schema] is the name of the schema to import definitions from. \end{description} The order of the imports does not matter to skate. At compile time, the Skate compiler will try to resolve the imports by searching the include paths and the path of the current schema file for an appropriate schema file. Imported files are parsed at the same time as the main schema file. The Skate compiler will attempt to parse all the imports of the imported files transitively. Cyclic dependencies between device files will not cause errors, but at present are unlikely to result in C header files which will successfully compile. \section{Types}\label{sec:decl:types} The Skate type system consists of a set of built in types and a set of implicit type definitions based on the declarations of the schema. Skate performs some checks on the use of types. \subsection{BuiltIn Types} Skate supports the common C-like types such as integers, floats, chars as well as boolean values and Strings (character arrays). In addition, Skate treats the Barrelfish capability reference (\texttt{struct capref}) as a built in type. \begin{syntax} UInt8, UInt16, UInt32, UInt64, UIntPtr Int8, Int16, Int32, Int64, IntPtr Float, Double Char, String Bool Capref \end{syntax} \subsection{Declaring Types} All declarations stated in Section~\ref{sec:decl:decls} are implicitly types and can be used within the fact declarations. This can restrict the values that are valid in a field. The syntax of the declarations enforces certain restrictions on which types can be used in the given context. In particular, fact declarations allow fields to be of type fact which allows a notion of inheritance and common abstractions. For example, PCI devices and USB devices may implement a specialization of the device abstraction. Note, cicular dependencies must be avoided. Defining type aliases using a a C-Like typedef is currently not supported. \section{Schema}\label{sec:decl:schema} A schema groups all the facts of a particular topic together. For example, a schema could be the PCI Express devices, memory regions or an ACPI table. Each schema must have a unique name, which must match the name of the file, and it must have at least one declaration to be considered a valid file. All checks that are being executed by Skate are stated in Chapter~\ref{chap:astops}. There can only be one schema declaration in a single Schema file. \paragraph{Syntax} \begin{syntax} \synbf{schema} \synit{name} "\synit{description}" \verb+{+ \synit{declaration}; \ldots \verb+}+; \end{syntax} \paragraph{Fields} \begin{description} \item[name] is an identifier for the Schema type, and will be used to generate identifiers in the target language (typically C). The name of the schema \emph{must} correspond to the filename of the file, including case sensitivity: for example, the file \texttt{cpuid.sks} will define a schema type of name \texttt{cpuid}. \item [description] is a string literal in double quotes, which describes the schema type being specified, for example \texttt{"CPUID Information Schema"}. \item [declaration] must contain at least one of the following declarations: \begin{itemize} \item namespace -- Section \ref{sec:decl:namespace} \item flags -- Section \ref{sec:decl:flags} \item constants -- Section \ref{sec:decl:constants} \item enumeration -- Section \ref{sec:decl:enums} \item facts -- Section \ref{sec:decl:facts} \item section -- Section \ref{sec:doc:section} \item text -- Section \ref{sec:doc:text} \end{itemize} \end{description} \section{Namespaces} \label{sec:decl:namespace} The idea of a namespaces is to provide more hierarchical structure similar to Java packages or URIs (schema.namespace.namespace) For example, a PCI devices may have virtual and physical functions or a processor has multiple cores. Namespaces can be nested within a schema to build a deeper hierarchy. Namespaces will have an effect on the code generation. \todo{does everything has to live in a namespace?, or is there an implicit default namespace?} \paragraph{Syntax} \begin{syntax} \synbf{namespace} \synit{name} "\synit{description}" \verb+{+ \synit{declaration}; \ldots \verb+}+; \end{syntax} \paragraph{Fields} \begin{description} \item[name] the identifier of this namespace. \item[description] human readable description of this namespace \item[declarations] One or more declarations that are valid a schema definition. \end{description} \section{Declarations}\label{sec:decl:decls} In this section we define the syntax for the possible fact, constant, flags and enumeration declarations in Skate. Each of the following declarations will define a type and can be used. \subsection{Flags} \label{sec:decl:flags} Flags are bit fields of a fixed size (8, 16, 32, 64 bits) where each bit position has a specific meaning e.g. the CPU is enabled or an interrupt is edge-triggered. In contrast to constants and enumerations, the bit positions of the flags have a particular meaning and two flags can be combined effectively enabling both options whereas the combination of enumeration values or constants may not be defined. Bit positions that are not defined in the flag group are treated as zero. As an example of where to use the flags use case we take the GICC CPU Interface flags as defined in the MADT Table of the ACPI specification. \begin{tabular}{lll} \textbf{Flag} & \textbf{Bit} & \textbf{Description} \\ \hline Enabled & 0 & If zero, this processor is unusable.\\ Performance Interrupt Mode & 1 & 0 - Level-triggered,\\ VGIC Maintenance Interrupt Mode & 2 & 0 - Level-triggered, 1 - Edge-Triggered \\ Reserved & 3..31 & Reserved \\ \hline \end{tabular} \subsubsection{Syntax} \begin{syntax} \synbf{flags} \synit{name} \synit{width} "\synit{description}" \verb+{+ \synit{position1} \synit{name1} "\synit{description1}" ; \ldots \verb+}+; \end{syntax} \subsubsection{Fields} \begin{description} \item[name] the identifier of this flag group. Must be unique for all declarations. \item [width] The width in bits of this flag group. Defines the maximum number of flags supported. This is one of 8, 16, 32, 64. \item [description] description in double quotes is a short explanation of what the flag group represents. \item [name1] identifier of the flag. Must be unique within the flag group. \item [position1] integer defining which bit position the flag sets \item [description1] description of this particular flag. \end{description} \subsubsection{Type} Flags with identifier $name$ define the following type: \begin{syntax} \synbf{flag} \synit{name}; \end{syntax} \subsubsection{Example} The example from the ACPI table can be expressed in Skate as follows: \begin{syntax} \synbf{flags} CPUInterfaceFlags \synit{32} "\synit{GICC CPU Interface Flags}"\ \verb+{+ 0 Enabled "\synit{The CPU is enabled and can be used}" ; 1 Performance "\synit{Performance Interrupt Mode Edge-Triggered }" ; 1 VGICMaintenance "\synit{VGIC Maintenance Interrupt Mode Edge-Triggered}" ; \verb+}+; \end{syntax} \subsection{Constants} \label{sec:decl:constants} Constants provide a way to specify a set of predefined values of a particular type. They are defined in a constant group and every constant of this group needs to be of the same type. Compared to flags, the combination of two constants has no meaning (e.g. adding two version numbers). In addition, constants only define a set of known values, but do not rule out the possibility of observing other values. As an example for this may be the vendor ID of a PCI Expess device, where the constant group contains the known vendor IDs. As an example where constants ca be used we take the GIC version field of the GICD entry of the ACPI MADT Table. \begin{tabular}{ll} \textbf{Value} & \textbf{Meaning} \\ \hline \texttt{0x00} & No GIC version is specified, fall back to hardware discovery for GIC version \\ \texttt{0x01} & Controller is a GICv1 \\ \texttt{0x02} & Controller is a GICv2 \\ \texttt{0x03} & Controller is a GICv3 \\ \texttt{0x04} & Controller is a GICv4 \\ \texttt{0x05-0xFF} & Reserved for future use. \\ \hline \end{tabular} \subsubsection{Syntax} \begin{syntax} \synbf{constants} \synit{name} \synit{builtintype} "\synit{description}" \verb+{+ \synit{name1} = \synit{value1} "\synit{description1}" ; \ldots \verb+}+; \end{syntax} \subsubsection{Fields} \begin{description} \item[name] the identifier of this constants group. Must be unique for all declarations. \item [builtintype] the type of the constant group. Must be one of the builtin types as defined in~\ref{sec:decl:types} \item [description] description in double quotes is a short explanation of what the constant group represents. \item [name1] identifier of the constant. Must be unique within the constant group. \item [value1] the value of the constant. Must match the declared type. \item [description1] description of this particular constant \end{description} \subsubsection{Type} Constants with identifier $name$ define the following type: \begin{syntax} \synbf{const} \synit{name}; \end{syntax} \subsubsection{Example} The GIC version of our example can be expressed in the syntax as follows: \begin{syntax} \synbf{constants} GICVersion \synit{uint8} "\synit{The GIC Version}" \verb+{+ unspecified = 0x00 "\synit{No GIC version is specified}" ; GICv1 = 0x01 "\synit{Controller is a GICv1}" ; GICv2 = 0x02 "\synit{Controller is a GICv2}" ; GICv3 = 0x03 "\synit{Controller is a GICv3}" ; GICv4 = 0x04 "\synit{Controller is a GICv4}" ; \verb+}+; \end{syntax} \subsection{Enumerations} \label{sec:decl:enums} Enumerations model a finite set of states effectively constants that only allow the specified values. However, in contrast to constants they are not assigned an specific value. Two enumeration values cannot be combined. As an example, the enumeration construct can be used to express the state of a device in the system which can be in one of the following states: \emph{uninitialized, operational, suspended, halted.} It's obvious, that the combination of the states operational and suspended is meaning less. \subsubsection{Syntax} \begin{syntax} \synbf{enumeration} \synit{name} "\synit{description}" \verb+{+ \synit{name1} "\synit{description1}"; \ldots \verb+}+; \end{syntax} \subsubsection{Fields} \begin{description} \item[name] the identifier of this enumeration group. Must be unique for all declarations. \item [description] description in double quotes is a short explanation of what the enumeration group represents. \item [name1] identifier of the element. Must be unique within the enumeration group. \item [description1] description of this particular element \end{description} \subsubsection{Type} Enumerations with identifier $name$ define the following type: \begin{syntax} \synbf{enum} \synit{name}; \end{syntax} \subsubsection{Example} \begin{syntax} \synbf{enumeration} DeviceState "\synit{Possible device states}" \verb+{+ uninitialized "\synit{The device is uninitialized}"; operational "\synit{The device is operaetional}"; suspended "\synit{The device is suspended}"; halted "\synit{The device is halted}"; \verb+}+; \end{syntax} \subsection{Facts} \label{sec:decl:facts} The fact is the central element of Skate. It defines the actual facts about the system that are put into the SKB. Each fact has a name and one or more fields of a given type. Facts should be defined such that they do not require any transformation. For example, take the entries of an ACPI table and define a fact for each of the entry types. \subsubsection{Syntax} \begin{syntax} \synbf{fact} \synit{name} "\synit{description}" \verb+{+ \synit{type1} \synit{name1} "\synit{description1}" ; \ldots \verb+}+; \end{syntax} \subsubsection{Fields} \begin{description} \item[name] the identifier of this fact. Must be unique for all declarations. \item[description] description in double quotes is a short English explanation of what the fact defines. (e.g. Local APIC) \item[type1] the type of the fact field. Must be one of the BuiltIn types or one of the constants, flags or other facts. When using facts as field types, there must be no recursive nesting. \item [name1] identifier of a fact field. Must be unique within the Fact group. \item [description1] description of this particular field \end{description} \subsubsection{Type} Facts with identifier $name$ define the following type. \begin{syntax} \synbf{fact} \synit{name}; \end{syntax} \section{Documentation} The schema declaration may contain \emph{section} and \emph{text} blocks that allow providing an introduction or additional information for the schema declared in the Skate file. The two constructs are for documentation purpose only and do not affect code generation. The section and text blocks can appear at any place in the Schema declaration. There is no type being defined for documentation blocks. \subsection{Schema} The generated documentation will contain all the schemas declared in the source tree. The different schema files correspond to chapters in the resulting documentation or form a page of a Wiki for instance. \subsection{Text} \label{sec:doc:text} By adding \texttt{text} blocks, additional content can be added to the generated documentation. This includes examples and additional information of the declarations of the schema. The text blocks are omitted when generating code. Note, each of the text lines must be wrapped in double quotes. Generally, a block of text will translate to a paragraph. \subsubsection{Syntax} \begin{syntax} \synbf{text} \verb+{+ "\synit{text}" ... \verb+};+ \end{syntax} \subsubsection{Fields} \begin{description} \item[text] A line of text in double quotes. \end{description} \subsection{Sections} \label{sec:doc:section} The \texttt{section} construct allows to insert section headings into the documentation. A section logically groups the declarations and text blocks together to allow expressing a logical hierarchy. \subsubsection{Syntax} \begin{syntax} \synbf{section} "\synit{name}" \verb+{+ \synit{declaration}; \ldots \verb+};+ \end{syntax} \subsubsection{Fields} \begin{description} \item[name] the name will be used as the section heading \item[declaration] declarations belonging to this section. \end{description} Note, nested sections will result into (sub)subheadings or heading 2, 3, ... Namespaces will appear as sections in the documentation. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \chapter{Operations and checks on the AST} \label{chap:astops} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% The following checks are executed after the parser has consumed the entire Skate file and created the AST. \section{Filename Check} As already stated, the name of the Skate (without extension) must match the identifier of the declared schema in the Skate file. This is required for resolving imports of other Schemas. \section{Uniqueness of declarations / fields} Skate ensures that all declarations within a namespace are unique no matter which type they are i.e. there cannot be a fact and a constant definition with the same identifier. Moreover, the same check is applied to the fact attributes as well as flags, enumerations and constant values. Checks are based on the qualified identifier. \section{Type Checks} \section{Sorting of Declarations} \todo{This requires generated a dependency graph for the facts etc. } %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \chapter{C mapping for Schema Definitions} \label{chap:cmapping} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% For each schema specification, Skate generates .... \paragraph{Abbrevations} In all the sections of this chapter, we use the follwing abbrevations, where the actual value may be upper or lower case depending on the conventions: \begin{description} \item[SN] The schema name as used in the schema declaration. \item[DN] The declaration name as used in the flags / constants / enumeration / facts declaration \item[FN] The field name as used in field declaration of flags / constants / enumeration / facts \end{description} In general all defined functions, types and macros are prefixed with the schema name SN. \paragraph{Conventions} We use the follwing conventions for the generated code: \begin{itemize} \item macro definitions and enumerations are uppercase. \item type definitions, function names are lowercase. \item use of the underscore \texttt{'\_'} to separate words \end{itemize} \todo{just a header file (cf mackerel), or also C functions (cf. flounder)?} \section{Using Schemas} Developers can use the schemas by including the generated header file of a schema. All header files are placed in the schema subdirectory of the main include folder of the build tree. For example, the schema \texttt{SN} would generate the file \texttt{SN\_schema.h} and can be included by a C program with: \begin{quote} \texttt{\#include