doc/manual.html

<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="generator" content="Asciidoctor 2.0.23">
<meta name="author" content="Alasdair Armstrong, Thomas Bauereiss, Brian Campbell, Shaked Flur, Kathryn E. Gray, Robert Norton-Wright, Christopher Pulte, Peter Sewell">
<title>The Sail instruction-set semantics specification language</title>
<style>
/*! Asciidoctor default stylesheet | MIT License | https://asciidoctor.org */
/* Uncomment the following line when using as a custom stylesheet */
@import "https://fonts.googleapis.com/css?family=Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CDroid+Sans+Mono:400,700";
html {
  font-family: sans-serif;
  -webkit-text-size-adjust: 100%;
}

a {
  background: none;
}

a:focus {
  outline: thin dotted;
}

a:active,
a:hover {
  outline: 0;
}

h1 {
  font-size: 1em;
  margin: 0.67em 0;
}

b,
strong {
  font-weight: bold;
}

abbr {
  font-size: 0.9em;
}

abbr[title] {
  cursor: help;
  border-bottom: 1px dotted #dddddf;
  text-decoration: none;
}

dfn {
  font-style: italic;
}

hr {
  height: 0;
}

mark {
  background: #ff0;
  color: #000;
}

code,
kbd,
pre,
samp {
  font-family: monospace;
  font-size: 1em;
}

pre {
  white-space: pre-wrap;
}

q {
  quotes: "\201C" "\201D" "\2018" "\2019";
}

small {
  font-size: 80%;
}

sub,
sup {
  font-size: 75%;
  line-height: 0;
  position: relative;
  vertical-align: baseline;
}

sup {
  top: -0.5em;
}

sub {
  bottom: -0.25em;
}

img {
  border: 0;
}

svg:not(:root) {
  overflow: hidden;
}

figure {
  margin: 0;
}

audio,
video {
  display: inline-block;
}

audio:not([controls]) {
  display: none;
  height: 0;
}

fieldset {
  border: 1px solid silver;
  margin: 0 2px;
  padding: 0.35em 0.625em 0.75em;
}

legend {
  border: 0;
  padding: 0;
}

button,
input,
select,
textarea {
  font-family: inherit;
  font-size: 100%;
  margin: 0;
}

button,
input {
  line-height: normal;
}

button,
select {
  text-transform: none;
}

button,
html input[type=button],
input[type=reset],
input[type=submit] {
  -webkit-appearance: button;
  cursor: pointer;
}

button[disabled],
html input[disabled] {
  cursor: default;
}

input[type=checkbox],
input[type=radio] {
  padding: 0;
}

button::-moz-focus-inner,
input::-moz-focus-inner {
  border: 0;
  padding: 0;
}

textarea {
  overflow: auto;
  vertical-align: top;
}

table {
  border-collapse: collapse;
  border-spacing: 0;
}

*,
::before,
::after {
  box-sizing: border-box;
}

html,
body {
  font-size: 100%;
}

body {
  background: #fff;
  color: rgba(0, 0, 0, 0.8);
  padding: 0;
  margin: 0;
  font-family: "Noto Serif", "DejaVu Serif", serif;
  line-height: 1;
  position: relative;
  cursor: auto;
  tab-size: 4;
  word-wrap: anywhere;
  -moz-osx-font-smoothing: grayscale;
  -webkit-font-smoothing: antialiased;
}

a:hover {
  cursor: pointer;
}

img,
object,
embed {
  max-width: 100%;
  height: auto;
}

object,
embed {
  height: 100%;
}

img {
  -ms-interpolation-mode: bicubic;
}

.left {
  float: left !important;
}

.right {
  float: right !important;
}

.text-left {
  text-align: left !important;
}

.text-right {
  text-align: right !important;
}

.text-center {
  text-align: center !important;
}

.text-justify {
  text-align: justify !important;
}

.hide {
  display: none;
}

img,
object,
svg {
  display: inline-block;
  vertical-align: middle;
}

textarea {
  height: auto;
  min-height: 50px;
}

select {
  width: 100%;
}

.subheader,
.admonitionblock td.content > .title,
.audioblock > .title,
.exampleblock > .title,
.imageblock > .title,
.listingblock > .title,
.literalblock > .title,
.stemblock > .title,
.openblock > .title,
.paragraph > .title,
.quoteblock > .title,
table.tableblock > .title,
.verseblock > .title,
.videoblock > .title,
.dlist > .title,
.olist > .title,
.ulist > .title,
.qlist > .title,
.hdlist > .title {
  line-height: 1.45;
  color: #7a2518;
  font-weight: 400;
  margin-top: 0;
  margin-bottom: 0.25em;
}

div,
dl,
dt,
dd,
ul,
ol,
li,
h1,
h2,
h3,
#toctitle,
.sidebarblock > .content > .title,
h4,
h5,
h6,
pre,
form,
p,
blockquote,
th,
td {
  margin: 0;
  padding: 0;
}

a {
  color: #2156a5;
  text-decoration: underline;
  line-height: inherit;
}

a:hover,
a:focus {
  color: #1d4b8f;
}

a img {
  border: 0;
}

p {
  line-height: 1.6;
  margin-bottom: 1.25em;
  text-rendering: optimizeLegibility;
}

p aside {
  font-size: 0.875em;
  line-height: 1.35;
  font-style: italic;
}

h1,
h2,
h3,
#toctitle,
.sidebarblock > .content > .title,
h4,
h5,
h6 {
  font-family: "Open Sans", "DejaVu Sans", sans-serif;
  font-weight: 400;
  font-style: normal;
  color: #733700;
  text-rendering: optimizeLegibility;
  margin-top: 1em;
  margin-bottom: 0.5em;
  line-height: 1.0125em;
}

h1 small,
h2 small,
h3 small,
#toctitle small,
.sidebarblock > .content > .title small,
h4 small,
h5 small,
h6 small {
  font-size: 60%;
  color: #e99b8f;
  line-height: 0;
}

h1 {
  font-size: 2.125em;
}

h2 {
  font-size: 1.6875em;
}

h3,
#toctitle,
.sidebarblock > .content > .title {
  font-size: 1.375em;
}

h4,
h5 {
  font-size: 1.125em;
}

h6 {
  font-size: 1em;
}

hr {
  border: solid #dddddf;
  border-width: 1px 0 0;
  clear: both;
  margin: 1.25em 0 1.1875em;
}

em,
i {
  font-style: italic;
  line-height: inherit;
}

strong,
b {
  font-weight: bold;
  line-height: inherit;
}

small {
  font-size: 60%;
  line-height: inherit;
}

code {
  font-family: "Droid Sans Mono", "DejaVu Sans Mono", monospace;
  font-weight: 400;
  color: rgba(0, 0, 0, 0.9);
}

ul,
ol,
dl {
  line-height: 1.6;
  margin-bottom: 1.25em;
  list-style-position: outside;
  font-family: inherit;
}

ul,
ol {
  margin-left: 1.5em;
}

ul li ul,
ul li ol {
  margin-left: 1.25em;
  margin-bottom: 0;
}

ul.circle {
  list-style-type: circle;
}

ul.disc {
  list-style-type: disc;
}

ul.square {
  list-style-type: square;
}

ul.circle ul:not([class]),
ul.disc ul:not([class]),
ul.square ul:not([class]) {
  list-style: inherit;
}

ol li ul,
ol li ol {
  margin-left: 1.25em;
  margin-bottom: 0;
}

dl dt {
  margin-bottom: 0.3125em;
  font-weight: bold;
}

dl dd {
  margin-bottom: 1.25em;
}

blockquote {
  margin: 0 0 1.25em;
  padding: 0.5625em 1.25em 0 1.1875em;
  border-left: 1px solid #ddd;
}

blockquote,
blockquote p {
  line-height: 1.6;
  color: rgba(0, 0, 0, 0.85);
}

@media screen and (min-width: 768px) {
  h1,
  h2,
  h3,
  #toctitle,
  .sidebarblock > .content > .title,
  h4,
  h5,
  h6 {
    line-height: 1.2;
  }

  h1 {
    font-size: 2.3em;
  }

  h2 {
    font-size: 2.3125em;
  }

  h3,
  #toctitle,
  .sidebarblock > .content > .title {
    font-size: 1.6875em;
  }

  h4 {
    font-size: 1.4375em;
  }
}

table {
  background: #fff;
  margin-bottom: 1.25em;
  border: 1px solid #dedede;
  word-wrap: normal;
}

table thead,
table tfoot {
  background: #f7f8f7;
}

table thead tr th,
table thead tr td,
table tfoot tr th,
table tfoot tr td {
  padding: 0.5em 0.625em 0.625em;
  font-size: inherit;
  color: rgba(0, 0, 0, 0.8);
  text-align: left;
}

table tr th,
table tr td {
  padding: 0.5625em 0.625em;
  font-size: inherit;
  color: rgba(0, 0, 0, 0.8);
}

table tr.even,
table tr.alt {
  background: #f8f8f7;
}

table thead tr th,
table tfoot tr th,
table tbody tr td,
table tr td,
table tfoot tr td {
  line-height: 1.6;
}

h1,
h2,
h3,
#toctitle,
.sidebarblock > .content > .title,
h4,
h5,
h6 {
  line-height: 1.2;
  word-spacing: -0.05em;
}

h1 strong,
h2 strong,
h3 strong,
#toctitle strong,
.sidebarblock > .content > .title strong,
h4 strong,
h5 strong,
h6 strong {
  font-weight: 400;
}

.center {
  margin-left: auto;
  margin-right: auto;
}

.stretch {
  width: 100%;
}

.clearfix::before,
.clearfix::after,
.float-group::before,
.float-group::after {
  content: " ";
  display: table;
}

.clearfix::after,
.float-group::after {
  clear: both;
}

:not(pre).nobreak {
  word-wrap: normal;
}

:not(pre).nowrap {
  white-space: nowrap;
}

:not(pre).pre-wrap {
  white-space: pre-wrap;
}

:not(pre):not([class^=L]) > code {
  font-size: 0.9375em;
  font-style: normal !important;
  letter-spacing: 0;
  padding: 0.1em 0.5ex;
  word-spacing: -0.15em;
  background: #f7f7f8;
  border-radius: 4px;
  line-height: 1.45;
  text-rendering: optimizeSpeed;
}

pre {
  color: rgba(0, 0, 0, 0.9);
  font-family: "Droid Sans Mono", "DejaVu Sans Mono", monospace;
  line-height: 1.45;
  text-rendering: optimizeSpeed;
}

pre code,
pre pre {
  color: inherit;
  font-size: inherit;
  line-height: inherit;
}

pre > code {
  display: block;
}

pre.nowrap,
pre.nowrap pre {
  white-space: pre;
  word-wrap: normal;
}

em em {
  font-style: normal;
}

strong strong {
  font-weight: 400;
}

.keyseq {
  color: rgba(51, 51, 51, 0.8);
}

kbd {
  font-family: "Droid Sans Mono", "DejaVu Sans Mono", monospace;
  display: inline-block;
  color: rgba(0, 0, 0, 0.8);
  font-size: 0.65em;
  line-height: 1.45;
  background: #f7f7f7;
  border: 1px solid #ccc;
  border-radius: 3px;
  box-shadow: 0 1px 0 rgba(0, 0, 0, 0.2), 0 0 0 0.1em #fff inset;
  margin: 0 0.15em;
  padding: 0.2em 0.5em;
  vertical-align: middle;
  position: relative;
  top: -0.1em;
  white-space: nowrap;
}

.keyseq kbd:first-child {
  margin-left: 0;
}

.keyseq kbd:last-child {
  margin-right: 0;
}

.menuseq,
.menuref {
  color: #000;
}

.menuseq b:not(.caret),
.menuref {
  font-weight: inherit;
}

.menuseq {
  word-spacing: -0.02em;
}

.menuseq b.caret {
  font-size: 1.25em;
  line-height: 0.8;
}

.menuseq i.caret {
  font-weight: bold;
  text-align: center;
  width: 0.45em;
}

b.button::before,
b.button::after {
  position: relative;
  top: -1px;
  font-weight: 400;
}

b.button::before {
  content: "[";
  padding: 0 3px 0 2px;
}

b.button::after {
  content: "]";
  padding: 0 2px 0 3px;
}

p a > code:hover {
  color: rgba(0, 0, 0, 0.9);
}

#header,
#content,
#footnotes,
#footer {
  width: 100%;
  margin: 0 auto;
  max-width: 62.5em;
  *zoom: 1;
  position: relative;
  padding-left: 0.9375em;
  padding-right: 0.9375em;
}

#header::before,
#header::after,
#content::before,
#content::after,
#footnotes::before,
#footnotes::after,
#footer::before,
#footer::after {
  content: " ";
  display: table;
}

#header::after,
#content::after,
#footnotes::after,
#footer::after {
  clear: both;
}

#content {
  margin-top: 1.25em;
}

#content::before {
  content: none;
}

#header > h1:first-child {
  color: rgba(0, 0, 0, 0.85);
  margin-top: 2.25rem;
  margin-bottom: 0;
}

#header > h1:first-child + #toc {
  margin-top: 8px;
  border-top: 1px solid #dddddf;
}

#header > h1:only-child,
body.toc2 #header > h1:nth-last-child(2) {
  border-bottom: 1px solid #dddddf;
  padding-bottom: 8px;
}

#header .details {
  border-bottom: 1px solid #dddddf;
  line-height: 1.45;
  padding-top: 0.25em;
  padding-bottom: 0.25em;
  padding-left: 0.25em;
  color: rgba(0, 0, 0, 0.6);
  display: flex;
  flex-flow: row wrap;
}

#header .details span:first-child {
  margin-left: -0.125em;
}

#header .details span.email a {
  color: rgba(0, 0, 0, 0.85);
}

#header .details br {
  display: none;
}

#header .details br + span::before {
  content: "\00a0\2013\00a0";
}

#header .details br + span.author::before {
  content: "\00a0\22c5\00a0";
  color: rgba(0, 0, 0, 0.85);
}

#header .details br + span#revremark::before {
  content: "\00a0|\00a0";
}

#header #revnumber {
  text-transform: capitalize;
}

#header #revnumber::after {
  content: "\00a0";
}

#content > h1:first-child:not([class]) {
  color: rgba(0, 0, 0, 0.85);
  border-bottom: 1px solid #dddddf;
  padding-bottom: 8px;
  margin-top: 0;
  padding-top: 1rem;
  margin-bottom: 1.25rem;
}

#toc {
  border-bottom: 1px solid #e7e7e9;
  padding-bottom: 0.5em;
}

#toc > ul {
  margin-left: 0.125em;
}

#toc ul.sectlevel0 > li > a {
  font-style: italic;
}

#toc ul.sectlevel0 ul.sectlevel1 {
  margin: 0.5em 0;
}

#toc ul {
  font-family: "Open Sans", "DejaVu Sans", sans-serif;
  list-style-type: none;
}

#toc li {
  line-height: 1.3334;
  margin-top: 0.3334em;
}

#toc a {
  text-decoration: none;
  color: #FFFFFF;
}

#toc a:active {
  text-decoration: underline;
}

#toctitle {
  color: #FFEBCC;
  font-size: 1.3em;
}

@media screen and (min-width: 768px) {
  #toctitle {
    font-size: 1.375em;
  }

  body.toc2 {
    padding-left: 15em;
    padding-right: 0;
  }

  #toc.toc2 {
    margin-top: 0 !important;
    background: #239DD5;
    position: fixed;
    width: 15em;
    left: 0;
    top: 0;
    border-right: 1px solid #e7e7e9;
    border-top-width: 0 !important;
    border-bottom-width: 0 !important;
    z-index: 1000;
    padding: 1.25em 1em;
    height: 100%;
    overflow: auto;
  }

  #toc.toc2 #toctitle {
    margin-top: 0;
    margin-bottom: 0.8rem;
    font-size: 1.2em;
  }

  #toc.toc2 > ul {
    font-size: 0.9em;
    margin-bottom: 0;
  }

  #toc.toc2 ul ul {
    margin-left: 0;
    padding-left: 1em;
  }

  #toc.toc2 ul.sectlevel0 ul.sectlevel1 {
    padding-left: 0;
    margin-top: 0.5em;
    margin-bottom: 0.5em;
  }

  body.toc2.toc-right {
    padding-left: 0;
    padding-right: 15em;
  }

  body.toc2.toc-right #toc.toc2 {
    border-right-width: 0;
    border-left: 1px solid #e7e7e9;
    left: auto;
    right: 0;
  }
}

@media screen and (min-width: 1280px) {
  body.toc2 {
    padding-left: 20em;
    padding-right: 0;
  }

  #toc.toc2 {
    width: 20em;
  }

  #toc.toc2 #toctitle {
    font-size: 1.375em;
  }

  #toc.toc2 > ul {
    font-size: 0.95em;
  }

  #toc.toc2 ul ul {
    padding-left: 1.25em;
  }

  body.toc2.toc-right {
    padding-left: 0;
    padding-right: 20em;
  }
}

#content #toc {
  border: 1px solid #e0e0dc;
  margin-bottom: 1.25em;
  padding: 1.25em;
  background: #f8f8f7;
  border-radius: 4px;
}

#content #toc > :first-child {
  margin-top: 0;
}

#content #toc > :last-child {
  margin-bottom: 0;
}

#footer {
  max-width: none;
  background: rgba(0, 0, 0, 0.8);
  padding: 1.25em;
}

#footer-text {
  color: rgba(255, 255, 255, 0.8);
  line-height: 1.44;
}

#content {
  margin-bottom: 0.625em;
}

.sect1 {
  padding-bottom: 0.625em;
}

@media screen and (min-width: 768px) {
  #content {
    margin-bottom: 1.25em;
  }

  .sect1 {
    padding-bottom: 1.25em;
  }
}

.sect1:last-child {
  padding-bottom: 0;
}

.sect1 + .sect1 {
  border-top: 1px solid #e7e7e9;
}

#content h1 > a.anchor,
h2 > a.anchor,
h3 > a.anchor,
#toctitle > a.anchor,
.sidebarblock > .content > .title > a.anchor,
h4 > a.anchor,
h5 > a.anchor,
h6 > a.anchor {
  position: absolute;
  z-index: 1001;
  width: 1.5ex;
  margin-left: -1.5ex;
  display: block;
  text-decoration: none !important;
  visibility: hidden;
  text-align: center;
  font-weight: 400;
}

#content h1 > a.anchor::before,
h2 > a.anchor::before,
h3 > a.anchor::before,
#toctitle > a.anchor::before,
.sidebarblock > .content > .title > a.anchor::before,
h4 > a.anchor::before,
h5 > a.anchor::before,
h6 > a.anchor::before {
  content: "\00A7";
  font-size: 0.85em;
  display: block;
  padding-top: 0.1em;
}

#content h1:hover > a.anchor,
#content h1 > a.anchor:hover,
h2:hover > a.anchor,
h2 > a.anchor:hover,
h3:hover > a.anchor,
#toctitle:hover > a.anchor,
.sidebarblock > .content > .title:hover > a.anchor,
h3 > a.anchor:hover,
#toctitle > a.anchor:hover,
.sidebarblock > .content > .title > a.anchor:hover,
h4:hover > a.anchor,
h4 > a.anchor:hover,
h5:hover > a.anchor,
h5 > a.anchor:hover,
h6:hover > a.anchor,
h6 > a.anchor:hover {
  visibility: visible;
}

#content h1 > a.link,
h2 > a.link,
h3 > a.link,
#toctitle > a.link,
.sidebarblock > .content > .title > a.link,
h4 > a.link,
h5 > a.link,
h6 > a.link {
  color: #ba3925;
  text-decoration: none;
}

#content h1 > a.link:hover,
h2 > a.link:hover,
h3 > a.link:hover,
#toctitle > a.link:hover,
.sidebarblock > .content > .title > a.link:hover,
h4 > a.link:hover,
h5 > a.link:hover,
h6 > a.link:hover {
  color: #a53221;
}

details,
.audioblock,
.imageblock,
.literalblock,
.listingblock,
.stemblock,
.videoblock {
  margin-bottom: 1.25em;
}

details {
  margin-left: 1.25rem;
}

details > summary {
  cursor: pointer;
  display: block;
  position: relative;
  line-height: 1.6;
  margin-bottom: 0.625rem;
  outline: none;
  -webkit-tap-highlight-color: transparent;
}

details > summary::-webkit-details-marker {
  display: none;
}

details > summary::before {
  content: "";
  border: solid transparent;
  border-left-color: currentColor;
  border-width: 0.3em 0 0.3em 0.5em;
  position: absolute;
  top: 0.5em;
  left: -1.25rem;
  transform: translateX(15%);
}

details[open] > summary::before {
  border: solid transparent;
  border-top-color: currentColor;
  border-width: 0.5em 0.3em 0;
  transform: translateY(15%);
}

details > summary::after {
  content: "";
  width: 1.25rem;
  height: 1em;
  position: absolute;
  top: 0.3em;
  left: -1.25rem;
}

.admonitionblock td.content > .title,
.audioblock > .title,
.exampleblock > .title,
.imageblock > .title,
.listingblock > .title,
.literalblock > .title,
.stemblock > .title,
.openblock > .title,
.paragraph > .title,
.quoteblock > .title,
table.tableblock > .title,
.verseblock > .title,
.videoblock > .title,
.dlist > .title,
.olist > .title,
.ulist > .title,
.qlist > .title,
.hdlist > .title {
  text-rendering: optimizeLegibility;
  text-align: left;
  font-family: "Noto Serif", "DejaVu Serif", serif;
  font-size: 1rem;
  font-style: italic;
}

table.tableblock.fit-content > caption.title {
  white-space: nowrap;
  width: 0;
}

.paragraph.lead > p,
#preamble > .sectionbody > [class=paragraph]:first-of-type p {
  font-size: 1.21875em;
  line-height: 1.6;
  color: rgba(0, 0, 0, 0.85);
}

.admonitionblock > table {
  border-collapse: separate;
  border: 0;
  background: none;
  width: 100%;
}

.admonitionblock > table td.icon {
  text-align: center;
  width: 80px;
}

.admonitionblock > table td.icon img {
  max-width: none;
}

.admonitionblock > table td.icon .title {
  font-weight: bold;
  font-family: "Open Sans", "DejaVu Sans", sans-serif;
  text-transform: uppercase;
}

.admonitionblock > table td.content {
  padding-left: 1.125em;
  padding-right: 1.25em;
  border-left: 1px solid #dddddf;
  color: rgba(0, 0, 0, 0.6);
  word-wrap: anywhere;
}

.admonitionblock > table td.content > :last-child > :last-child {
  margin-bottom: 0;
}

.exampleblock > .content {
  border: 1px solid #e6e6e6;
  margin-bottom: 1.25em;
  padding: 1.25em;
  background: #fff;
  border-radius: 4px;
}

.sidebarblock {
  border: 1px solid #dbdbd6;
  margin-bottom: 1.25em;
  padding: 1.25em;
  background: #f3f3f2;
  border-radius: 4px;
}

.sidebarblock > .content > .title {
  color: #7a2518;
  margin-top: 0;
  text-align: center;
}

.exampleblock > .content > :first-child,
.sidebarblock > .content > :first-child {
  margin-top: 0;
}

.exampleblock > .content > :last-child,
.exampleblock > .content > :last-child > :last-child,
.exampleblock > .content .olist > ol > li:last-child > :last-child,
.exampleblock > .content .ulist > ul > li:last-child > :last-child,
.exampleblock > .content .qlist > ol > li:last-child > :last-child,
.sidebarblock > .content > :last-child,
.sidebarblock > .content > :last-child > :last-child,
.sidebarblock > .content .olist > ol > li:last-child > :last-child,
.sidebarblock > .content .ulist > ul > li:last-child > :last-child,
.sidebarblock > .content .qlist > ol > li:last-child > :last-child {
  margin-bottom: 0;
}

.literalblock pre,
.listingblock > .content > pre {
  border-radius: 4px;
  overflow-x: auto;
  padding: 1em;
  font-size: 0.8125em;
}

@media screen and (min-width: 768px) {
  .literalblock pre,
  .listingblock > .content > pre {
    font-size: 0.90625em;
  }
}

@media screen and (min-width: 1280px) {
  .literalblock pre,
  .listingblock > .content > pre {
    font-size: 1em;
  }
}

.literalblock pre,
.listingblock > .content > pre:not(.highlight),
.listingblock > .content > pre[class=highlight],
.listingblock > .content > pre[class^="highlight "] {
  background: #f7f7f8;
}

.literalblock.output pre {
  color: #f7f7f8;
  background: rgba(0, 0, 0, 0.9);
}

.listingblock > .content {
  position: relative;
}

.listingblock code[data-lang]::before {
  display: none;
  content: attr(data-lang);
  position: absolute;
  font-size: 0.75em;
  top: 0.425rem;
  right: 0.5rem;
  line-height: 1;
  text-transform: uppercase;
  color: inherit;
  opacity: 0.5;
}

.listingblock:hover code[data-lang]::before {
  display: block;
}

.listingblock.terminal pre .command::before {
  content: attr(data-prompt);
  padding-right: 0.5em;
  color: inherit;
  opacity: 0.5;
}

.listingblock.terminal pre .command:not([data-prompt])::before {
  content: "$";
}

.listingblock pre.highlightjs {
  padding: 0;
}

.listingblock pre.highlightjs > code {
  padding: 1em;
  border-radius: 4px;
}

.listingblock pre.prettyprint {
  border-width: 0;
}

.prettyprint {
  background: #f7f7f8;
}

pre.prettyprint .linenums {
  line-height: 1.45;
  margin-left: 2em;
}

pre.prettyprint li {
  background: none;
  list-style-type: inherit;
  padding-left: 0;
}

pre.prettyprint li code[data-lang]::before {
  opacity: 1;
}

pre.prettyprint li:not(:first-child) code[data-lang]::before {
  display: none;
}

table.linenotable {
  border-collapse: separate;
  border: 0;
  margin-bottom: 0;
  background: none;
}

table.linenotable td[class] {
  color: inherit;
  vertical-align: top;
  padding: 0;
  line-height: inherit;
  white-space: normal;
}

table.linenotable td.code {
  padding-left: 0.75em;
}

table.linenotable td.linenos,
pre.pygments .linenos {
  border-right: 1px solid;
  opacity: 0.35;
  padding-right: 0.5em;
  user-select: none;
}

pre.pygments span.linenos {
  display: inline-block;
  margin-right: 0.75em;
}

.quoteblock {
  margin: 0 1em 1.25em 1.5em;
  display: table;
}

.quoteblock:not(.excerpt) > .title {
  margin-left: -1.5em;
  margin-bottom: 0.75em;
}

.quoteblock blockquote,
.quoteblock p {
  color: rgba(0, 0, 0, 0.85);
  font-size: 1.15rem;
  line-height: 1.75;
  word-spacing: 0.1em;
  letter-spacing: 0;
  font-style: italic;
  text-align: justify;
}

.quoteblock blockquote {
  margin: 0;
  padding: 0;
  border: 0;
}

.quoteblock blockquote::before {
  content: "\201c";
  float: left;
  font-size: 2.75em;
  font-weight: bold;
  line-height: 0.6em;
  margin-left: -0.6em;
  color: #7a2518;
  text-shadow: 0 1px 2px rgba(0, 0, 0, 0.1);
}

.quoteblock blockquote > .paragraph:last-child p {
  margin-bottom: 0;
}

.quoteblock .attribution {
  margin-top: 0.75em;
  margin-right: 0.5ex;
  text-align: right;
}

.verseblock {
  margin: 0 1em 1.25em;
}

.verseblock pre {
  font-family: "Open Sans", "DejaVu Sans", sans-serif;
  font-size: 1.15rem;
  color: rgba(0, 0, 0, 0.85);
  font-weight: 300;
  text-rendering: optimizeLegibility;
}

.verseblock pre strong {
  font-weight: 400;
}

.verseblock .attribution {
  margin-top: 1.25rem;
  margin-left: 0.5ex;
}

.quoteblock .attribution,
.verseblock .attribution {
  font-size: 0.9375em;
  line-height: 1.45;
  font-style: italic;
}

.quoteblock .attribution br,
.verseblock .attribution br {
  display: none;
}

.quoteblock .attribution cite,
.verseblock .attribution cite {
  display: block;
  letter-spacing: -0.025em;
  color: rgba(0, 0, 0, 0.6);
}

.quoteblock.abstract blockquote::before,
.quoteblock.excerpt blockquote::before,
.quoteblock .quoteblock blockquote::before {
  display: none;
}

.quoteblock.abstract blockquote,
.quoteblock.abstract p,
.quoteblock.excerpt blockquote,
.quoteblock.excerpt p,
.quoteblock .quoteblock blockquote,
.quoteblock .quoteblock p {
  line-height: 1.6;
  word-spacing: 0;
}

.quoteblock.abstract {
  margin: 0 1em 1.25em;
  display: block;
}

.quoteblock.abstract > .title {
  margin: 0 0 0.375em;
  font-size: 1.15em;
  text-align: center;
}

.quoteblock.excerpt > blockquote,
.quoteblock .quoteblock {
  padding: 0 0 0.25em 1em;
  border-left: 0.25em solid #dddddf;
}

.quoteblock.excerpt,
.quoteblock .quoteblock {
  margin-left: 0;
}

.quoteblock.excerpt blockquote,
.quoteblock.excerpt p,
.quoteblock .quoteblock blockquote,
.quoteblock .quoteblock p {
  color: inherit;
  font-size: 1.0625rem;
}

.quoteblock.excerpt .attribution,
.quoteblock .quoteblock .attribution {
  color: inherit;
  font-size: 0.85rem;
  text-align: left;
  margin-right: 0;
}

p.tableblock:last-child {
  margin-bottom: 0;
}

td.tableblock > .content {
  margin-bottom: 1.25em;
  word-wrap: anywhere;
}

td.tableblock > .content > :last-child {
  margin-bottom: -1.25em;
}

table.tableblock,
th.tableblock,
td.tableblock {
  border: 0 solid #dedede;
}

table.grid-all > * > tr > * {
  border-width: 1px;
}

table.grid-cols > * > tr > * {
  border-width: 0 1px;
}

table.grid-rows > * > tr > * {
  border-width: 1px 0;
}

table.frame-all {
  border-width: 1px;
}

table.frame-ends {
  border-width: 1px 0;
}

table.frame-sides {
  border-width: 0 1px;
}

table.frame-none > colgroup + * > :first-child > *,
table.frame-sides > colgroup + * > :first-child > * {
  border-top-width: 0;
}

table.frame-none > :last-child > :last-child > *,
table.frame-sides > :last-child > :last-child > * {
  border-bottom-width: 0;
}

table.frame-none > * > tr > :first-child,
table.frame-ends > * > tr > :first-child {
  border-left-width: 0;
}

table.frame-none > * > tr > :last-child,
table.frame-ends > * > tr > :last-child {
  border-right-width: 0;
}

table.stripes-all > * > tr,
table.stripes-odd > * > tr:nth-of-type(odd),
table.stripes-even > * > tr:nth-of-type(even),
table.stripes-hover > * > tr:hover {
  background: #f8f8f7;
}

th.halign-left,
td.halign-left {
  text-align: left;
}

th.halign-right,
td.halign-right {
  text-align: right;
}

th.halign-center,
td.halign-center {
  text-align: center;
}

th.valign-top,
td.valign-top {
  vertical-align: top;
}

th.valign-bottom,
td.valign-bottom {
  vertical-align: bottom;
}

th.valign-middle,
td.valign-middle {
  vertical-align: middle;
}

table thead th,
table tfoot th {
  font-weight: bold;
}

tbody tr th {
  background: #f7f8f7;
}

tbody tr th,
tbody tr th p,
tfoot tr th,
tfoot tr th p {
  color: rgba(0, 0, 0, 0.8);
  font-weight: bold;
}

p.tableblock > code:only-child {
  background: none;
  padding: 0;
}

p.tableblock {
  font-size: 1em;
}

ol {
  margin-left: 1.75em;
}

ul li ol {
  margin-left: 1.5em;
}

dl dd {
  margin-left: 1.125em;
}

dl dd:last-child,
dl dd:last-child > :last-child {
  margin-bottom: 0;
}

li p,
ul dd,
ol dd,
.olist .olist,
.ulist .ulist,
.ulist .olist,
.olist .ulist {
  margin-bottom: 0.625em;
}

ul.checklist,
ul.none,
ol.none,
ul.no-bullet,
ol.no-bullet,
ol.unnumbered,
ul.unstyled,
ol.unstyled {
  list-style-type: none;
}

ul.no-bullet,
ol.no-bullet,
ol.unnumbered {
  margin-left: 0.625em;
}

ul.unstyled,
ol.unstyled {
  margin-left: 0;
}

li > p:empty:only-child::before {
  content: "";
  display: inline-block;
}

ul.checklist > li > p:first-child {
  margin-left: -1em;
}

ul.checklist > li > p:first-child > .fa-square-o:first-child,
ul.checklist > li > p:first-child > .fa-check-square-o:first-child {
  width: 1.25em;
  font-size: 0.8em;
  position: relative;
  bottom: 0.125em;
}

ul.checklist > li > p:first-child > input[type=checkbox]:first-child {
  margin-right: 0.25em;
}

ul.inline {
  display: flex;
  flex-flow: row wrap;
  list-style: none;
  margin: 0 0 0.625em -1.25em;
}

ul.inline > li {
  margin-left: 1.25em;
}

.unstyled dl dt {
  font-weight: 400;
  font-style: normal;
}

ol.arabic {
  list-style-type: decimal;
}

ol.decimal {
  list-style-type: decimal-leading-zero;
}

ol.loweralpha {
  list-style-type: lower-alpha;
}

ol.upperalpha {
  list-style-type: upper-alpha;
}

ol.lowerroman {
  list-style-type: lower-roman;
}

ol.upperroman {
  list-style-type: upper-roman;
}

ol.lowergreek {
  list-style-type: lower-greek;
}

.hdlist > table,
.colist > table {
  border: 0;
  background: none;
}

.hdlist > table > tbody > tr,
.colist > table > tbody > tr {
  background: none;
}

td.hdlist1,
td.hdlist2 {
  vertical-align: top;
  padding: 0 0.625em;
}

td.hdlist1 {
  font-weight: bold;
  padding-bottom: 1.25em;
}

td.hdlist2 {
  word-wrap: anywhere;
}

.literalblock + .colist,
.listingblock + .colist {
  margin-top: -0.5em;
}

.colist td:not([class]):first-child {
  padding: 0.4em 0.75em 0;
  line-height: 1;
  vertical-align: top;
}

.colist td:not([class]):first-child img {
  max-width: none;
}

.colist td:not([class]):last-child {
  padding: 0.25em 0;
}

.thumb,
.th {
  line-height: 0;
  display: inline-block;
  border: 4px solid #fff;
  box-shadow: 0 0 0 1px #ddd;
}

.imageblock.left {
  margin: 0.25em 0.625em 1.25em 0;
}

.imageblock.right {
  margin: 0.25em 0 1.25em 0.625em;
}

.imageblock > .title {
  margin-bottom: 0;
}

.imageblock.thumb,
.imageblock.th {
  border-width: 6px;
}

.imageblock.thumb > .title,
.imageblock.th > .title {
  padding: 0 0.125em;
}

.image.left,
.image.right {
  margin-top: 0.25em;
  margin-bottom: 0.25em;
  display: inline-block;
  line-height: 0;
}

.image.left {
  margin-right: 0.625em;
}

.image.right {
  margin-left: 0.625em;
}

a.image {
  text-decoration: none;
  display: inline-block;
}

a.image object {
  pointer-events: none;
}

sup.footnote,
sup.footnoteref {
  font-size: 0.875em;
  position: static;
  vertical-align: super;
}

sup.footnote a,
sup.footnoteref a {
  text-decoration: none;
}

sup.footnote a:active,
sup.footnoteref a:active {
  text-decoration: underline;
}

#footnotes {
  padding-top: 0.75em;
  padding-bottom: 0.75em;
  margin-bottom: 0.625em;
}

#footnotes hr {
  width: 20%;
  min-width: 6.25em;
  margin: -0.25em 0 0.75em;
  border-width: 1px 0 0;
}

#footnotes .footnote {
  padding: 0 0.375em 0 0.225em;
  line-height: 1.3334;
  font-size: 0.875em;
  margin-left: 1.2em;
  margin-bottom: 0.2em;
}

#footnotes .footnote a:first-of-type {
  font-weight: bold;
  text-decoration: none;
  margin-left: -1.05em;
}

#footnotes .footnote:last-of-type {
  margin-bottom: 0;
}

#content #footnotes {
  margin-top: -0.625em;
  margin-bottom: 0;
  padding: 0.75em 0;
}

div.unbreakable {
  page-break-inside: avoid;
}

.big {
  font-size: larger;
}

.small {
  font-size: smaller;
}

.underline {
  text-decoration: underline;
}

.overline {
  text-decoration: overline;
}

.line-through {
  text-decoration: line-through;
}

.aqua {
  color: #00bfbf;
}

.aqua-background {
  background: #00fafa;
}

.black {
  color: #000;
}

.black-background {
  background: #000;
}

.blue {
  color: #0000bf;
}

.blue-background {
  background: #0000fa;
}

.fuchsia {
  color: #bf00bf;
}

.fuchsia-background {
  background: #fa00fa;
}

.gray {
  color: #606060;
}

.gray-background {
  background: #7d7d7d;
}

.green {
  color: #006000;
}

.green-background {
  background: #007d00;
}

.lime {
  color: #00bf00;
}

.lime-background {
  background: #00fa00;
}

.maroon {
  color: #600000;
}

.maroon-background {
  background: #7d0000;
}

.navy {
  color: #000060;
}

.navy-background {
  background: #00007d;
}

.olive {
  color: #606000;
}

.olive-background {
  background: #7d7d00;
}

.purple {
  color: #600060;
}

.purple-background {
  background: #7d007d;
}

.red {
  color: #bf0000;
}

.red-background {
  background: #fa0000;
}

.silver {
  color: #909090;
}

.silver-background {
  background: #bcbcbc;
}

.teal {
  color: #006060;
}

.teal-background {
  background: #007d7d;
}

.white {
  color: #bfbfbf;
}

.white-background {
  background: #fafafa;
}

.yellow {
  color: #bfbf00;
}

.yellow-background {
  background: #fafa00;
}

span.icon > .fa {
  cursor: default;
}

a span.icon > .fa {
  cursor: inherit;
}

.admonitionblock td.icon [class^="fa icon-"] {
  font-size: 2.5em;
  text-shadow: 1px 1px 2px rgba(0, 0, 0, 0.5);
  cursor: default;
}

.admonitionblock td.icon .icon-note::before {
  content: "\f05a";
  color: #19407c;
}

.admonitionblock td.icon .icon-tip::before {
  content: "\f0eb";
  text-shadow: 1px 1px 2px rgba(155, 155, 0, 0.8);
  color: #111;
}

.admonitionblock td.icon .icon-warning::before {
  content: "\f071";
  color: #bf6900;
}

.admonitionblock td.icon .icon-caution::before {
  content: "\f06d";
  color: #bf3400;
}

.admonitionblock td.icon .icon-important::before {
  content: "\f06a";
  color: #bf0000;
}

.conum[data-value] {
  display: inline-block;
  color: #fff !important;
  background: rgba(0, 0, 0, 0.8);
  border-radius: 50%;
  text-align: center;
  font-size: 0.75em;
  width: 1.67em;
  height: 1.67em;
  line-height: 1.67em;
  font-family: "Open Sans", "DejaVu Sans", sans-serif;
  font-style: normal;
  font-weight: bold;
}

.conum[data-value] * {
  color: #fff !important;
}

.conum[data-value] + b {
  display: none;
}

.conum[data-value]::after {
  content: attr(data-value);
}

pre .conum[data-value] {
  position: relative;
  top: -0.125em;
}

b.conum * {
  color: inherit !important;
}

.conum:not([data-value]):empty {
  display: none;
}

dt,
th.tableblock,
td.content,
div.footnote {
  text-rendering: optimizeLegibility;
}

h1,
h2,
p,
td.content,
span.alt,
summary {
  letter-spacing: -0.01em;
}

p strong,
td.content strong,
div.footnote strong {
  letter-spacing: -0.005em;
}

p,
blockquote,
dt,
td.content,
td.hdlist1,
span.alt,
summary {
  font-size: 1.0625rem;
}

p {
  margin-bottom: 1.25rem;
}

.sidebarblock p,
.sidebarblock dt,
.sidebarblock td.content,
p.tableblock {
  font-size: 1em;
}

.exampleblock > .content {
  background: #fffef7;
  border-color: #e0e0dc;
  box-shadow: 0 1px 4px #e0e0dc;
}

.print-only {
  display: none !important;
}

@page {
  margin: 1.25cm 0.75cm;
}

@media print {
  * {
    box-shadow: none !important;
    text-shadow: none !important;
  }

  html {
    font-size: 80%;
  }

  a {
    color: inherit !important;
    text-decoration: underline !important;
  }

  a.bare,
  a[href^="#"],
  a[href^="mailto:"] {
    text-decoration: none !important;
  }

  a[href^="http:"]:not(.bare)::after,
  a[href^="https:"]:not(.bare)::after {
    content: "(" attr(href) ")";
    display: inline-block;
    font-size: 0.875em;
    padding-left: 0.25em;
  }

  abbr[title] {
    border-bottom: 1px dotted;
  }

  abbr[title]::after {
    content: " (" attr(title) ")";
  }

  pre,
  blockquote,
  tr,
  img,
  object,
  svg {
    page-break-inside: avoid;
  }

  thead {
    display: table-header-group;
  }

  svg {
    max-width: 100%;
  }

  p,
  blockquote,
  dt,
  td.content {
    font-size: 1em;
    orphans: 3;
    widows: 3;
  }

  h2,
  h3,
  #toctitle,
  .sidebarblock > .content > .title {
    page-break-after: avoid;
  }

  #header,
  #content,
  #footnotes,
  #footer {
    max-width: none;
  }

  #toc,
  .sidebarblock,
  .exampleblock > .content {
    background: none !important;
  }

  #toc {
    border-bottom: 1px solid #dddddf !important;
    padding-bottom: 0 !important;
  }

  body.book #header {
    text-align: center;
  }

  body.book #header > h1:first-child {
    border: 0 !important;
    margin: 2.5em 0 1em;
  }

  body.book #header .details {
    border: 0 !important;
    display: block;
    padding: 0 !important;
  }

  body.book #header .details span:first-child {
    margin-left: 0 !important;
  }

  body.book #header .details br {
    display: block;
  }

  body.book #header .details br + span::before {
    content: none !important;
  }

  body.book #toc {
    border: 0 !important;
    text-align: left !important;
    padding: 0 !important;
    margin: 0 !important;
  }

  body.book #toc,
  body.book #preamble,
  body.book h1.sect0,
  body.book .sect1 > h2 {
    page-break-before: always;
  }

  .listingblock code[data-lang]::before {
    display: block;
  }

  #footer {
    padding: 0 0.9375em;
  }

  .hide-on-print {
    display: none !important;
  }

  .print-only {
    display: block !important;
  }

  .hide-for-print {
    display: none !important;
  }

  .show-for-print {
    display: inherit !important;
  }
}

@media amzn-kf8, print {
  #header > h1:first-child {
    margin-top: 1.25rem;
  }

  .sect1 {
    padding: 0 !important;
  }

  .sect1 + .sect1 {
    border: 0;
  }

  #footer {
    background: none;
  }

  #footer-text {
    color: rgba(0, 0, 0, 0.6);
    font-size: 0.9em;
  }
}

@media amzn-kf8 {
  #header,
  #content,
  #footnotes,
  #footer {
    padding: 0;
  }
}

</style>
<style>
pre.rouge table td { padding: 5px; }
pre.rouge table pre { margin: 0; }
pre.rouge, pre.rouge .w {
  color: #24292f;
  background-color: #f6f8fa;
}
pre.rouge .k, pre.rouge .kd, pre.rouge .kn, pre.rouge .kp, pre.rouge .kr, pre.rouge .kt, pre.rouge .kv {
  color: #cf222e;
}
pre.rouge .gr {
  color: #f6f8fa;
}
pre.rouge .gd {
  color: #82071e;
  background-color: #ffebe9;
}
pre.rouge .nb {
  color: #953800;
}
pre.rouge .nc {
  color: #953800;
}
pre.rouge .no {
  color: #953800;
}
pre.rouge .nn {
  color: #953800;
}
pre.rouge .sr {
  color: #116329;
}
pre.rouge .na {
  color: #116329;
}
pre.rouge .nt {
  color: #116329;
}
pre.rouge .gi {
  color: #116329;
  background-color: #dafbe1;
}
pre.rouge .ges {
  font-weight: bold;
  font-style: italic;
}
pre.rouge .kc {
  color: #0550ae;
}
pre.rouge .l, pre.rouge .ld, pre.rouge .m, pre.rouge .mb, pre.rouge .mf, pre.rouge .mh, pre.rouge .mi, pre.rouge .il, pre.rouge .mo, pre.rouge .mx {
  color: #0550ae;
}
pre.rouge .sb {
  color: #0550ae;
}
pre.rouge .bp {
  color: #0550ae;
}
pre.rouge .ne {
  color: #0550ae;
}
pre.rouge .nl {
  color: #0550ae;
}
pre.rouge .py {
  color: #0550ae;
}
pre.rouge .nv, pre.rouge .vc, pre.rouge .vg, pre.rouge .vi, pre.rouge .vm {
  color: #0550ae;
}
pre.rouge .o, pre.rouge .ow {
  color: #0550ae;
}
pre.rouge .gh {
  color: #0550ae;
  font-weight: bold;
}
pre.rouge .gu {
  color: #0550ae;
  font-weight: bold;
}
pre.rouge .s, pre.rouge .sa, pre.rouge .sc, pre.rouge .dl, pre.rouge .sd, pre.rouge .s2, pre.rouge .se, pre.rouge .sh, pre.rouge .sx, pre.rouge .s1, pre.rouge .ss {
  color: #0a3069;
}
pre.rouge .nd {
  color: #8250df;
}
pre.rouge .nf, pre.rouge .fm {
  color: #8250df;
}
pre.rouge .err {
  color: #f6f8fa;
  background-color: #82071e;
}
pre.rouge .c, pre.rouge .ch, pre.rouge .cd, pre.rouge .cm, pre.rouge .cp, pre.rouge .cpf, pre.rouge .c1, pre.rouge .cs {
  color: #6e7781;
}
pre.rouge .gl {
  color: #6e7781;
}
pre.rouge .gt {
  color: #6e7781;
}
pre.rouge .ni {
  color: #24292f;
}
pre.rouge .si {
  color: #24292f;
}
pre.rouge .ge {
  color: #24292f;
  font-style: italic;
}
pre.rouge .gs {
  color: #24292f;
  font-weight: bold;
}
</style>
<style>
#toc img.logo {
  width: 100px;
  height: 100px;
  margin-left: auto;
  margin-right: auto;
  margin-bottom: 10px;
  display: block;
}
</style>

<script>
  document.addEventListener("DOMContentLoaded", () => {
    var image = document.createElement('img')
    image.setAttribute('src', '../etc/logo/sail_logo_square.png')
    image.setAttribute('alt', 'Sail Logo')
    image.classList.add('logo')
    var toc = document.querySelector('#toc')
    if (toc) {
      toc.insertAdjacentElement('afterbegin', image)
    }
  });
</script>
</head>
<body class="book toc2 toc-left">
<div id="header">
<h1>The Sail instruction-set semantics specification language</h1>
<div class="details">
<span id="author" class="author">Alasdair Armstrong</span><br>
<span id="author2" class="author">Thomas Bauereiss</span><br>
<span id="author3" class="author">Brian Campbell</span><br>
<span id="author4" class="author">Shaked Flur</span><br>
<span id="author5" class="author">Kathryn E. Gray</span><br>
<span id="author6" class="author">Robert Norton-Wright</span><br>
<span id="author7" class="author">Christopher Pulte</span><br>
<span id="author8" class="author">Peter Sewell</span><br>
</div>
<div id="toc" class="toc2">
<div id="toctitle">Table of Contents</div>
<ul class="sectlevel1">
<li><a href="#_introduction">Introduction</a></li>
<li><a href="#_a_tutorial_risc_v_style_example">A tutorial RISC-V style example</a></li>
<li><a href="#_usage">Usage</a>
<ul class="sectlevel2">
<li><a href="#_sail_options">Sail options</a></li>
<li><a href="#_c_compilation">C compilation</a></li>
<li><a href="#_systemverilog_compilation_experimental">SystemVerilog compilation (Experimental)</a></li>
<li><a href="#_automatic_formatting_experimental">Automatic formatting (Experimental)</a></li>
<li><a href="#_interactive_mode">Interactive mode</a></li>
<li><a href="#_other_options">Other options</a></li>
<li><a href="#_debug_options">Debug options</a></li>
</ul>
</li>
<li><a href="#_the_sail_language">The Sail Language</a>
<ul class="sectlevel2">
<li><a href="#_functions">Functions</a></li>
<li><a href="#_blocks">Blocks</a></li>
<li><a href="#_the_unit_type">The <code>unit</code> type</a></li>
<li><a href="#_numeric_types_and_bits">Numeric types and bits</a></li>
<li><a href="#_bitvector_literals">Bitvector literals</a></li>
<li><a href="#_vectors">Vectors</a></li>
<li><a href="#_accessing_and_updating_vectors">Accessing and updating vectors</a></li>
<li><a href="#_the_list_type">The <code>list</code> type</a></li>
<li><a href="#_tuples">Tuples</a></li>
<li><a href="#_strings">Strings</a></li>
<li><a href="#_user_defined_types">User-defined types</a>
<ul class="sectlevel3">
<li><a href="#_structs">Structs</a></li>
<li><a href="#_enums">Enums</a></li>
<li><a href="#_unions">Unions</a></li>
<li><a href="#_newtype"><code>newtype</code></a></li>
</ul>
</li>
<li><a href="#_type_synonyms">Type synonyms</a></li>
<li><a href="#_type_kinds">Type kinds</a></li>
<li><a href="#_abstract_types">Abstract types</a></li>
<li><a href="#_pattern_matching">Pattern matching</a>
<ul class="sectlevel3">
<li><a href="#_guards">Guards</a></li>
<li><a href="#_matching_on_literals">Matching on literals</a></li>
<li><a href="#_matching_on_enumerations">Matching on enumerations</a></li>
<li><a href="#_matching_on_tuples">Matching on tuples</a></li>
<li><a href="#_matching_on_unions">Matching on unions</a></li>
<li><a href="#_matching_on_lists">Matching on lists</a></li>
<li><a href="#_matching_on_structs">Matching on structs</a></li>
<li><a href="#_as_patterns">As patterns</a></li>
<li><a href="#_automatic_wildcard_insertion">Automatic wildcard insertion</a></li>
</ul>
</li>
<li><a href="#_matching_in_let_and_function_arguments">Matching in let and function arguments</a></li>
<li><a href="#_type_patterns">Type patterns</a></li>
<li><a href="#_mutable_variables">Mutable variables</a></li>
<li><a href="#_assignment_and_l_values">Assignment and l-values</a></li>
<li><a href="#_bitfields">Bitfields</a></li>
<li><a href="#_operators">Operators</a>
<ul class="sectlevel3">
<li><a href="#_built_in_precedences">Built-in precedences</a></li>
</ul>
</li>
<li><a href="#_ad_hoc_overloading">Ad-hoc overloading</a></li>
<li><a href="#_mappings">Mappings</a></li>
<li><a href="#_sizeof_and_constraint">Sizeof and constraint</a></li>
<li><a href="#_exceptions">Exceptions</a></li>
<li><a href="#_scattered_definitions">Scattered definitions</a></li>
<li><a href="#_preludes_and_default_environment">Preludes and default environment</a></li>
</ul>
</li>
<li><a href="#_model_configuration">Model Configuration</a>
<ul class="sectlevel2">
<li><a href="#_json_representation_of_sail_types">JSON representation of Sail types</a></li>
<li><a href="#_runtime_configuration_with_sail_to_c">Runtime Configuration with Sail to C</a></li>
<li><a href="#_configurable_abstract_types">Configurable abstract types</a></li>
<li><a href="#_validating_configurations_with_json_schema">Validating Configurations with JSON Schema</a></li>
</ul>
</li>
<li><a href="#_modular_sail_specifications">Modular Sail Specifications</a>
<ul class="sectlevel2">
<li><a href="#_modules">Modules</a></li>
<li><a href="#_working_with_makefiles">Working with Makefiles</a></li>
<li><a href="#_conditional_compilation_within_modules">Conditional compilation within modules</a></li>
<li><a href="#_optional_and_default_modules">Optional and default modules</a></li>
</ul>
</li>
<li><a href="#_the_sail_grammar">The Sail Grammar</a></li>
<li><a href="#_references">References</a></li>
</ul>
</div>
</div>
<div id="content">
<div class="sect1">
<h2 id="_introduction">Introduction</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Sail is a language for expressing the instruction-set
architecture (ISA) semantics of processors.</p>
</div>
<div class="paragraph">
<p>Vendor architecture specification documents typically describe the
sequential behaviour of their ISA with a combination of prose, tables,
and pseudocode for each instruction.</p>
</div>
<div class="paragraph">
<p>They vary in how precise that pseudocode is: in some it is just
suggestive, while in others it is close to a complete description of
the envelope of architecturally allowed behaviour for sequential code.</p>
</div>
<div class="paragraph">
<p>For x86 <span class="citation">[<a href="#Intel61">1</a>]</span>, the Intel pseudocode is just suggestive,
with embedded prose, while the AMD descriptions <span class="citation">[<a href="#AMD_3_21">2</a>]</span>
are prose alone. For IBM Power <span class="citation">[<a href="#Power3.0B">3</a>]</span>, there is
detailed pseudocode which has recently become
machine-processed <span class="citation">[<a href="#Leighton21">4</a>]</span>. For
Arm <span class="citation">[<a href="#armarmv8">5</a>]</span>, there is detailed pseudocode, which has
recently become machine-processed <span class="citation">[<a href="#Reid16">6</a>]</span>. For
MIPS <span class="citation">[<a href="#MIPS64-II">7</a>, <a href="#MIPS64-III">8</a>]</span> there is also reasonably detailed
pseudocode.</p>
</div>
<div class="paragraph">
<p>Sail is intended:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>To support precise definition of real-world ISA semantics;</p>
</li>
<li>
<p>To be accessible to engineers familiar with existing vendor
pseudocodes, with a similar style to the pseudocodes used by ARM and
IBM Power (modulo minor syntactic differences);</p>
</li>
<li>
<p>To expose the structure needed to combine the sequential ISA
semantics with the relaxed-memory concurrency models we have
developed;</p>
</li>
<li>
<p>To provide an expressive type system that can statically check the
bitvector length and indexing computation that arises in these
specifications, to detect errors and to support code generation,
with type inference to minimise the required type annotations;</p>
</li>
<li>
<p>To support execution, for architecturally complete emulation
automatically based on the definition;</p>
</li>
<li>
<p>To support automatic generation of theorem-prover definitions, for
mechanised reasoning about ISA specifications; and</p>
</li>
<li>
<p>To be as minimal as possible given the above, to ease the tasks of
code generation and theorem-prover definition generation.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>A Sail specification will typically define an abstract syntax type/tre
(AST) of machine instructions, a decode function that takes binary
values to AST values, and an execute function that describes how each
of those behaves at runtime, together with whatever auxiliary
functions and types are needed.</p>
</div>
<div class="paragraph">
<p>Given such a specification, the Sail implementation can typecheck it
and generate:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>An internal representation of the fully type-annotated
definition (a deep embedding of the definition) in a form that can
be executed by the Sail interpreter.  These are both expressed in
Lem <span class="citation">[<a href="#Lem-icfp2014">9</a>, <a href="#Lemcode">10</a>]</span>, a language of type, function, and
relation definitions that can be compiled into OCaml and various
theorem provers. The Sail interpreter can also be used to analyse
instruction definitions (or partially executed instructions) to
determine their potential register and memory footprints.</p>
</li>
<li>
<p>A shallow embedding of the definition, also in Lem, that can be
executed or converted to theorem-prover code more directly.
Currently this is aimed at Isabelle/HOL or HOL4, though the Sail
dependent types should support generation of idiomatic Coq definitions
(directly rather than via Lem).</p>
</li>
<li>
<p>A compiled version of the specification
directly into OCaml.</p>
</li>
<li>
<p>A more efficient executable version of the specification, compiled
into C code.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>Sail has been used to develop models of parts of several architectures:</p>
</div>
<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 33.3333%;">
<col style="width: 33.3333%;">
<col style="width: 33.3334%;">
</colgroup>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Arm-v8 (ASL)</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">generated from Arm&#8217;s v8.5 public ASL spec</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://github.com/rems-project/sail-arm/tree/master/arm-v8.5-a" class="bare">github.com/rems-project/sail-arm/tree/master/arm-v8.5-a</a></p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Arm-v9 (ASL)</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">generated from Arm&#8217;s v9.3 public ASL spec</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://github.com/rems-project/sail-arm/tree/master/arm-v9.3-a" class="bare">github.com/rems-project/sail-arm/tree/master/arm-v9.3-a</a></p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">RISC-V</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">hand-written</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://github.com/riscv/sail-riscv" class="bare">github.com/riscv/sail-riscv</a></p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">CHERI-MIPS</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">hand-written</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://github.com/CTSRD-CHERI/sail-cheri-mips" class="bare">github.com/CTSRD-CHERI/sail-cheri-mips</a></p></td>
</tr>
</tbody>
</table>
<div class="paragraph">
<p>The Arm-v8 (ASL) model is based on an automatic translation of Arm&#8217;s
machine-readable public v8.3 ASL specification <sup class="footnote">[<a id="_footnoteref_1" class="footnote" href="#_footnotedef_1" title="View footnote.">1</a>]</sup>. It includes everything in
ARM&#8217;s specification.</p>
</div>
<div class="paragraph">
<p>The MIPS model is hand-written based on the MIPS64 manual version
2.5 <span class="citation">[<a href="#MIPS64-II">7</a>, <a href="#MIPS64-III">8</a>]</span>,
but covering only the features in the BERI hardware
reference <span class="citation">[<a href="#UCAM-CL-TR-868">11</a>]</span>,
which in turn drew on MIPS4000 and MIPS32 <span class="citation">[<a href="#MIPS4000">12</a>, <a href="#MIPS32-I">13</a>]</span>.</p>
</div>
<div class="paragraph">
<p>The CHERI model is based on that and the CHERI ISA reference manual
version&#160;5 <span class="citation">[<a href="#UCAM-CL-TR-891">14</a>]</span>. These two are both
principally by Norton-Wright; they cover all basic user
and kernel mode MIPS features sufficient to boot FreeBSD, including a
TLB, exceptions and a basic UART for console interaction. ISA
extensions such as floating point are not covered. The CHERI model
supports either 256-bit capabilities or 128-bit compressed
capabilities.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_a_tutorial_risc_v_style_example">A tutorial RISC-V style example</h2>
<div class="sectionbody">
<div class="paragraph">
<p>We introduce the basic features of Sail via a small example from our
RISC-V model that includes just two instructions: add immediate and
load double. We start by defining the default order (see <a href="#_vectors">Vectors</a>
for details), and including the Sail prelude:</p>
</div>
<div id="riscv-code-span-PREAMBLE" class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="k">default</span><span class="w"> </span><span class="kt">Order</span><span class="w"> </span><span class="kt">dec</span><span class="w">
</span><span class="cp">$include &lt;prelude.sail&gt;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>The Sail prelude is very minimal, and it is expected that Sail
specifications will usually build upon it. Some Sail specifications
are derived from pre-existing pseudocode, which already use specific
idioms&#8201;&#8212;&#8201;our Sail Arm specification uses <code>ZeroExtend</code> and
<code>SignExtend</code> mirroring the ASL code, whereas our MIPS and RISC-V
specification use <code>EXTZ</code> and <code>EXTS</code> for the same functions. Therefore for
this example we define zero-extension and sign-extension functions as:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="k">val</span><span class="w"> </span><span class="nf">EXTZ</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="k">forall</span><span class="w"> </span><span class="nv">'n</span><span class="w"> </span><span class="nv">'m</span><span class="p">,</span><span class="w"> </span><span class="nv">'m</span><span class="w"> </span><span class="o">&gt;=</span><span class="w"> </span><span class="nv">'n</span><span class="o">.</span><span class="w"> </span><span class="p">(</span><span class="kt">implicit</span><span class="p">(</span><span class="nv">'m</span><span class="p">),</span><span class="w"> </span><span class="kt">bits</span><span class="p">(</span><span class="nv">'n</span><span class="p">))</span><span class="w"> </span><span class="p">-&gt;</span><span class="w"> </span><span class="kt">bits</span><span class="p">(</span><span class="nv">'m</span><span class="p">)</span><span class="w">
</span><span class="k">function</span><span class="w"> </span><span class="nf">EXTZ</span><span class="p">(</span><span class="n">m</span><span class="p">,</span><span class="w"> </span><span class="n">v</span><span class="p">)</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">sail_zero_extend</span><span class="p">(</span><span class="n">v</span><span class="p">,</span><span class="w"> </span><span class="n">m</span><span class="p">)</span><span class="w">

</span><span class="k">val</span><span class="w"> </span><span class="nf">EXTS</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="k">forall</span><span class="w"> </span><span class="nv">'n</span><span class="w"> </span><span class="nv">'m</span><span class="p">,</span><span class="w"> </span><span class="nv">'m</span><span class="w"> </span><span class="o">&gt;=</span><span class="w"> </span><span class="nv">'n</span><span class="o">.</span><span class="w"> </span><span class="p">(</span><span class="kt">implicit</span><span class="p">(</span><span class="nv">'m</span><span class="p">),</span><span class="w"> </span><span class="kt">bits</span><span class="p">(</span><span class="nv">'n</span><span class="p">))</span><span class="w"> </span><span class="p">-&gt;</span><span class="w"> </span><span class="kt">bits</span><span class="p">(</span><span class="nv">'m</span><span class="p">)</span><span class="w">
</span><span class="k">function</span><span class="w"> </span><span class="nf">EXTS</span><span class="p">(</span><span class="n">m</span><span class="p">,</span><span class="w"> </span><span class="n">v</span><span class="p">)</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">sail_sign_extend</span><span class="p">(</span><span class="n">v</span><span class="p">,</span><span class="w"> </span><span class="n">m</span><span class="p">)</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>We now define an integer type synonym <code>xlen</code>, which for this example
will be equal to 64. Sail supports definitions which are generic over
both regular types, and integers (think const generics in C++, but
more expressive). We also create a type <code>xlenbits</code> for bitvectors of
length <code>xlen</code>.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="k">type</span><span class="w"> </span><span class="n">xlen</span><span class="w">       </span><span class="p">:</span><span class="w"> </span><span class="kt">Int</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="mi">64</span><span class="w">
</span><span class="k">type</span><span class="w"> </span><span class="n">xlen_bytes</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="kt">Int</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="mi">8</span><span class="w">
</span><span class="k">type</span><span class="w"> </span><span class="n">xlenbits</span><span class="w">         </span><span class="p">=</span><span class="w"> </span><span class="kt">bits</span><span class="p">(</span><span class="n">xlen</span><span class="p">)</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>For the purpose of this example, we also introduce a type synonym for
bitvectors of length 5, which represent registers.</p>
</div>
<div id="riscv-code-type-regbits" class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="k">type</span><span class="w"> </span><span class="n">regbits</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="kt">bits</span><span class="p">(</span><span class="mi">5</span><span class="p">)</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>We now set up some basic architectural state. First creating a
register of type <code>xlenbits</code> for both the program counter <code>PC</code>, and
the next program counter, <code>nextPC</code>. We define the general purpose
registers as a vector of 32 <code>xlenbits</code> bitvectors. The <code>dec</code>
keyword isn&#8217;t important in this example, but Sail supports two
different numbering schemes for (bit)vectors <code>inc</code>, for most
significant bit is zero, and <code>dec</code> for least significant bit is
zero. We then define a getter and setter for the registers, which
ensure that the zero register is treated specially (in
RISC-V register 0 is always hardcoded to be 0). Finally we overload
both the read (<code>rX</code>) and write (<code>wX</code>) functions as simply
<code>X</code>. This allows us to write registers as <code>X(r) = value</code> and
read registers as <code>value = X(r)</code>. Sail supports flexible ad-hoc
overloading, and has an expressive l-value language in assignments,
with the aim of allowing pseudo-code like definitions.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="w">
</span><span class="k">register</span><span class="w"> </span><span class="n">PC</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="n">xlenbits</span><span class="w">
</span><span class="k">register</span><span class="w"> </span><span class="n">nextPC</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="n">xlenbits</span><span class="w">

</span><span class="k">register</span><span class="w"> </span><span class="n">Xs</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="n">vector</span><span class="p">(</span><span class="mi">32</span><span class="p">,</span><span class="w"> </span><span class="kt">dec</span><span class="p">,</span><span class="w"> </span><span class="n">xlenbits</span><span class="p">)</span><span class="w">

</span><span class="k">val</span><span class="w"> </span><span class="nf">rX</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="n">regbits</span><span class="w"> </span><span class="p">-&gt;</span><span class="w"> </span><span class="n">xlenbits</span><span class="w">
</span><span class="k">function</span><span class="w"> </span><span class="nf">rX</span><span class="p">(</span><span class="n">r</span><span class="p">)</span><span class="w"> </span><span class="p">=</span><span class="w">
  </span><span class="k">match</span><span class="w"> </span><span class="n">r</span><span class="w"> </span><span class="p">{</span><span class="w">
    </span><span class="mb">0b00000</span><span class="w"> </span><span class="p">=</span><span class="o">&gt;</span><span class="w"> </span><span class="n">EXTZ</span><span class="p">(</span><span class="mh">0x0</span><span class="p">),</span><span class="w">
    </span><span class="mi">_</span><span class="w"> </span><span class="p">=</span><span class="o">&gt;</span><span class="w"> </span><span class="n">Xs</span><span class="p">[</span><span class="n">unsigned</span><span class="p">(</span><span class="n">r</span><span class="p">)]</span><span class="w">
  </span><span class="p">}</span><span class="w">

</span><span class="k">val</span><span class="w"> </span><span class="nf">wX</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="p">(</span><span class="n">regbits</span><span class="p">,</span><span class="w"> </span><span class="n">xlenbits</span><span class="p">)</span><span class="w"> </span><span class="p">-&gt;</span><span class="w"> </span><span class="kt">unit</span><span class="w">
</span><span class="k">function</span><span class="w"> </span><span class="nf">wX</span><span class="p">(</span><span class="n">r</span><span class="p">,</span><span class="w"> </span><span class="n">v</span><span class="p">)</span><span class="w"> </span><span class="p">=</span><span class="w">
  </span><span class="k">if</span><span class="w"> </span><span class="n">r</span><span class="w"> </span><span class="o">!=</span><span class="w"> </span><span class="mb">0b00000</span><span class="w"> </span><span class="k">then</span><span class="w"> </span><span class="p">{</span><span class="w">
     </span><span class="n">Xs</span><span class="p">[</span><span class="n">unsigned</span><span class="p">(</span><span class="n">r</span><span class="p">)]</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">v</span><span class="p">;</span><span class="w">
  </span><span class="p">}</span><span class="w">

</span><span class="k">overload</span><span class="w"> </span><span class="n">X</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">{</span><span class="n">rX</span><span class="p">,</span><span class="w"> </span><span class="n">wX</span><span class="p">}</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>We also give a function <code>MEMr</code> for reading memory, this function just
points at a builtin we have defined elsewhere.  The builtin is very
general (it allows addresses of multiple bitwidths), so we also derive
a simpler <code>read_mem</code> function.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="k">val</span><span class="w"> </span><span class="nf">MEMr</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">impure</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="n">lem</span><span class="p">:</span><span class="w"> </span><span class="s">"MEMr"</span><span class="p">,</span><span class="w"> </span><span class="n">coq</span><span class="p">:</span><span class="w"> </span><span class="s">"MEMr"</span><span class="p">,</span><span class="w"> </span><span class="mi">_</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="s">"read_ram"</span><span class="w"> </span><span class="p">}</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="k">forall</span><span class="w"> </span><span class="nv">'n</span><span class="w"> </span><span class="nv">'m</span><span class="p">,</span><span class="w"> </span><span class="nv">'n</span><span class="w"> </span><span class="o">&gt;=</span><span class="w"> </span><span class="mi">0</span><span class="o">.</span><span class="w">
   </span><span class="p">(</span><span class="kt">int</span><span class="p">(</span><span class="nv">'m</span><span class="p">),</span><span class="w"> </span><span class="kt">int</span><span class="p">(</span><span class="nv">'n</span><span class="p">),</span><span class="w"> </span><span class="kt">bits</span><span class="p">(</span><span class="nv">'m</span><span class="p">),</span><span class="w"> </span><span class="kt">bits</span><span class="p">(</span><span class="nv">'m</span><span class="p">))</span><span class="w"> </span><span class="p">-&gt;</span><span class="w"> </span><span class="kt">bits</span><span class="p">(</span><span class="mi">8</span><span class="w"> </span><span class="o">*</span><span class="w"> </span><span class="nv">'n</span><span class="p">)</span><span class="w">

</span><span class="k">val</span><span class="w"> </span><span class="nf">read_mem</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="k">forall</span><span class="w"> </span><span class="nv">'n</span><span class="p">,</span><span class="w"> </span><span class="nv">'n</span><span class="w"> </span><span class="o">&gt;=</span><span class="w"> </span><span class="mi">0</span><span class="o">.</span><span class="w"> </span><span class="p">(</span><span class="n">xlenbits</span><span class="p">,</span><span class="w"> </span><span class="kt">int</span><span class="p">(</span><span class="nv">'n</span><span class="p">))</span><span class="w"> </span><span class="p">-&gt;</span><span class="w"> </span><span class="kt">bits</span><span class="p">(</span><span class="mi">8</span><span class="w"> </span><span class="o">*</span><span class="w"> </span><span class="nv">'n</span><span class="p">)</span><span class="w">
</span><span class="k">function</span><span class="w"> </span><span class="nf">read_mem</span><span class="p">(</span><span class="n">addr</span><span class="p">,</span><span class="w"> </span><span class="n">width</span><span class="p">)</span><span class="w"> </span><span class="p">=</span><span class="w">
    </span><span class="n">MEMr</span><span class="p">(</span><span class="nb">sizeof</span><span class="p">(</span><span class="n">xlen</span><span class="p">),</span><span class="w"> </span><span class="n">width</span><span class="p">,</span><span class="w"> </span><span class="n">EXTZ</span><span class="p">(</span><span class="mh">0x0</span><span class="p">),</span><span class="w"> </span><span class="n">addr</span><span class="p">)</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>It&#8217;s common when defining architecture specifications to break
instruction semantics down into separate functions that handle
decoding (possibly even in several stages) into custom intermediate
datatypes and executing the decoded instructions. However it&#8217;s often
desirable to group the relevant parts of these functions and datatypes
together in one place, as they would usually be found in an
architecture reference manual. To support this Sail supports
<em>scattered</em> definitions. First we give types for the execute and
decode functions, as well as the <code>ast</code> union.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="k">enum</span><span class="w"> </span><span class="n">iop</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">{</span><span class="n">RISCV_ADDI</span><span class="p">,</span><span class="w"> </span><span class="n">RISCV_SLTI</span><span class="p">,</span><span class="w"> </span><span class="n">RISCV_SLTIU</span><span class="p">,</span><span class="w"> </span><span class="n">RISCV_XORI</span><span class="p">,</span><span class="w"> </span><span class="n">RISCV_ORI</span><span class="p">,</span><span class="w"> </span><span class="n">RISCV_ANDI</span><span class="p">}</span><span class="w">

</span><span class="k">scattered</span><span class="w"> </span><span class="k">union</span><span class="w"> </span><span class="n">ast</span><span class="w">

</span><span class="k">val</span><span class="w"> </span><span class="nf">decode</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="kt">bits</span><span class="p">(</span><span class="mi">32</span><span class="p">)</span><span class="w"> </span><span class="p">-&gt;</span><span class="w"> </span><span class="kt">option</span><span class="p">(</span><span class="n">ast</span><span class="p">)</span><span class="w">
</span><span class="k">val</span><span class="w"> </span><span class="nf">execute</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="n">ast</span><span class="w"> </span><span class="p">-&gt;</span><span class="w"> </span><span class="kt">unit</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>Now we provide the clauses for the add-immediate <code>ast</code> type, as well
as its execute and decode clauses. We can define the decode function
by directly pattern matching on the bitvector representing the
instruction. Sail supports vector concatenation patterns (<code>@</code> is the
vector concatenation operator), and uses the types provided
(e.g. <code>bits(12)</code> and <code>regbits</code>) to destructure the vector in the
correct way. We use the <code>EXTS</code> function that sign-extends its
argument.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="k">union</span><span class="w"> </span><span class="k">clause</span><span class="w"> </span><span class="n">ast</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">ITYPE</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="p">(</span><span class="kt">bits</span><span class="p">(</span><span class="mi">12</span><span class="p">),</span><span class="w"> </span><span class="n">regbits</span><span class="p">,</span><span class="w"> </span><span class="n">regbits</span><span class="p">,</span><span class="w"> </span><span class="n">iop</span><span class="p">)</span><span class="w">

</span><span class="k">function</span><span class="w"> </span><span class="nf">clause</span><span class="w"> </span><span class="n">decode</span><span class="w"> </span><span class="n">imm</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="kt">bits</span><span class="p">(</span><span class="mi">12</span><span class="p">)</span><span class="w"> </span><span class="p">@</span><span class="w"> </span><span class="n">rs1</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="n">regbits</span><span class="w"> </span><span class="p">@</span><span class="w"> </span><span class="mb">0b000</span><span class="w"> </span><span class="p">@</span><span class="w"> </span><span class="n">rd</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="n">regbits</span><span class="w"> </span><span class="p">@</span><span class="w"> </span><span class="mb">0b0010011</span><span class="w">
  </span><span class="p">=</span><span class="w"> </span><span class="n">Some</span><span class="p">(</span><span class="n">ITYPE</span><span class="p">(</span><span class="n">imm</span><span class="p">,</span><span class="w"> </span><span class="n">rs1</span><span class="p">,</span><span class="w"> </span><span class="n">rd</span><span class="p">,</span><span class="w"> </span><span class="n">RISCV_ADDI</span><span class="p">))</span><span class="w">

</span><span class="k">function</span><span class="w"> </span><span class="nf">clause</span><span class="w"> </span><span class="n">execute</span><span class="w"> </span><span class="p">(</span><span class="n">ITYPE</span><span class="w"> </span><span class="p">(</span><span class="n">imm</span><span class="p">,</span><span class="w"> </span><span class="n">rs1</span><span class="p">,</span><span class="w"> </span><span class="n">rd</span><span class="p">,</span><span class="w"> </span><span class="n">RISCV_ADDI</span><span class="p">))</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">{</span><span class="w">
  </span><span class="k">let</span><span class="w"> </span><span class="n">rs1_val</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">X</span><span class="p">(</span><span class="n">rs1</span><span class="p">);</span><span class="w">
  </span><span class="k">let</span><span class="w"> </span><span class="n">imm_ext</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="n">xlenbits</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">EXTS</span><span class="p">(</span><span class="n">imm</span><span class="p">);</span><span class="w">
  </span><span class="k">let</span><span class="w"> </span><span class="n">result</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">rs1_val</span><span class="w"> </span><span class="o">+</span><span class="w"> </span><span class="n">imm_ext</span><span class="p">;</span><span class="w">
  </span><span class="n">X</span><span class="p">(</span><span class="n">rd</span><span class="p">)</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">result</span><span class="w">
</span><span class="p">}</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>Now we do the same thing for the load-double instruction:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="k">union</span><span class="w"> </span><span class="k">clause</span><span class="w"> </span><span class="n">ast</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">LOAD</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="p">(</span><span class="kt">bits</span><span class="p">(</span><span class="mi">12</span><span class="p">),</span><span class="w"> </span><span class="n">regbits</span><span class="p">,</span><span class="w"> </span><span class="n">regbits</span><span class="p">)</span><span class="w">

</span><span class="k">function</span><span class="w"> </span><span class="nf">clause</span><span class="w"> </span><span class="n">decode</span><span class="w"> </span><span class="n">imm</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="kt">bits</span><span class="p">(</span><span class="mi">12</span><span class="p">)</span><span class="w"> </span><span class="p">@</span><span class="w"> </span><span class="n">rs1</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="n">regbits</span><span class="w"> </span><span class="p">@</span><span class="w"> </span><span class="mb">0b011</span><span class="w"> </span><span class="p">@</span><span class="w"> </span><span class="n">rd</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="n">regbits</span><span class="w"> </span><span class="p">@</span><span class="w"> </span><span class="mb">0b0000011</span><span class="w">
  </span><span class="p">=</span><span class="w"> </span><span class="n">Some</span><span class="p">(</span><span class="n">LOAD</span><span class="p">(</span><span class="n">imm</span><span class="p">,</span><span class="w"> </span><span class="n">rs1</span><span class="p">,</span><span class="w"> </span><span class="n">rd</span><span class="p">))</span><span class="w">

</span><span class="k">function</span><span class="w"> </span><span class="nf">clause</span><span class="w"> </span><span class="n">execute</span><span class="p">(</span><span class="n">LOAD</span><span class="p">(</span><span class="n">imm</span><span class="p">,</span><span class="w"> </span><span class="n">rs1</span><span class="p">,</span><span class="w"> </span><span class="n">rd</span><span class="p">))</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">{</span><span class="w">
    </span><span class="k">let</span><span class="w"> </span><span class="n">addr</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="n">xlenbits</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">X</span><span class="p">(</span><span class="n">rs1</span><span class="p">)</span><span class="w"> </span><span class="o">+</span><span class="w"> </span><span class="n">EXTS</span><span class="p">(</span><span class="n">imm</span><span class="p">);</span><span class="w">
    </span><span class="k">let</span><span class="w"> </span><span class="n">result</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="n">xlenbits</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">read_mem</span><span class="p">(</span><span class="n">addr</span><span class="p">,</span><span class="w"> </span><span class="nb">sizeof</span><span class="p">(</span><span class="n">xlen_bytes</span><span class="p">));</span><span class="w">
    </span><span class="n">X</span><span class="p">(</span><span class="n">rd</span><span class="p">)</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">result</span><span class="w">
</span><span class="p">}</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>Finally we define the fallthrough case for the decode function. Note
that the clauses in a scattered function will be matched in the order
they appear in the file.</p>
</div>
<div id="riscv-code-decode" class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="k">function</span><span class="w"> </span><span class="nf">clause</span><span class="w"> </span><span class="n">decode</span><span class="w"> </span><span class="mi">_</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">None</span><span class="p">()</span></code></pre>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_usage">Usage</h2>
<div class="sectionbody">
<div class="paragraph">
<p>In its most basic use-case Sail is a command-line tool, analogous to
a compiler: one gives it a list of input Sail files; it type-checks
them and provides translated output.</p>
</div>
<div class="paragraph">
<p>To simply typecheck Sail files, one can pass them on the command line
with no other options, for example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sh">sail prelude.sail riscv_types.sail riscv_mem.sail riscv_sys.sail riscv_vmem.sail riscv.sail</code></pre>
</div>
</div>
<div class="paragraph">
<p>The sail files passed on the command line are simply treated as if
they are one large file concatenated together, although the parser
will keep track of locations on a per-file basis for
error-reporting. As can be seen, this specification is split into
several logical components. <code>prelude.sail</code> defines the initial
type environment and builtins, <code>riscv_types.sail</code> gives type
definitions used in the rest of the specification, <code>riscv_mem.sail</code>
and <code>riscv_vmem.sail</code> describe the physical and virtual memory
interaction, and then <code>riscv_sys.sail</code> and <code>riscv.sail</code>
implement most of the specification.</p>
</div>
<div class="paragraph">
<p>One can use also use <code>$include</code> directives in Sail source, for
example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="cp">$include &lt;library.sail&gt;</span><span class="w">
</span><span class="cp">$include "file.sail"</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>Here, Sail will look for <code>library.sail</code> in the <code>$SAIL_DIR/lib</code>
directory, where <code>$SAIL_DIR</code> is usually the root of the sail
repository (or <code>opam var sail:share</code> when Sail is installed using
opam). It will search for <code>file.sail</code> relative to the location of the
file containing the <code>$include</code>. The space after the <code>$include</code> before
the filename is mandatory. Sail also supports <code>$define</code>, <code>$ifdef</code>, and
<code>$ifndef</code> for basic conditional compilation. These are things that are
understood by Sail itself, not a separate preprocessor, and are
handled after the AST is parsed.</p>
</div>
<div class="paragraph">
<p>For more complex projects, a module hierarchy can be defined. See the
<a href="#_modules">Modules</a> section for details.</p>
</div>
<div class="sect2">
<h3 id="_sail_options">Sail options</h3>
<div class="paragraph">
<p>For backwards compatibility reasons, Sail accepts arguments of the
form <code>-long_opt</code>, i.e. leading with a single <code>-</code> and words
separated by <code>_</code>. Such an option will be treated the same as
<code>--long-opt</code>.</p>
</div>
<div class="paragraph">
<p>For a list of all options, one can call Sail as <code>sail --help</code>.</p>
</div>
<div style="page-break-after: always;"></div>
</div>
<div class="sect2">
<h3 id="_c_compilation">C compilation</h3>
<div class="paragraph">
<p>To compile Sail into C, the <code>-c</code> option is used, like so:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sh">sail <span class="nt">-c</span> FILES 1&gt; out.c</code></pre>
</div>
</div>
<div class="paragraph">
<p>The translated C is by default printed to stdout, but one can also use
the <code>-o</code> option to output to a file, so</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sh">sail <span class="nt">-c</span> FILES <span class="nt">-o</span> out</code></pre>
</div>
</div>
<div class="paragraph">
<p>will generate a file called <code>out.c</code>. To produce an executable
this needs to be compiled and linked with the C files in the
<code>$SAIL_DIR/lib</code> directory:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sh">gcc out.c <span class="nv">$SAIL_DIR</span>/lib/<span class="k">*</span>.c <span class="nt">-lgmp</span> <span class="nt">-I</span> <span class="nv">$SAIL_DIR</span>/lib/ <span class="nt">-o</span> out</code></pre>
</div>
</div>
<div class="paragraph">
<p>The C output requires the <a href="https://gmplib.org/">GMP library</a> for arbitrary precision
arithmetic.</p>
</div>
<div class="paragraph">
<p>There are several Sail options that affect the C output:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>-O</code> turns on optimisations. The generated C code will be quite slow
unless this flag is set.</p>
</li>
<li>
<p><code>--Oconstant-fold</code> apply constant folding optimisations.</p>
</li>
<li>
<p><code>--c-include</code> Supply additional header files to be included in the
generated C.</p>
</li>
<li>
<p><code>--c-no-main</code> Do not generate a <code>main()</code> function.</p>
</li>
<li>
<p><code>--static</code> Mark generated C functions as static where possible. This
is useful for measuring code coverage.</p>
</li>
</ul>
</div>
<div style="page-break-after: always;"></div>
</div>
<div class="sect2">
<h3 id="_systemverilog_compilation_experimental">SystemVerilog compilation (Experimental)</h3>
<div class="admonitionblock caution">
<table>
<tr>
<td class="icon">
<div class="title">Caution</div>
</td>
<td class="content">
This feature is new and experimental, so it is not guaranteed
to provide working SystemVerilog. Furthermore, it is intended for
hardware model checking against a hand-written design. Sail is not a
hardware description language!
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>To compile Sail into SystemVerilog, the <code>--sv</code> option is used. The <code>-o</code>
option provides a prefix that is used on the various generated files.</p>
</div>
<div class="paragraph">
<p>There are several options for the SystemVerilog output:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>--sv-output-dir</code> Generate all files in the specified directory</p>
</li>
<li>
<p><code>--sv-include</code> Add an include directive to the generated SystemVerilog</p>
</li>
<li>
<p><code>--sv-verilate</code> Can be used as either <code>--sv-verilate run</code> or
<code>--sv-verilate compile</code>. If used Sail will automatically invoke
<a href="https://www.veripool.org/verilator/">verilator</a> on the generated
SystemVerilog</p>
</li>
<li>
<p><code>--sv-lines</code> Output SystemVerilog `line directives to aid debugging.</p>
</li>
<li>
<p><code>--sv-int-size</code> Set the maximum integer size allowed in the specification.</p>
</li>
<li>
<p><code>--sv-bits-size</code> Bound the maximum bitvector width on the generated SystemVerilog.</p>
</li>
<li>
<p><code>--sv-specialize</code> The <code>--sv-specialize n</code> option will perform <code>n</code>
rounds of specialisation on the Sail code before generating
SystemVerilog. This will make bitvectors more monomorphic, but at
the cost of code duplication.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>The are various other options that control various minutae about the
generated SystemVerilog, see <code>sail --help</code> for more details.</p>
</div>
<div style="page-break-after: always;"></div>
</div>
<div class="sect2">
<h3 id="_automatic_formatting_experimental">Automatic formatting (Experimental)</h3>
<div class="admonitionblock caution">
<table>
<tr>
<td class="icon">
<div class="title">Caution</div>
</td>
<td class="content">
This feature is new and experimental, so be sure to inspect
changes to source made by the tool and use at your own risk!
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>Sail supports automatic code formatting similar to tools like <code>go fmt</code>
or <code>rustfmt</code>. This is built into Sail itself, and can be used via the
<code>--fmt</code> flag. To format a file <code>my_file.sail</code>, we would use the command:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sh">sail <span class="nt">--fmt</span> my_file.sail</code></pre>
</div>
</div>
<div class="paragraph">
<p>Note that Sail does not attempt to type-check files when formatting
them, so in this case we do not necessarily have to pass the other
files that <code>my_file.sail</code> would otherwise require to
type-check. However, it is perfectly fine to pass multiple files like
so:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sh">sail <span class="nt">--fmt</span> file1.sail file2.sail file3.sail</code></pre>
</div>
</div>
<div class="paragraph">
<p>The one exception is if a file uses a custom infix operator, then the
file that declares that operator must be passed before any file that
uses it. So if <code>my_file.sail</code> uses an operator declared in
<code>operator.sail</code> (otherwise it would not be able to parenthesize infix
expressions correctly), we would be required to do:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sh">sail <span class="nt">--fmt</span> operator.sail my_file.sail</code></pre>
</div>
</div>
<div class="paragraph">
<p>This will format both files. If we want to avoid formatting
<code>operator.sail</code>, we could either use <code>--fmt-skip</code>, like so:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sh">sail <span class="nt">--fmt-skip</span> operator.sail <span class="nt">--fmt</span> operator.sail my_file.sail</code></pre>
</div>
</div>
<div class="paragraph">
<p>or the <code>--fmt-only</code> option, like so:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sh">sail <span class="nt">--fmt-only</span> my_file.sail <span class="nt">--fmt</span> operator.sail my_file.sail</code></pre>
</div>
</div>
<div class="paragraph">
<p>Both of these options can be passed multiple times if required.</p>
</div>
<div class="paragraph">
<p>Formatting configuration is done using a JSON configuration file:
as:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="json"><span class="p">{</span><span class="w">
    </span><span class="nl">"fmt"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w">
        </span><span class="nl">"indent"</span><span class="p">:</span><span class="w"> </span><span class="mi">4</span><span class="p">,</span><span class="w">
        </span><span class="nl">"preserve_structure"</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="p">,</span><span class="w">
        </span><span class="nl">"line_width"</span><span class="p">:</span><span class="w"> </span><span class="mi">120</span><span class="p">,</span><span class="w">
        </span><span class="nl">"ribbon_width"</span><span class="p">:</span><span class="w"> </span><span class="mf">1.0</span><span class="w">
    </span><span class="p">}</span><span class="w">
</span><span class="p">}</span><span class="w">
</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>which is passed to sail with the <code>--config</code> flag.</p>
</div>
<div class="paragraph">
<p>The various keys supported under the <code>"fmt"</code> key are as follows:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>indent</code> The default indentation level</p>
</li>
<li>
<p><code>preserve_structure</code> Preserve the structure of the syntax tree as
much as possible. Note that the use of this operation is not
recommended as it inhibits many formatting options, such as
inserting blocks on if statements and loops.</p>
</li>
<li>
<p><code>line_width</code> The desired maximum line-width. Note that this is a
soft limit, and the line-width can go beyond if there are no
possible line break options (e.g. if you have <em>extremely</em> long
identifiers).</p>
</li>
<li>
<p><code>ribbon_width</code> A soft limit on what proportion (between 0.0 and 1.0)
of the line should be non-whitespace. A value of 1.0 indicates that the
entirity of <code>line_width</code> can be taken up by non-whitespace.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>If this file is not passed on the command line, Sail will check the
<code>$SAIL_CONFIG</code> environment variable, and if that is unset it will
search for a file named <code>sail_config.json</code> in the current working
directory, then recursively backwards through parent directories.</p>
</div>
<div style="page-break-after: always;"></div>
</div>
<div class="sect2">
<h3 id="_interactive_mode">Interactive mode</h3>
<div class="paragraph">
<p>Sail has a GHCi-style interactive interpreter. This can be used by
starting Sail with <code>sail -i</code>.  Sail will still handle any other
command line arguments as per usual. To use Sail files within the
interpreter they must be passed on the command line as if they were
being compiled normally. One can also pass a list of commands to the
interpreter by using the <code>--is</code> flag, as</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sh">sail <span class="nt">--is</span> &lt;file&gt;</code></pre>
</div>
</div>
<div class="paragraph">
<p>where <code>&lt;file&gt;</code> contains a list of commands. Once inside the
interactive mode, a list of available commands can be accessed by
typing <code>:commands</code>, while <code>:help &lt;command&gt;</code> can be used to provide
some documentation for each command.</p>
</div>
<div style="page-break-after: always;"></div>
</div>
<div class="sect2">
<h3 id="_other_options">Other options</h3>
<div class="paragraph">
<p>Here we summarize most of the other options available for
Sail. Debugging options (usually for debugging Sail itself) are
indicated by starting with the letter <code>d</code>.</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>-v</code> Print the Sail version.</p>
</li>
<li>
<p><code>-help</code> Print a list of options.</p>
</li>
<li>
<p><code>--no-warn</code> Turn off warnings.</p>
</li>
<li>
<p><code>--enum-casts</code> Allow elements of enumerations to be
automatically cast to numbers.</p>
</li>
<li>
<p><code>--memo-z3</code> Memoize calls to the Z3 solver. This can greatly improve
typechecking times if you are repeatedly typechecking the same
specification while developing it.</p>
</li>
<li>
<p><code>--no-lexp-bounds-check</code> Turn off bounds checking in the left hand
side of assignments. This option only exists for some Sail translated
from ASL (as ASL does not do compile-time bounds checking here).</p>
</li>
<li>
<p><code>--just-check</code> Force Sail to terminate immediately after
typechecking.</p>
</li>
<li>
<p><code>--require-version</code>. Check that the Sail version is newer than the
specified version, if not Sail will print an error and exit with a
non-zero exit code.</p>
</li>
</ul>
</div>
<div style="page-break-after: always;"></div>
</div>
<div class="sect2">
<h3 id="_debug_options">Debug options</h3>
<div class="paragraph">
<p>These options are mostly used for debugging the Sail compiler itself.
They are included as they might be useful for those writing custom Sail
plugins. These options are all prefixed with <code>d</code>.</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>--dtc-verbose &lt;verbosity&gt;</code> Make the typechecker print a
trace of typing judgements. If the verbosity level is 1, then this
should only include fairly readable judgements about checking and
inference rules. If verbosity is 2 then it will include a large
amount of debugging information. This option can be useful to
diagnose tricky type-errors, especially if the error message isn&#8217;t
very good.</p>
</li>
<li>
<p><code>--ddump-initial-ast</code> Write the AST out immediately after parsing
and desugaring.</p>
</li>
<li>
<p><code>--ddump-tc-ast</code> Write the typechecked AST to stdout after
typechecking</p>
</li>
<li>
<p><code>--ddump-side-effects</code> Print inferred information about function
side effects</p>
</li>
<li>
<p><code>--ddump-rewrite-ast &lt;prefix&gt;</code> Write the AST out after each
re-writing pass. The output from each pass is placed in a file
starting with <code>prefix</code>.</p>
</li>
<li>
<p><code>--dmagic-hash</code> Allow the <code>#</code> symbol in identifiers. It&#8217;s
currently used as a magic symbol to separate generated identifiers
from those the user can write, so this option allows for the output
of the various other debugging options to be fed back into Sail. The
name comes from the GHC option with the same purpose:
<a href="https://ghc.gitlab.haskell.org/ghc/doc/users_guide/exts/magic_hash.html" class="bare">ghc.gitlab.haskell.org/ghc/doc/users_guide/exts/magic_hash.html</a></p>
</li>
</ul>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_the_sail_language">The Sail Language</h2>
<div class="sectionbody">
<div class="sect2">
<h3 id="_functions">Functions</h3>
<div class="paragraph">
<p>In Sail, we often define functions in two parts. First we can write
the type signature for the function using the <code>val</code> keyword, then
define the body of the function using the <code>function</code> keyword. In this
Subsection, we will write our own version of the <code>replicate_bits</code>
function from the Sail library. This function takes a number <code>n</code> and a
bitvector, and creates a new bitvector containing that bitvector
copied <code>n</code> times.</p>
</div>
<div id="mrb-val-my_replicate_bits" class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="k">val</span><span class="w"> </span><span class="nf">my_replicate_bits</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="k">forall</span><span class="w"> </span><span class="nv">'n</span><span class="w"> </span><span class="nv">'m</span><span class="p">,</span><span class="w"> </span><span class="nv">'m</span><span class="w"> </span><span class="o">&gt;=</span><span class="w"> </span><span class="mi">1</span><span class="w"> </span><span class="o">&amp;</span><span class="w"> </span><span class="nv">'n</span><span class="w"> </span><span class="o">&gt;=</span><span class="w"> </span><span class="mi">1</span><span class="o">.</span><span class="w">
    </span><span class="p">(</span><span class="kt">int</span><span class="p">(</span><span class="nv">'n</span><span class="p">),</span><span class="w"> </span><span class="kt">bits</span><span class="p">(</span><span class="nv">'m</span><span class="p">))</span><span class="w"> </span><span class="p">-&gt;</span><span class="w"> </span><span class="kt">bits</span><span class="p">(</span><span class="nv">'n</span><span class="w"> </span><span class="o">*</span><span class="w"> </span><span class="nv">'m</span><span class="p">)</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>This signature shows how Sail can track the length of bitvectors and
the value of integer variables in type signatures, using <em>type
variables</em>. Type variables are written with a leading 'tick', so <code>'n</code>
and <code>'m</code> are the type variables in the above signature.</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">
The leading tick is a convention derived from Standard ML, and
other functional languages derived from Standard ML, such as OCaml.
Readers who are familiar with Rust will also recognise this naming
convention from lifetime variables in Rust types. The <code>val</code> keyword to
declare functions is also taken from OCaml.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>The type <code>bits('m)</code> is a bitvector of length <code>'m</code>, and <code>int('n)</code> is an
integer with the value <code>'n</code>. The result of this function will
therefore be a bitvector of length <code>'n * 'm</code>. We can also add
<em>constraints</em> on these types. Here we require that we are replicating
the input bitvector at least once with the <code>'n &gt;= 1</code> constraint, and
that the input bitvector length is at least one with the <code>'m &gt;= 1</code>
constraint. Sail will check that all callers of this function are
guaranteed to satisfy these constraints.</p>
</div>
<div class="paragraph">
<p>Sail will also ensure that the output of our function has precisely
the length <code>bits('n * 'm)</code> for all possible inputs (hence why the
keyword uses the mathematical <em>forall</em> quantifier).</p>
</div>
<div class="paragraph">
<p>A potential implementation of this function looks like:</p>
</div>
<div id="mrb-my_replicate_bits" class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="k">function</span><span class="w"> </span><span class="nf">my_replicate_bits</span><span class="p">(</span><span class="n">n</span><span class="p">,</span><span class="w"> </span><span class="n">xs</span><span class="p">)</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">{</span><span class="w">
    </span><span class="k">var</span><span class="w"> </span><span class="n">ys</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">zeros</span><span class="p">(</span><span class="n">n</span><span class="w"> </span><span class="o">*</span><span class="w"> </span><span class="n">length</span><span class="p">(</span><span class="n">xs</span><span class="p">));</span><span class="w">
    </span><span class="k">foreach</span><span class="w"> </span><span class="p">(</span><span class="n">i</span><span class="w"> </span><span class="k">from</span><span class="w"> </span><span class="mi">1</span><span class="w"> </span><span class="k">to</span><span class="w"> </span><span class="n">n</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w">
        </span><span class="n">ys</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">ys</span><span class="w"> </span><span class="o">&lt;&lt;</span><span class="w"> </span><span class="n">length</span><span class="p">(</span><span class="n">xs</span><span class="p">);</span><span class="w">
        </span><span class="n">ys</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">ys</span><span class="w"> </span><span class="o">|</span><span class="w"> </span><span class="n">zero_extend</span><span class="p">(</span><span class="n">xs</span><span class="p">,</span><span class="w"> </span><span class="n">length</span><span class="p">(</span><span class="n">ys</span><span class="p">))</span><span class="w">
    </span><span class="p">};</span><span class="w">
    </span><span class="n">ys</span><span class="w">
</span><span class="p">}</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>Functions may also have implicit parameters, e.g. we can implement a
zero extension function that implicitly picks up its result length
from the calling context as follows:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="k">val</span><span class="w"> </span><span class="nf">extz</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="k">forall</span><span class="w"> </span><span class="nv">'n</span><span class="w"> </span><span class="nv">'m</span><span class="p">,</span><span class="w"> </span><span class="nv">'m</span><span class="w"> </span><span class="o">&gt;=</span><span class="w"> </span><span class="nv">'n</span><span class="o">.</span><span class="w"> </span><span class="p">(</span><span class="kt">implicit</span><span class="p">(</span><span class="nv">'m</span><span class="p">),</span><span class="w"> </span><span class="kt">bits</span><span class="p">(</span><span class="nv">'n</span><span class="p">))</span><span class="w"> </span><span class="p">-&gt;</span><span class="w"> </span><span class="kt">bits</span><span class="p">(</span><span class="nv">'m</span><span class="p">)</span><span class="w">

</span><span class="k">function</span><span class="w"> </span><span class="nf">extz</span><span class="p">(</span><span class="n">m</span><span class="p">,</span><span class="w"> </span><span class="n">xs</span><span class="p">)</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">zero_extend</span><span class="p">(</span><span class="n">xs</span><span class="p">,</span><span class="w"> </span><span class="n">m</span><span class="p">)</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>Implicit parameters are always integers, and they must appear first
before any other parameters in the function type signature. The first
argument can then just be omitted when calling the function, like so:</p>
</div>
<div id="mrb-extz_usage" class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="k">let</span><span class="w"> </span><span class="n">xs</span><span class="p">:</span><span class="w"> </span><span class="kt">bits</span><span class="p">(</span><span class="mi">32</span><span class="p">)</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="mh">0x0000_0000</span><span class="p">;</span><span class="w">
</span><span class="k">let</span><span class="w"> </span><span class="n">ys</span><span class="p">:</span><span class="w"> </span><span class="kt">bits</span><span class="p">(</span><span class="mi">64</span><span class="p">)</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">extz</span><span class="p">(</span><span class="n">xs</span><span class="p">);</span></code></pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_blocks">Blocks</h3>
<div class="paragraph">
<p>You may have noticed that in the definition of <code>my_replicate_bits</code>
above, there was no <code>return</code> keyword. This is because unlike languages
such as C and C++, and more similar to languages like OCaml and Rust,
everything in Sail is an <em>expression</em> which evaluates to a value. A
block in Sail is simply a sequence of expressions surrounded by curly
braces <code>{</code> and <code>}</code>, and separated by semicolons. The value returned by
a block is the value returned by the last expression, and likewise
the type of a block is determined by its final expression, so
<code>{&#160;A;&#160;B;&#160;C&#160;}</code>, will evaluate to the value of <code>C</code>
after evaluating <code>A</code> and <code>B</code> in order. The expressions other than the
final expression in the block must have type <code>unit</code>, which is
discussed in the following section. Within blocks we can declare
immutable variables using <code>let</code>, and mutable variables using <code>var</code>,
for example:</p>
</div>
<div id="let-var-example" class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="p">{</span><span class="w">
    </span><span class="k">let</span><span class="w"> </span><span class="n">x</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="kt">int</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="mi">3</span><span class="p">;</span><span class="w">
    </span><span class="k">var</span><span class="w"> </span><span class="n">y</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="kt">int</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="mi">2</span><span class="p">;</span><span class="w">
    </span><span class="n">y</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">y</span><span class="w"> </span><span class="o">+</span><span class="w"> </span><span class="mi">1</span><span class="p">;</span><span class="w">
    </span><span class="n">x</span><span class="w"> </span><span class="o">+</span><span class="w"> </span><span class="n">y</span><span class="w">
</span><span class="p">}</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>The above block has type <code>int</code> and evaluates to the value <code>6</code>.</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">
For those familiar with Rust, a trailing semicolon in Sail does
not change the semantics of the block and is purely optional.
</td>
</tr>
</table>
</div>
</div>
<div class="sect2">
<h3 id="_the_unit_type">The <code>unit</code> type</h3>
<div class="paragraph">
<p>The simplest type in Sail is the <em>unit type</em> <code>unit</code>. It is a type with
a single member <code>()</code>. Rather than have functions that takes zero
arguments, we have functions that take a single <code>unit</code> argument.
Similarly, rather than having functions that return no results, a
function with no meaningful return value can return <code>()</code>. The <code>()</code>
notation reflects the fact that the unit type can be thought of as an
empty tuple (see <a href="#_tuples">Tuples</a>).</p>
</div>
<div class="paragraph">
<p>In Sail <code>unit</code> plays a similar role to void in C and C++, except
unlike void it is an ordinary type and can appear anywhere and be used
in generic functions.</p>
</div>
<div class="paragraph">
<p>The <a href="https://en.wikipedia.org/wiki/Unit_type">wikipedia page for the unit type</a>,
goes into further details on the difference between unit and void.</p>
</div>
</div>
<div class="sect2">
<h3 id="_numeric_types_and_bits">Numeric types and bits</h3>
<div class="paragraph">
<p>Sail has three basic numeric types, <code>int</code>, <code>nat</code>, and <code>range</code>. The
type <code>int</code> which we have already seen above is an arbitrary precision
mathematical integer. Likewise, <code>nat</code> is an arbitrary precision
natural number. The type <code>range('n,&#160;'m)</code> is an inclusive range
between type variables <code>'n</code> and <code>'m</code>. For both <code>int</code> and <code>nat</code> we can
specify a type variable that constrains elements of the type to be
equal to the value of that type variable. In other words, the values
of type <code>int('n)</code> are integers equal to <code>'n</code>. So
<code>5&#160;:&#160;int(5)</code> and similarly for any integer constant. These
types can often be used interchangeably provided certain constraints
are satisfied. For example, <code>int('n)</code> is equivalent to
<code>range('n,&#160;'n)</code> and <code>range('n,&#160;'m)</code> can be converted into
<code>int('n)</code> when <code>'n&#160;==&#160;'m</code>.</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">
The colon operator <code>:</code> is used for type ascription, so <code>x : Y</code>
is read as <code>x</code> <em>has type</em> <code>Y</code>
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>Note that <code>bit</code> isn&#8217;t a numeric type (i.e. it&#8217;s not
<code>range(0,&#160;1)</code>). This is intentional, as otherwise it would be
possible to write expressions like <code>(1&#160;:&#160;bit)&#160;+&#160;5</code>
which would end up being equivalent to
<code>6&#160;:&#160;range(5,&#160;6)</code>. This kind of implicit casting from
bits to other numeric types would be highly undesirable. The <code>bit</code>
type itself is a two-element type with members <code>bitzero</code> and <code>bitone</code>.</p>
</div>
<div class="paragraph">
<p>In addition, we can write a numeric type that only contains a fixed
set of integers. The type <code>{32,&#160;64}</code> is a type that can only
contain the values <code>32</code> and <code>64</code>.</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">
In older Sail versions the numeric set type would have been
denoted <code>{|32, 64|}</code>. This syntax is now deprecated.
</td>
</tr>
</table>
</div>
</div>
<div class="sect2">
<h3 id="_bitvector_literals">Bitvector literals</h3>
<div class="paragraph">
<p>Bitvector literals in Sail are written as either <code>0x</code> followed by a
sequence of hexadecimal digits (as in <code>0x12FE</code>) or <code>0b</code> followed by a
sequence of binary digits (as in <code>0b1010100</code>). The bit length of a
hex literal is always four times the number of hexadecimal digits,
and the bit length of binary literal is always the exact number of
binary digits. So, <code>0x12FE</code> has bit length 16, and <code>0b1010100</code> has
bit length 7. To ensure bitvector logic
in specifications is precisely specified, we do not allow any kind of
implicit widening or truncation as might occur in C. To change the
length of a bitvector, explicit zero/sign extension and truncation
functions must be used. Underscores can be used in bitvector literals
to separate groups, where each group is typically 16 bits. For
example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="k">let</span><span class="w"> </span><span class="n">large_bitvector</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="kt">bits</span><span class="p">(</span><span class="mi">64</span><span class="p">)</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="mh">0xFFFF_0000_1234_0000</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>We can make bitvectors as large as we need:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="k">let</span><span class="w"> </span><span class="n">even_larger_bitvector</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="kt">bits</span><span class="p">(</span><span class="mi">192</span><span class="p">)</span><span class="w"> </span><span class="p">=</span><span class="w">
  </span><span class="mh">0xFFFF_FFFF_FFFF_FFFF_0000_0000_0000_0000_ABCD_ABCD_ABCD_ABCD</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>We can also write bitvectors very verbosely using <code>bitzero</code> and
<code>bitone</code>, like:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="k">let</span><span class="w"> </span><span class="n">v</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="kt">bits</span><span class="p">(</span><span class="mi">2</span><span class="p">)</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">[</span><span class="nb">bitzero</span><span class="p">,</span><span class="w"> </span><span class="nb">bitzero</span><span class="p">]</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>The <code>@</code> operator is used to concatenate bitvectors, for example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="k">let</span><span class="w"> </span><span class="n">x</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="mh">0xFFFF</span><span class="p">;</span><span class="w">
</span><span class="k">let</span><span class="w"> </span><span class="n">y</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="mh">0x0000</span><span class="p">;</span><span class="w">
</span><span class="n">assert</span><span class="p">(</span><span class="n">x</span><span class="w"> </span><span class="p">@</span><span class="w"> </span><span class="n">y</span><span class="w"> </span><span class="p">==</span><span class="w"> </span><span class="mh">0xFFFF_0000</span><span class="p">);</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>For historical reasons the <code>bit</code> type is not equal to <code>bits(1)</code>, and
while this does simplify naively mapping the bits type into a (very
inefficient!) representation like <code>bit list</code> in Isabelle or OCaml, it
might be something we reconsider in the future.</p>
</div>
<div class="paragraph">
<p>Sail allows two different types of bitvector orderings---increasing
(<code>inc</code>) and decreasing (<code>dec</code>). These two orderings are shown for the
bitvector 0b10110000 below.</p>
</div>
<div class="imageblock text-center">
<div class="content">
<img src="ordering-tikz.png" alt="ordering tikz" width="70%">
</div>
</div>
<div class="paragraph">
<p>For increasing (bit)vectors, the 0 index is the most significant bit
and the indexing increases towards the least significant bit. Whereas
for decreasing (bit)vectors the least significant bit is 0 indexed,
and the indexing decreases from the most significant to the least
significant bit. For this reason, increasing indexing is sometimes
called `most significant bit is zero' or MSB0, while decreasing
indexing is sometimes called `least significant bit is zero' or
LSB0. While this vector ordering makes most sense for bitvectors (it
is usually called bit-ordering), in Sail it applies to all
vectors. A default ordering can be set using</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="k">default</span><span class="w"> </span><span class="kt">Order</span><span class="w"> </span><span class="kt">dec</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>and this should usually be done right at the beginning of a
specification. This setting is global, and increasing and decreasing
bitvectors can therefore never be mixed within the same specification!</p>
</div>
<div class="paragraph">
<p>In practice decreasing order is the almost universal standard and only
POWER uses increasing order. All currently maintained Sail
specifications use decreasing. You may run into issues with increasing
bitvectors as the code to support these is effectively never exercised
as a result.</p>
</div>
</div>
<div class="sect2">
<h3 id="_vectors">Vectors</h3>
<div class="paragraph">
<p>Sail has the built-in type <code>vector</code>, which is a polymorphic type for
fixed-length vectors. For example, we could define a vector <code>v</code> of
three integers as follows:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="k">let</span><span class="w"> </span><span class="n">v</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="n">vector</span><span class="p">(</span><span class="mi">3</span><span class="p">,</span><span class="w"> </span><span class="kt">int</span><span class="p">)</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">[</span><span class="mi">3</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="mi">1</span><span class="p">]</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>The first argument of the vector type is a numeric expression
representing the length of the vector, and the second is the type of
the vector&#8217;s elements. As mentioned in the bitvector section, the
ordering of bitvectors and vectors is always the same, so:</p>
</div>
<div id="vectorex-same_order" class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="w">    </span><span class="k">let</span><span class="w"> </span><span class="n">a_generic_vector</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="n">vector</span><span class="p">(</span><span class="mi">3</span><span class="p">,</span><span class="w"> </span><span class="n">bit</span><span class="p">)</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">[</span><span class="nb">bitzero</span><span class="p">,</span><span class="w"> </span><span class="nb">bitzero</span><span class="p">,</span><span class="w"> </span><span class="nb">bitone</span><span class="p">];</span><span class="w">
    </span><span class="k">let</span><span class="w"> </span><span class="n">a_bitvector</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="kt">bits</span><span class="p">(</span><span class="mi">3</span><span class="p">)</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">[</span><span class="nb">bitzero</span><span class="p">,</span><span class="w"> </span><span class="nb">bitzero</span><span class="p">,</span><span class="w"> </span><span class="nb">bitone</span><span class="p">];</span><span class="w"> </span><span class="c">// 0b001</span><span class="w">

    </span><span class="n">assert</span><span class="p">(</span><span class="n">a_generic_vector</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span><span class="w"> </span><span class="p">==</span><span class="w"> </span><span class="nb">bitone</span><span class="p">);</span><span class="w">
    </span><span class="n">assert</span><span class="p">(</span><span class="n">a_bitvector</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span><span class="w"> </span><span class="p">==</span><span class="w"> </span><span class="nb">bitone</span><span class="p">)</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>Note that a generic vector of bits and a bitvector are not the same
type, despite us being able to write them using the same syntax. This
means you cannot write a function that is polymorphic over both
generic vectors and bitvectors). This is because we typically want
these types to have very different representations in our various Sail
backends, and we don&#8217;t want to be forced into a compilation strategy
that requires monomorphising such functions.</p>
</div>
</div>
<div class="sect2">
<h3 id="_accessing_and_updating_vectors">Accessing and updating vectors</h3>
<div class="paragraph">
<p>A (bit)vector can be indexed by using the <em>vector index</em> notation. So,
in the following code:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="k">let</span><span class="w"> </span><span class="n">v</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="n">vector</span><span class="p">(</span><span class="mi">4</span><span class="p">,</span><span class="w"> </span><span class="kt">int</span><span class="p">)</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">[</span><span class="mi">1</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="mi">3</span><span class="p">,</span><span class="w"> </span><span class="mi">4</span><span class="p">]</span><span class="w">
</span><span class="k">let</span><span class="w"> </span><span class="n">a</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">v</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span><span class="w">
</span><span class="k">let</span><span class="w"> </span><span class="n">b</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">v</span><span class="p">[</span><span class="mi">3</span><span class="p">]</span></code></pre>
</div>
</div>
<div class="paragraph">
<p><code>a</code> will be <code>4</code>, and <code>b</code> will be <code>1</code> (we assume <code>default Order dec</code>
here). By default, Sail will statically check for out of bounds
errors, and will raise a type error if it cannot prove that all such
vector accesses are valid.</p>
</div>
<div class="paragraph">
<p>A vector <code>v</code> can be sliced using the <code>v[n&#160;..&#160;m]</code> notation. The
indexes are always supplied with the index closest to the MSB being
given first, so we would take the bottom 32-bits of a decreasing
bitvector <code>v</code> as <code>v[31&#160;..&#160;0]</code>, and the upper 32-bits of an
increasing bitvector as <code>v[0&#160;..&#160;31]</code>, i.e. the indexing
order for decreasing vectors decreases, and the indexing order for
increasing vectors increases.</p>
</div>
<div class="paragraph">
<p>A vector <code>v</code> can have an index <code>index</code> using
<code>[v&#160;with&#160;index&#160;=&#160;expression]</code>. Similarly, a
sub-range of v can be updated using
<code>[v&#160;with&#160;n&#160;..&#160;m&#160;=&#160;expression]</code> where the
order of the indexes is the same as described above for increasing and
decreasing vectors.</p>
</div>
</div>
<div class="sect2">
<h3 id="_the_list_type">The <code>list</code> type</h3>
<div class="paragraph">
<p>In addition to vectors, Sail also has <code>list</code> as a built-in type. For
example:</p>
</div>
<div id="list-example-example1" class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="k">let</span><span class="w"> </span><span class="n">l</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="n">list</span><span class="p">(</span><span class="kt">int</span><span class="p">)</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">[|</span><span class="mi">1</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="mi">3</span><span class="p">|]</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>The cons operator is <code>::</code>, so we could equally write:</p>
</div>
<div id="list-example-example2" class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="k">let</span><span class="w"> </span><span class="n">l</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="n">list</span><span class="p">(</span><span class="kt">int</span><span class="p">)</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="mi">1</span><span class="w"> </span><span class="p">::</span><span class="w"> </span><span class="mi">2</span><span class="w"> </span><span class="p">::</span><span class="w"> </span><span class="mi">3</span><span class="w"> </span><span class="p">::</span><span class="w"> </span><span class="p">[||]</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>For those unfamiliar the word, 'cons' is derived from Lisp dialects,
and has become standard functional programming jargon for such an
operator&#8201;&#8212;&#8201;see <a href="https://en.wikipedia.org/wiki/Cons" class="bare">en.wikipedia.org/wiki/Cons</a> for more details.</p>
</div>
<div class="admonitionblock caution">
<table>
<tr>
<td class="icon">
<div class="title">Caution</div>
</td>
<td class="content">
The list type (plus the recursive functions typically used to
manipulate lists) does not work well with certain Sail targets, such
as the SMT and SystemVerilog backends. The <code>vector</code> type is almost
always preferable to the <code>list</code> type. The inclusion of the list type
(where we otherwise forbid recursive types) was perhaps a design
mistake.
</td>
</tr>
</table>
</div>
</div>
<div class="sect2">
<h3 id="_tuples">Tuples</h3>
<div class="paragraph">
<p>Sail has tuple types which represent heterogeneous sequences containing
values of different types. A tuple type <code>(T1,&#160;T2,&#160;&#8230;&#8203;)</code> has
values <code>(x1,&#160;x2,&#160;&#8230;&#8203;)</code> where <code>x1&#160;:&#160;T1</code>,
<code>x2&#160;:&#160;T2</code> and so on. A tuple must have 2 or more elements.
Some examples of tuples would be:</p>
</div>
<div id="tuples-span-TUPLES" class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="k">let</span><span class="w"> </span><span class="n">tuple1</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="p">(</span><span class="n">string</span><span class="p">,</span><span class="w"> </span><span class="kt">int</span><span class="p">)</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">(</span><span class="s">"Hello, World!"</span><span class="p">,</span><span class="w"> </span><span class="mi">3</span><span class="p">)</span><span class="w">

</span><span class="k">let</span><span class="w"> </span><span class="n">tuple2</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="p">(</span><span class="n">nat</span><span class="p">,</span><span class="w"> </span><span class="n">nat</span><span class="p">,</span><span class="w"> </span><span class="n">nat</span><span class="p">)</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">(</span><span class="mi">1</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="mi">3</span><span class="p">)</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>Note that while the function type <code>(A,&#160;B)&#160;-&gt;&#160;C</code> might
look like a function taking a single tuple argument, it is in fact a
function taking two arguments. If we wanted to write a function taking
a single tuple argument, we would instead write:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="k">val</span><span class="w"> </span><span class="nf">single_tuple_argument</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="p">((</span><span class="kt">int</span><span class="p">,</span><span class="w"> </span><span class="kt">int</span><span class="p">))</span><span class="w"> </span><span class="p">-&gt;</span><span class="w"> </span><span class="kt">unit</span><span class="w">

</span><span class="k">function</span><span class="w"> </span><span class="nf">single_tuple_argument</span><span class="p">(</span><span class="n">tuple</span><span class="p">)</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">{</span><span class="w">
  </span><span class="k">let</span><span class="w"> </span><span class="p">(</span><span class="n">x</span><span class="p">,</span><span class="w"> </span><span class="n">y</span><span class="p">)</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">tuple</span><span class="p">;</span><span class="w">
  </span><span class="n">print_int</span><span class="p">(</span><span class="s">"x = "</span><span class="p">,</span><span class="w"> </span><span class="n">x</span><span class="p">);</span><span class="w">
  </span><span class="n">print_int</span><span class="p">(</span><span class="s">"y = "</span><span class="p">,</span><span class="w"> </span><span class="n">y</span><span class="p">);</span><span class="w">
</span><span class="p">}</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>which would be called as</p>
</div>
<div id="tuples-caller" class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="n">single_tuple_argument</span><span class="p">((</span><span class="mi">1</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">))</span></code></pre>
</div>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">
This is because in Sail the function type is denoted
<code>(A,&#160;B,&#160;&#8230;&#8203;)&#160;-&gt;&#160;C</code>, but we allow the brackets to
be elided when the function has a single non-tuple argument so we can
write <code>A&#160;-&gt;&#160;B</code> rather than <code>(A)&#160;-&gt;&#160;B</code>.
</td>
</tr>
</table>
</div>
</div>
<div class="sect2">
<h3 id="_strings">Strings</h3>
<div class="paragraph">
<p>Sail has a <code>string</code> type, which is primarily used for error reporting
and debugging.</p>
</div>
<div class="admonitionblock caution">
<table>
<tr>
<td class="icon">
<div class="title">Caution</div>
</td>
<td class="content">
Sail is not a language designed for working with strings, and
the semantics of ISA specifications should not depend on any logic
involving strings. If you find yourself using strings for reasons
other than printing or logging errors in a Sail specification, you
should probably reconsider.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>A Sail string is any sequence of ASCII characters between double
quotes. Backslash is used to introduce escape sequences, and the
following escape sequences are supported:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>\\</code>&#8201;&#8212;&#8201;Backslash</p>
</li>
<li>
<p><code>\n</code>&#8201;&#8212;&#8201;Newline character</p>
</li>
<li>
<p><code>\t</code>&#8201;&#8212;&#8201;Tab character</p>
</li>
<li>
<p><code>\b</code>&#8201;&#8212;&#8201;Backspace character</p>
</li>
<li>
<p><code>\r</code>&#8201;&#8212;&#8201;Carriage return</p>
</li>
<li>
<p><code>\'</code>&#8201;&#8212;&#8201;Single quote (somewhat unnecessary, as single quotes are allowed in Sail strings)</p>
</li>
<li>
<p><code>\"</code>&#8201;&#8212;&#8201;Double quote</p>
</li>
<li>
<p><code>\DDD</code>&#8201;&#8212;&#8201;The character with decimal ASCII code <code>DDD</code></p>
</li>
<li>
<p><code>\xHH</code>&#8201;&#8212;&#8201;The character with hexadecimal ASCII code <code>HH</code></p>
</li>
</ul>
</div>
<div class="paragraph">
<p>Multi-line strings can be written by escaping the newline character at the end of a line:</p>
</div>
<div id="strings-multi_line" class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="n">print_endline</span><span class="p">(</span><span class="s">"Hello, </span><span class="err">\
</span><span class="s">               World!"</span><span class="p">);</span><span class="w">
</span><span class="c">// Is equivalent to</span><span class="w">
</span><span class="n">print_endline</span><span class="p">(</span><span class="s">"Hello, World!"</span><span class="p">)</span></code></pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_user_defined_types">User-defined types</h3>
<div class="paragraph">
<p>Sail supports various kinds of user-defined types: <em>structs</em>,
<em>unions</em>, and <em>enums</em>.</p>
</div>
<div class="sect3">
<h4 id="_structs">Structs</h4>
<div class="paragraph">
<p>Like in C, structs are used to hold multiple values. Structs are
created using the <code>struct</code> keyword followed by the name of the struct.
The data the struct contains is then defined following the <code>=</code> symbol.
Each piece of data stored in a struct is called a <code>field</code>, and each is
given a unique name that identifies that piece of data, and can have a
different type.</p>
</div>
<div class="paragraph">
<p>The following example struct defines three fields. The first contains
a bitvector of length 5 and is called <code>field1</code>. The second, <code>field2</code>
contains an integer. The third, <code>field3</code> contains a string.</p>
</div>
<div id="struct-type-My_struct" class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="k">struct</span><span class="w"> </span><span class="n">My_struct</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">{</span><span class="w">
  </span><span class="n">field1</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="kt">bits</span><span class="p">(</span><span class="mi">5</span><span class="p">),</span><span class="w">
  </span><span class="n">field2</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="kt">int</span><span class="p">,</span><span class="w">
  </span><span class="n">field3</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="n">string</span><span class="p">,</span><span class="w">
</span><span class="p">}</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>We can then construct struct values by using the <code>struct</code> keyword and
providing values for all the fields. The individual fields can be
accessed using the <code>.</code> operator. If the struct is mutable, we can also
the <code>.</code> operator on the left-hand side of an assignment to assign to
the struct field. For immutable structs, we can update them using the
<code>with</code> keyword, which will create a new struct value with some fields
changed.</p>
</div>
<div id="struct-example" class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="w">  </span><span class="k">let</span><span class="w"> </span><span class="n">s</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="n">My_struct</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="k">struct</span><span class="w"> </span><span class="p">{</span><span class="w">
    </span><span class="n">field1</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="mb">0b11111</span><span class="p">,</span><span class="w">
    </span><span class="n">field2</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="mi">5</span><span class="p">,</span><span class="w">
    </span><span class="n">field3</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="s">"test"</span><span class="p">,</span><span class="w">
  </span><span class="p">};</span><span class="w">

  </span><span class="c">// Accessing a struct field, prints "field1 is 0b11111"</span><span class="w">
  </span><span class="n">print_bits</span><span class="p">(</span><span class="s">"field1 is "</span><span class="p">,</span><span class="w"> </span><span class="n">s</span><span class="o">.</span><span class="n">field1</span><span class="p">);</span><span class="w">

  </span><span class="c">// Updating struct fields, creating a new struct variable s2</span><span class="w">
  </span><span class="k">var</span><span class="w"> </span><span class="n">s2</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="n">s</span><span class="w"> </span><span class="k">with</span><span class="w"> </span><span class="n">field1</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="mb">0b00000</span><span class="p">,</span><span class="w"> </span><span class="n">field3</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="s">"a string"</span><span class="w"> </span><span class="p">};</span><span class="w">

  </span><span class="c">// Prints "field1 is 0b00000"</span><span class="w">
  </span><span class="n">print_bits</span><span class="p">(</span><span class="s">"field1 is "</span><span class="p">,</span><span class="w"> </span><span class="n">s2</span><span class="o">.</span><span class="n">field1</span><span class="p">);</span><span class="w">
  </span><span class="c">// Prints "field2 is 5", as field2 was taken from 's' and not modified</span><span class="w">
  </span><span class="n">print_int</span><span class="p">(</span><span class="s">"field2 is "</span><span class="p">,</span><span class="w"> </span><span class="n">s2</span><span class="o">.</span><span class="n">field2</span><span class="p">);</span><span class="w">

  </span><span class="c">// Because s2 is mutable we can assign to it</span><span class="w">
  </span><span class="n">s2</span><span class="o">.</span><span class="n">field3</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="s">"some string"</span><span class="p">;</span><span class="w">
  </span><span class="c">// Prints "some string"</span><span class="w">
  </span><span class="n">print_endline</span><span class="p">(</span><span class="n">s2</span><span class="o">.</span><span class="n">field3</span><span class="p">)</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>Structs can have user defined type parameters. The following example
has an integer parameter <code>'n</code> and a type parameter <code>'a</code>.</p>
</div>
<div id="struct-type-My_other_struct" class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="k">struct</span><span class="w"> </span><span class="n">My_other_struct</span><span class="p">(</span><span class="nv">'n</span><span class="p">,</span><span class="w"> </span><span class="nv">'a</span><span class="p">)</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">{</span><span class="w">
  </span><span class="n">a_bitvector</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="kt">bits</span><span class="p">(</span><span class="nv">'n</span><span class="p">),</span><span class="w">
  </span><span class="n">something</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="nv">'a</span><span class="w">
</span><span class="p">}</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>The struct can then be instantiated with any length of bitvector for
the <code>a_bitvector</code> field, and any data type for the <code>something</code> field,
including another struct like the <code>My_struct</code> type we defined earlier.</p>
</div>
<div id="struct-poly_example" class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="w">  </span><span class="k">var</span><span class="w"> </span><span class="n">s3</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="n">My_other_struct</span><span class="p">(</span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="n">string</span><span class="p">)</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="k">struct</span><span class="w"> </span><span class="p">{</span><span class="w">
    </span><span class="n">a_bitvector</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="mb">0b00</span><span class="p">,</span><span class="w">
    </span><span class="n">something</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="s">"a string"</span><span class="w">
  </span><span class="p">};</span><span class="w">

  </span><span class="k">var</span><span class="w"> </span><span class="n">s4</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="n">My_other_struct</span><span class="p">(</span><span class="mi">32</span><span class="p">,</span><span class="w"> </span><span class="n">My_struct</span><span class="p">)</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="k">struct</span><span class="w"> </span><span class="p">{</span><span class="w">
    </span><span class="n">a_bitvector</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="mh">0xFFFF_FFFF</span><span class="p">,</span><span class="w">
    </span><span class="n">something</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="k">struct</span><span class="w"> </span><span class="p">{</span><span class="w">
      </span><span class="n">field1</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="mb">0b11111</span><span class="p">,</span><span class="w">
      </span><span class="n">field2</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="mi">6</span><span class="p">,</span><span class="w">
      </span><span class="n">field3</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="s">"nested structs!"</span><span class="p">,</span><span class="w">
    </span><span class="p">}</span><span class="w">
  </span><span class="p">};</span><span class="w">

  </span><span class="n">s3</span><span class="o">.</span><span class="n">a_bitvector</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="mb">0b11</span><span class="p">;</span><span class="w">

  </span><span class="c">// Note that once created, we cannot change a variable's type, so the following is forbidden:</span><span class="w">
  </span><span class="c">// s3.a_bitvector = 0xFFFF_FFFF;</span><span class="w">

  </span><span class="c">// Changing the type is also forbidden in a with expression:</span><span class="w">
  </span><span class="c">// let s4 : My_other_struct(32, string) = { s3 with a_bitvector = 0xFFFF_FFFF };</span><span class="w">

  </span><span class="c">// If structs are nested, then field accesses can also be nested</span><span class="w">
  </span><span class="n">print_endline</span><span class="p">(</span><span class="n">s4</span><span class="o">.</span><span class="n">something</span><span class="o">.</span><span class="n">field3</span><span class="p">);</span><span class="w">
  </span><span class="c">// and assignments</span><span class="w">
  </span><span class="n">s4</span><span class="o">.</span><span class="n">something</span><span class="o">.</span><span class="n">field3</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="s">"another string"</span></code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="_enums">Enums</h4>
<div class="paragraph">
<p>Sail enumerations are also much like their C counterparts. An enum is
declared using the <code>enum</code> keyword followed by the name of the
enumeration type. The members of the enumeration are specified as a
comma-separated list of identifiers between curly braces, like so:</p>
</div>
<div id="enum-type-My_enum" class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="k">enum</span><span class="w"> </span><span class="n">My_enum</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">{</span><span class="w">
  </span><span class="n">Foo</span><span class="p">,</span><span class="w">
  </span><span class="n">Bar</span><span class="p">,</span><span class="w">
  </span><span class="n">Baz</span><span class="p">,</span><span class="w">
  </span><span class="n">Quux</span><span class="p">,</span><span class="w">
</span><span class="p">}</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>The above style is best when there are a lot of elements in the
enumeration. We allow enums to be defined in a style similar to
Haskell, where the identifiers are separated by a vertical bar <code>|</code>
character, like so:</p>
</div>
<div id="enum-type-My_short_enum" class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="k">enum</span><span class="w"> </span><span class="n">My_short_enum</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">A</span><span class="w"> </span><span class="o">|</span><span class="w"> </span><span class="n">B</span><span class="w"> </span><span class="o">|</span><span class="w"> </span><span class="n">C</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>This style is better when the enumeration is short and has few
constructors, however specification authors may prefer to use the
first style exclusively for consistency.</p>
</div>
<div class="paragraph">
<p>Sail will automatically generate functions for converting enumeration
members into numbers, starting with 0 for the first element of the
enumeration.</p>
</div>
<div id="enum-enum_example1" class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="k">function</span><span class="w"> </span><span class="nf">enum_example1</span><span class="p">()</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">{</span><span class="w">
  </span><span class="n">assert</span><span class="p">(</span><span class="n">num_of_My_enum</span><span class="p">(</span><span class="n">Foo</span><span class="p">)</span><span class="w"> </span><span class="p">==</span><span class="w"> </span><span class="mi">0</span><span class="p">);</span><span class="w">
  </span><span class="n">assert</span><span class="p">(</span><span class="n">num_of_My_enum</span><span class="p">(</span><span class="n">Bar</span><span class="p">)</span><span class="w"> </span><span class="p">==</span><span class="w"> </span><span class="mi">1</span><span class="p">);</span><span class="w">
  </span><span class="n">assert</span><span class="p">(</span><span class="n">num_of_My_enum</span><span class="p">(</span><span class="n">Baz</span><span class="p">)</span><span class="w"> </span><span class="p">==</span><span class="w"> </span><span class="mi">2</span><span class="p">);</span><span class="w">
  </span><span class="n">assert</span><span class="p">(</span><span class="n">num_of_My_enum</span><span class="p">(</span><span class="n">Quux</span><span class="p">)</span><span class="w"> </span><span class="p">==</span><span class="w"> </span><span class="mi">3</span><span class="p">);</span><span class="w">
</span><span class="p">}</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>Likewise, there is a function for converting the other way</p>
</div>
<div id="enum-enum_example2" class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="k">function</span><span class="w"> </span><span class="nf">enum_example2</span><span class="p">()</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">{</span><span class="w">
  </span><span class="n">assert</span><span class="p">(</span><span class="n">My_enum_of_num</span><span class="p">(</span><span class="mi">0</span><span class="p">)</span><span class="w"> </span><span class="p">==</span><span class="w"> </span><span class="n">Foo</span><span class="p">)</span><span class="w">
</span><span class="p">}</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>If the names of the generated functions are not ideal, then custom
names can be provided using the <code>enum_number_conversions</code> attribute.</p>
</div>
<div id="enum-span-ENUM_CONV" class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="cp">$[enum_number_conversions { from_enum = to_number, to_enum = from_number }]</span><span class="w">
</span><span class="k">enum</span><span class="w"> </span><span class="n">Another_enum</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">{</span><span class="w">
  </span><span class="n">Member1</span><span class="p">,</span><span class="w">
  </span><span class="n">Member2</span><span class="p">,</span><span class="w">
</span><span class="p">}</span><span class="w">

</span><span class="k">function</span><span class="w"> </span><span class="nf">custom_conversions</span><span class="p">()</span><span class="w"> </span><span class="p">-&gt;</span><span class="w"> </span><span class="kt">unit</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">{</span><span class="w">
  </span><span class="n">assert</span><span class="p">(</span><span class="n">to_number</span><span class="p">(</span><span class="n">Member1</span><span class="p">)</span><span class="w"> </span><span class="p">==</span><span class="w"> </span><span class="mi">0</span><span class="p">);</span><span class="w">
  </span><span class="n">assert</span><span class="p">(</span><span class="n">from_number</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span><span class="w"> </span><span class="p">==</span><span class="w"> </span><span class="n">Member2</span><span class="p">);</span><span class="w">
</span><span class="p">}</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>The <code>no_enum_number_conversions</code> attribute can be used to disable the
generation of these functions entirely.</p>
</div>
<div class="paragraph">
<p>We also support generating a vector containing all elements of the
enumeration, using the <code>enum_vector</code> attribute.</p>
</div>
<div id="enum-span-ENUM_VECTOR" class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="cp">$[enum_vector my_enum_members]</span><span class="w">
</span><span class="k">enum</span><span class="w"> </span><span class="n">My_other_enum</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="n">M1</span><span class="p">,</span><span class="w"> </span><span class="n">M2</span><span class="p">,</span><span class="w"> </span><span class="n">M3</span><span class="w"> </span><span class="p">}</span><span class="w">

</span><span class="k">function</span><span class="w"> </span><span class="nf">iterate</span><span class="p">()</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">{</span><span class="w">
  </span><span class="k">foreach</span><span class="w"> </span><span class="p">(</span><span class="n">i</span><span class="w"> </span><span class="k">from</span><span class="w"> </span><span class="mi">0</span><span class="w"> </span><span class="k">to</span><span class="w"> </span><span class="p">(</span><span class="n">length</span><span class="p">(</span><span class="n">my_enum_members</span><span class="p">)</span><span class="w"> </span><span class="o">-</span><span class="w"> </span><span class="mi">1</span><span class="p">))</span><span class="w"> </span><span class="p">{</span><span class="w">
    </span><span class="k">match</span><span class="w"> </span><span class="n">my_enum_members</span><span class="p">[</span><span class="n">i</span><span class="p">]</span><span class="w"> </span><span class="p">{</span><span class="w">
      </span><span class="n">M1</span><span class="w"> </span><span class="p">=</span><span class="o">&gt;</span><span class="w"> </span><span class="n">print_endline</span><span class="p">(</span><span class="s">"1"</span><span class="p">),</span><span class="w">
      </span><span class="n">M2</span><span class="w"> </span><span class="p">=</span><span class="o">&gt;</span><span class="w"> </span><span class="n">print_endline</span><span class="p">(</span><span class="s">"2"</span><span class="p">),</span><span class="w">
      </span><span class="n">M3</span><span class="w"> </span><span class="p">=</span><span class="o">&gt;</span><span class="w"> </span><span class="n">print_endline</span><span class="p">(</span><span class="s">"3"</span><span class="p">),</span><span class="w">
    </span><span class="p">}</span><span class="w">
  </span><span class="p">}</span><span class="w">
</span><span class="p">}</span></code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="_unions">Unions</h4>
<div class="paragraph">
<p>Structs provide us a way to group multiple pieces of related data, for example</p>
</div>
<div id="union-type-rectangle" class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="k">struct</span><span class="w"> </span><span class="n">rectangle</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">{</span><span class="w">
    </span><span class="n">width</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="kt">int</span><span class="p">,</span><span class="w">
    </span><span class="n">height</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="kt">int</span><span class="p">,</span><span class="w">
</span><span class="p">}</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>defines a type <code>rectangle</code> that has both a width <em>and</em> a height. The
other logical way to combine data is if we want to say we have some
data <em>or</em> some other data, like if we wanted to represent a shape that
could be a circle <em>or</em> a rectangle. In Sail, we use a <em>union</em> for this.</p>
</div>
<div id="union-span-SHAPE" class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="k">struct</span><span class="w"> </span><span class="n">circle</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="n">radius</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="kt">int</span><span class="w"> </span><span class="p">}</span><span class="w">

</span><span class="k">union</span><span class="w"> </span><span class="n">shape</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">{</span><span class="w">
    </span><span class="n">Rectangle</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="n">rectangle</span><span class="p">,</span><span class="w">
    </span><span class="n">Circle</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="n">circle</span><span class="p">,</span><span class="w">
</span><span class="p">}</span></code></pre>
</div>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">
While structs are ubiquitous in programming languages, the
equivalent feature for safely representing disjunctions of types is
often a second-class afterthought or even absent entirely. The
requirement to safely represent disjunctions of types is why C&#8217;s
<code>union</code> feature is something different to what we want here, which is
sometimes called <em>tagged</em> unions or <em>variants</em> to distinguish them
from the unsafe C construct. C++ is therefore a good example of a
language where structs are first class, but <code>std::variant</code> is
relegated to a library feature.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>This defines a type with two <em>constructors</em> <code>Rectangle</code> and <code>Circle</code>.
Constructors are used like functions with a single argument, as so:</p>
</div>
<div id="union-example" class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="k">function</span><span class="w"> </span><span class="nf">example</span><span class="p">()</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">{</span><span class="w">
    </span><span class="c">// Construct a shape using the Rectangle constructor</span><span class="w">
    </span><span class="k">let</span><span class="w"> </span><span class="n">r</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="n">shape</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">Rectangle</span><span class="p">(</span><span class="k">struct</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="n">width</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="mi">30</span><span class="p">,</span><span class="w"> </span><span class="n">height</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="mi">20</span><span class="w"> </span><span class="p">});</span><span class="w">

    </span><span class="c">// Construct a shape using the Circle constructor</span><span class="w">
    </span><span class="c">// Note that we can allow the 'shape' type to be inferred</span><span class="w">
    </span><span class="k">let</span><span class="w"> </span><span class="n">c</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">Circle</span><span class="p">(</span><span class="k">struct</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="n">radius</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="mi">15</span><span class="w"> </span><span class="p">});</span><span class="w">
</span><span class="p">}</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>To destructure unions, we typically use <em>pattern matching</em> to handle
each case in the union separately. This will be discussed in detail in
<a href="#_pattern_matching">Pattern matching</a>.</p>
</div>
<div class="paragraph">
<p>Constructors in Sail always have a single argument. If we want a
constructor in a union type to contain no information, then we can use
the <code>unit</code> type. For a constructor with multiple arguments we can use
a tuple type. We provide some syntax sugar that allows writing
constructor applications with either tuple or unit argument types as
if they were functions with multiple arguments or no arguments
respectively.</p>
</div>
<div id="union-span-EX_UNIT" class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="k">union</span><span class="w"> </span><span class="n">example_unit_constructor</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">{</span><span class="w">
  </span><span class="n">Foo</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="p">(</span><span class="kt">int</span><span class="p">,</span><span class="w"> </span><span class="n">string</span><span class="p">),</span><span class="w">
  </span><span class="n">Bar</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="kt">unit</span><span class="p">,</span><span class="w">
</span><span class="p">}</span><span class="w">

</span><span class="c">// Using a constructor with a tuple type</span><span class="w">
</span><span class="k">let</span><span class="w"> </span><span class="n">x1</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">Foo</span><span class="p">(</span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="s">"a string"</span><span class="p">)</span><span class="w">

</span><span class="c">// Note that the above is equivalent to</span><span class="w">
</span><span class="k">let</span><span class="w"> </span><span class="n">x2</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">Foo</span><span class="p">((</span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="s">"a string"</span><span class="p">))</span><span class="w">

</span><span class="c">// Using a unit-type constructor</span><span class="w">
</span><span class="k">let</span><span class="w"> </span><span class="n">y1</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">Bar</span><span class="p">()</span><span class="w">

</span><span class="c">// Similarly, equivalent to</span><span class="w">
</span><span class="k">let</span><span class="w"> </span><span class="n">y2</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">Bar</span><span class="p">(())</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>In our shape example, we defined <code>rectangle</code> and <code>circle</code> as two
separate structs, but if we wanted we could declare those structs
inline</p>
</div>
<div id="union-type-shape2" class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="k">union</span><span class="w"> </span><span class="n">shape2</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">{</span><span class="w">
    </span><span class="n">Rectangle2</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="n">width</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="kt">int</span><span class="p">,</span><span class="w"> </span><span class="n">height</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="kt">int</span><span class="w"> </span><span class="p">},</span><span class="w">
    </span><span class="n">Circle2</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="n">radius</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="kt">int</span><span class="w"> </span><span class="p">},</span><span class="w">
</span><span class="p">}</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>Behind the scenes, Sail will just generate separate struct
definitions, so we use this type in exactly the same was as we did
previously.</p>
</div>
<div class="paragraph">
<p>As with structs, we can define polymorphic union types, like</p>
</div>
<div id="union-type-either" class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="k">union</span><span class="w"> </span><span class="n">either</span><span class="p">(</span><span class="nv">'a</span><span class="p">,</span><span class="w"> </span><span class="nv">'b</span><span class="p">)</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">{</span><span class="w">
    </span><span class="n">Left</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="nv">'a</span><span class="p">,</span><span class="w">
    </span><span class="n">Right</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="nv">'b</span><span class="p">,</span><span class="w">
</span><span class="p">}</span></code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="_newtype"><code>newtype</code></h4>
<div class="paragraph">
<p>There is a slight variation of the <code>union</code> keyword, which allows
constructing a union with just a single constructor:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="k">newtype</span><span class="w"> </span><span class="n">register_index</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">Mk_index</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="kt">bits</span><span class="p">(</span><span class="mi">5</span><span class="p">)</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>this is semantically equivalent to</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="k">union</span><span class="w"> </span><span class="n">register_index</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">{</span><span class="w">
  </span><span class="n">Mk_index</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="kt">bits</span><span class="p">(</span><span class="mi">5</span><span class="p">)</span><span class="w">
</span><span class="p">}</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>The main difference from is that for certain Sail targets (including
C, SMT, and SystemVerilog) <code>register_index</code> will be compiled as if it
were <code>bits(5)</code> directly.</p>
</div>
<div class="paragraph">
<p>The purpose of the <code>newtype</code> construct is to create an alias for an
existing type which is distinct from the perspective of the type
system&#8201;&#8212;&#8201;We cannot accidentally pass any <code>bits(5)</code> where a
<code>register_index</code> index is required, as register indices must have been
explicitly constructed using <code>Mk_index</code>. This means that using
<code>newtypes</code> can increase type-safety and therefore prevent errors,
unlike regular type synonyms which we discuss below.</p>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_type_synonyms">Type synonyms</h3>
<div class="paragraph">
<p>We have now described all the various types available in Sail.
However, in order to create more descriptive and self-documenting
specifications, we might want to give types new names that better
inform the reader of the intent behind the types. We can do this using
<em>type synonyms</em>, which are created with the <code>type</code> keyword.</p>
</div>
<div class="paragraph">
<p>For example, if we have an architecture with 32 general purpose
registers, we might want to index them using a 5-bit type. Rather than
using <code>bits(5)</code> directly, we create a synonym:</p>
</div>
<div id="type_syn-type-regbits" class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="k">type</span><span class="w"> </span><span class="n">regbits</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="kt">bits</span><span class="p">(</span><span class="mi">5</span><span class="p">)</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>We can now write functions that use this type:</p>
</div>
<div id="type_syn-span-EX_REGBITS" class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="k">register</span><span class="w"> </span><span class="n">R1</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="kt">bits</span><span class="p">(</span><span class="mi">32</span><span class="p">)</span><span class="w">
</span><span class="k">register</span><span class="w"> </span><span class="n">R2</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="kt">bits</span><span class="p">(</span><span class="mi">32</span><span class="p">)</span><span class="w">

</span><span class="k">function</span><span class="w"> </span><span class="nf">access_register</span><span class="p">(</span><span class="n">r</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="n">regbits</span><span class="p">)</span><span class="w"> </span><span class="p">-&gt;</span><span class="w"> </span><span class="kt">bits</span><span class="p">(</span><span class="mi">32</span><span class="p">)</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">{</span><span class="w">
  </span><span class="k">match</span><span class="w"> </span><span class="n">r</span><span class="w"> </span><span class="p">{</span><span class="w">
     </span><span class="mb">0b00000</span><span class="w"> </span><span class="p">=</span><span class="o">&gt;</span><span class="w"> </span><span class="mh">0x0000_0000</span><span class="p">,</span><span class="w"> </span><span class="c">// zero register</span><span class="w">
     </span><span class="mb">0b00001</span><span class="w"> </span><span class="p">=</span><span class="o">&gt;</span><span class="w"> </span><span class="n">R1</span><span class="p">,</span><span class="w">
     </span><span class="mb">0b00010</span><span class="w"> </span><span class="p">=</span><span class="o">&gt;</span><span class="w"> </span><span class="n">R2</span><span class="p">,</span><span class="w">
     </span><span class="c">// and so on</span><span class="w">
  </span><span class="p">}</span><span class="w">
</span><span class="p">}</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>Sail types also include numbers, as in <code>bits(32)</code> above. We can
therefore write a type synonym for just such a number:</p>
</div>
<div id="type_syn_xlen-type-xlen" class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="k">type</span><span class="w"> </span><span class="n">xlen</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="mi">32</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>In which case, we could re-write our example as</p>
</div>
<div id="type_syn_xlen-span-EX_REGBITS" class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="k">register</span><span class="w"> </span><span class="n">R1</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="kt">bits</span><span class="p">(</span><span class="n">xlen</span><span class="p">)</span><span class="w">
</span><span class="k">register</span><span class="w"> </span><span class="n">R2</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="kt">bits</span><span class="p">(</span><span class="n">xlen</span><span class="p">)</span><span class="w">

</span><span class="k">function</span><span class="w"> </span><span class="nf">access_register</span><span class="p">(</span><span class="n">r</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="n">regbits</span><span class="p">)</span><span class="w"> </span><span class="p">-&gt;</span><span class="w"> </span><span class="kt">bits</span><span class="p">(</span><span class="n">xlen</span><span class="p">)</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">{</span><span class="w">
  </span><span class="k">match</span><span class="w"> </span><span class="n">r</span><span class="w"> </span><span class="p">{</span><span class="w">
     </span><span class="mb">0b00000</span><span class="w"> </span><span class="p">=</span><span class="o">&gt;</span><span class="w"> </span><span class="mh">0x0000_0000</span><span class="p">,</span><span class="w"> </span><span class="c">// zero register</span><span class="w">
     </span><span class="mb">0b00001</span><span class="w"> </span><span class="p">=</span><span class="o">&gt;</span><span class="w"> </span><span class="n">R1</span><span class="p">,</span><span class="w">
     </span><span class="mb">0b00010</span><span class="w"> </span><span class="p">=</span><span class="o">&gt;</span><span class="w"> </span><span class="n">R2</span><span class="p">,</span><span class="w">
     </span><span class="c">// and so on</span><span class="w">
  </span><span class="p">}</span><span class="w">
</span><span class="p">}</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>Type synonyms are completely transparent to the Sail type-checker, so
a type synonym can be used exactly the same as the original type.</p>
</div>
<div class="paragraph">
<p>We can also write type-synonyms that have arguments, for example:</p>
</div>
<div id="type_syn-type-square" class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="k">type</span><span class="w"> </span><span class="n">square</span><span class="p">(</span><span class="nv">'n</span><span class="p">,</span><span class="w"> </span><span class="nv">'a</span><span class="p">)</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">vector</span><span class="p">(</span><span class="nv">'n</span><span class="p">,</span><span class="w"> </span><span class="n">vector</span><span class="p">(</span><span class="nv">'n</span><span class="p">,</span><span class="w"> </span><span class="nv">'a</span><span class="p">))</span></code></pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_type_kinds">Type kinds</h3>
<div class="paragraph">
<p>Throughout the previous section we have seen many different types. For
example we could have a type like <code>list(int)</code>, or a type like
<code>range(2, 5)</code>. The <code>range</code> type takes two numbers as an arguments,
whereas list takes a type as an argument. We&#8217;ve also seen polymorphic
user-defined types like:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="w">
</span><span class="k">struct</span><span class="w"> </span><span class="n">foo</span><span class="p">(</span><span class="nv">'n</span><span class="p">,</span><span class="w"> </span><span class="nv">'a</span><span class="p">)</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">{</span><span class="w">
  </span><span class="n">some_bits</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="kt">bits</span><span class="p">(</span><span class="nv">'n</span><span class="p">),</span><span class="w">
  </span><span class="n">some_a</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="nv">'a</span><span class="p">,</span><span class="w">
</span><span class="p">}</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>Which we could use as the type <code>foo(32, string)</code>, or <code>foo(16, int)</code>.
What stops us from writing <code>foo(string, int)</code> or even <code>range(int,
int)</code> or <code>list(3)</code> however? Those should clearly be type errors, and
if they are type errors <em>does that mean types have types</em>? The answer
to this is yes, and we call the types of types <em>kinds</em>. Sail has three
different kinds of types, which we denote as <code>Int</code>, <code>Bool</code>, and
<code>Type</code>. The <code>Int</code> kind is for type-level integers, <code>Bool</code> is for
type-level (boolean) constraints, and <code>Type</code> is for ordinary types.
Type constructors therefore have types much like functions, with
<code>list</code> having the type <code>Type &#8594; Type</code> and <code>range</code> having the type
<code>(Int, Int) &#8594; Type</code>.</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">
From a type-theory perspective, one really can think of type
constructors as just functions at the type level. As functions are
applied to terms, type constructors are applied to types. This is
partly why we use parentheses for type constructor application in Sail&#8201;&#8212;&#8201;not only does it neatly sidestep the notoriously thorny parsing
problems of <code>&lt;</code> and <code>&gt;</code> in types (see Rust&#8217;s
<a href="https://github.com/rust-lang/rust/blob/master/tests/ui/parser/bastion-of-the-turbofish.rs">infamous turbofish operator</a>, or requiring extra spaces in C++ templates to
avoid ambiguities with <code>&gt;&gt;</code>), but it really is the same concept when
viewed in the right way.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>Sail allows writing the kinds explicitly in type definitions, so we
could write:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="k">struct</span><span class="w"> </span><span class="n">foo</span><span class="p">(</span><span class="nv">'n</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="kt">Int</span><span class="p">,</span><span class="w"> </span><span class="nv">'a</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="kt">Type</span><span class="p">)</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">{</span><span class="w">
  </span><span class="n">some_bits</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="kt">bits</span><span class="p">(</span><span class="nv">'n</span><span class="p">),</span><span class="w">
  </span><span class="n">some_a</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="nv">'a</span><span class="p">,</span><span class="w">
</span><span class="p">}</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>but in practice we don&#8217;t need to do this, as Sail has kind-inference
to avoid us having to think about this particular detail.</p>
</div>
</div>
<div class="sect2">
<h3 id="_abstract_types">Abstract types</h3>
<div class="paragraph">
<p>Consider the following problem: We want to specify an architecture
like RISC-V, which permits both 32-bit and a 64-bit implementations,
with the two implementations being mostly the same other than the base
ISA width (called XLEN in RISC-V).</p>
</div>
<div class="paragraph">
<p>In Sail, we could write something like:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="cp">$ifdef RV32</span><span class="w">
</span><span class="k">type</span><span class="w"> </span><span class="n">xlen</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="mi">32</span><span class="w">
</span><span class="cp">$else</span><span class="w">
</span><span class="k">type</span><span class="w"> </span><span class="n">xlen</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="mi">64</span><span class="w">
</span><span class="cp">$endif</span><span class="w">

</span><span class="k">register</span><span class="w"> </span><span class="n">X1</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="kt">bits</span><span class="p">(</span><span class="n">xlen</span><span class="p">)</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>However, this has the problem that if we write a function like:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="k">function</span><span class="w"> </span><span class="nf">rv32_only</span><span class="p">()</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">{</span><span class="w">
    </span><span class="n">X1</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="mh">0xFFFF_FFFF</span><span class="w">
</span><span class="p">}</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>it will typecheck and build fine only when <code>RV32</code> is defined, but will
fail otherwise when <code>xlen = 64</code>.</p>
</div>
<div class="paragraph">
<p>What we really want is to write a specification that is truely
<em>parametric</em> over the choice of <code>xlen</code>. In Sail we can do this by
leaving the <code>xlen</code> type <em>abstract</em>, which means we do not provide a
concrete value for it during type-checking. This would look like:</p>
</div>
<div id="abstract-ty-span-XLEN" class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="k">type</span><span class="w"> </span><span class="n">xlen</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="kt">Int</span><span class="w">

</span><span class="nb">constraint</span><span class="w"> </span><span class="n">xlen</span><span class="w"> </span><span class="k">in</span><span class="w"> </span><span class="p">{</span><span class="mi">32</span><span class="p">,</span><span class="w"> </span><span class="mi">64</span><span class="p">}</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>If we then try to write the above <code>rv32_only</code> function, we will get an error</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code>Type error:
../examples/abstract_error.sail:4.9-20:
4 |    X1 = 0xFFFF_FFFF
  |         ^---------^
  | Failed to prove constraint: 32 == xlen
  | 
  | constraint from ../examples/abstract_xlen.sail:10.19-23:
  | 10 |register X1 : bits(xlen)
  |    |                   ^--^ This type argument</code></pre>
</div>
</div>
<div class="paragraph">
<p>as <code>xlen</code> is not guaranteed to be 32.</p>
</div>
<div class="paragraph">
<p>Not all Sail targets support abstract types, so for some targets the
abstract types must be instantiated to concrete values before
generating definitions. We do this using the <code>--instantiate</code> option,
so if the above file is called <code>xlen.sail</code>, we could do:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sh">sail xlen.sail <span class="nt">--lem</span> <span class="nt">--instantiate</span> <span class="nv">xlen</span><span class="o">=</span>32</code></pre>
</div>
</div>
<div class="paragraph">
<p>To create lem definitions for the <code>xlen = 32</code> case.</p>
</div>
</div>
<div class="sect2">
<h3 id="_pattern_matching">Pattern matching</h3>
<div class="paragraph">
<p>Like most functional languages, and an increasing number of imperative
languages like Rust, Sail supports <em>pattern matching</em> via the <code>match</code>
keyword. For example:</p>
</div>
<div id="pattern-match-example" class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="k">let</span><span class="w"> </span><span class="n">n</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="kt">int</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">f</span><span class="p">();</span><span class="w">
</span><span class="k">match</span><span class="w"> </span><span class="n">n</span><span class="w"> </span><span class="p">{</span><span class="w">
    </span><span class="mi">1</span><span class="w"> </span><span class="p">=</span><span class="o">&gt;</span><span class="w"> </span><span class="n">print_endline</span><span class="p">(</span><span class="s">"1"</span><span class="p">),</span><span class="w">
    </span><span class="mi">2</span><span class="w"> </span><span class="p">=</span><span class="o">&gt;</span><span class="w"> </span><span class="n">print_endline</span><span class="p">(</span><span class="s">"2"</span><span class="p">),</span><span class="w">
    </span><span class="mi">3</span><span class="w"> </span><span class="p">=</span><span class="o">&gt;</span><span class="w"> </span><span class="n">print_endline</span><span class="p">(</span><span class="s">"3"</span><span class="p">),</span><span class="w">
    </span><span class="mi">_</span><span class="w"> </span><span class="p">=</span><span class="o">&gt;</span><span class="w"> </span><span class="n">print_endline</span><span class="p">(</span><span class="s">"wildcard"</span><span class="p">),</span><span class="w">
</span><span class="p">}</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>The <code>match</code> keyword takes an expression and then branches by comparing
the matched value with a <em>pattern</em>. Each case in the match expression
takes the form <code>&lt;pattern&gt; =&gt; &lt;expression&gt;</code>, separated by commas (a
trailing comma is allowed). The cases are checked sequentially from
top to bottom, and when the first pattern matches its expression will
be evaluated.</p>
</div>
<div class="paragraph">
<p>The concrete match statement syntax in Sail is inspired by the syntax
used in Rust&#8201;&#8212;&#8201;but programmers coming from languages with no pattern
matching features may be unfamiliar with the concept. One can think of
the match statement like a super-powered switch statement in C. At its
most basic level a match statement can function like a switch
statement (except without any fall-through). As in the above example we
can use match to compare an expression against a sequence of values
like so:</p>
</div>
<div id="pattern-match-match_switch" class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="k">match</span><span class="w"> </span><span class="n">expression</span><span class="w"> </span><span class="p">{</span><span class="w">
    </span><span class="mi">1</span><span class="w"> </span><span class="p">=</span><span class="o">&gt;</span><span class="w"> </span><span class="n">print_endline</span><span class="p">(</span><span class="s">"expression == 1"</span><span class="p">),</span><span class="w">
    </span><span class="mi">2</span><span class="w"> </span><span class="p">=</span><span class="o">&gt;</span><span class="w"> </span><span class="p">{</span><span class="w">
        </span><span class="c">// A match arm can have a single expression or a block</span><span class="w">
        </span><span class="c">// (because blocks in Sail are also expressions!)</span><span class="w">
        </span><span class="n">print_endline</span><span class="p">(</span><span class="s">"expression == 2"</span><span class="p">)</span><span class="w">
        </span><span class="c">// Note that unlike in C, no 'break' is needed as there is no fallthrough</span><span class="w">
    </span><span class="p">},</span><span class="w">
    </span><span class="mi">_</span><span class="w"> </span><span class="p">=</span><span class="o">&gt;</span><span class="w"> </span><span class="n">print_endline</span><span class="p">(</span><span class="s">"This wildcard pattern acts like default: in a C switch"</span><span class="p">)</span><span class="w">
</span><span class="p">}</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>However the pattern in a match statement can also <em>bind</em> variables. In
the following example we match on a numeric expression <code>x + y</code>, and if
it is equal to <code>1</code> we execute the first match arm. However, if that is
not the case the value of <code>x + y</code> is bound to a new immutable variable
<code>z</code>.</p>
</div>
<div id="pattern-match-match_bind" class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="k">match</span><span class="w"> </span><span class="n">x</span><span class="w"> </span><span class="o">+</span><span class="w"> </span><span class="n">y</span><span class="w"> </span><span class="p">{</span><span class="w">
    </span><span class="mi">1</span><span class="w"> </span><span class="p">=</span><span class="o">&gt;</span><span class="w"> </span><span class="n">print_endline</span><span class="p">(</span><span class="s">"x + y == 1"</span><span class="p">),</span><span class="w">
    </span><span class="n">z</span><span class="w"> </span><span class="p">=</span><span class="o">&gt;</span><span class="w"> </span><span class="p">{</span><span class="w">
        </span><span class="c">// here z is a new variable defined as x + y.</span><span class="w">
        </span><span class="n">print_int</span><span class="p">(</span><span class="s">"x + y = "</span><span class="p">,</span><span class="w"> </span><span class="n">z</span><span class="p">)</span><span class="w">
        </span><span class="c">// z is only defined within the match arm</span><span class="w">
    </span><span class="p">},</span><span class="w">
</span><span class="p">}</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>Finally, we can use patterns to <em>destructure</em> values&#8201;&#8212;&#8201;breaking them
apart into their constituent parts. For example if we have a pair
expression we can break it apart into the first value in the pair and
the second, which can then be used as individual variables:</p>
</div>
<div id="pattern-match-match_destruct" class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="k">match</span><span class="w"> </span><span class="n">pair</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="p">(</span><span class="kt">int</span><span class="p">,</span><span class="w"> </span><span class="kt">int</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w">
    </span><span class="p">(</span><span class="n">first</span><span class="p">,</span><span class="w"> </span><span class="n">second</span><span class="p">)</span><span class="w"> </span><span class="p">=</span><span class="o">&gt;</span><span class="w"> </span><span class="p">{</span><span class="w">
        </span><span class="c">// here we have split a pair into two variables first and second</span><span class="w">
        </span><span class="n">print_int</span><span class="p">(</span><span class="s">"first = "</span><span class="p">,</span><span class="w"> </span><span class="n">first</span><span class="p">);</span><span class="w">
        </span><span class="n">print_int</span><span class="p">(</span><span class="s">"second = "</span><span class="p">,</span><span class="w"> </span><span class="n">second</span><span class="p">)</span><span class="w">
    </span><span class="p">}</span><span class="w">
</span><span class="p">}</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>These features can be combined, so if we had a pattern <code>(first, 3)</code> in
the above example, the expression for that pattern would be executed
when the second element of the pair is equal to 3, and the first element
would be bound to the variable <code>first</code>.</p>
</div>
<div class="paragraph">
<p>Sail will check match statements for exhaustiveness (meaning that the
patterns in the match cover every possible value), and prints a
warning if the overall match statement is not exhaustive. There are
some limitations on the exhaustiveness checker which we will discuss
further below.</p>
</div>
<div class="sect3">
<h4 id="_guards">Guards</h4>
<div class="paragraph">
<p>What if we need to switch based on more complex logic than just the
structure and values of the expressions we are matching on? For this
matches in Sail support <em>guards</em>. A guard allows us to combine the
behavior of a match expression and the boolean logic of an if
expression&#8201;&#8212;&#8201;and the syntax is reflective of this, as we can use the
<code>if</code> keyword to add extra logic to each match arm:</p>
</div>
<div id="pattern-match-match_guard" class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="k">match</span><span class="w"> </span><span class="n">x</span><span class="w"> </span><span class="o">+</span><span class="w"> </span><span class="n">y</span><span class="w"> </span><span class="p">{</span><span class="w">
    </span><span class="n">z</span><span class="w"> </span><span class="k">if</span><span class="w"> </span><span class="n">z</span><span class="w"> </span><span class="o">&gt;</span><span class="w"> </span><span class="mi">0</span><span class="w">  </span><span class="p">=</span><span class="o">&gt;</span><span class="w"> </span><span class="n">print_endline</span><span class="p">(</span><span class="s">"y is greater than 0"</span><span class="p">),</span><span class="w">
    </span><span class="n">z</span><span class="w"> </span><span class="k">if</span><span class="w"> </span><span class="n">z</span><span class="w"> </span><span class="p">==</span><span class="w"> </span><span class="mi">0</span><span class="w"> </span><span class="p">=</span><span class="o">&gt;</span><span class="w"> </span><span class="n">print_endline</span><span class="p">(</span><span class="s">"z is equal to 0"</span><span class="p">),</span><span class="w">
    </span><span class="n">z</span><span class="w">           </span><span class="p">=</span><span class="o">&gt;</span><span class="w"> </span><span class="n">print_endline</span><span class="p">(</span><span class="s">"z is less than 0"</span><span class="p">),</span><span class="w">
</span><span class="p">}</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>You may wonder&#8201;&#8212;&#8201;why not write <code>z if z &lt; 0</code> for the final case? Here
we run into one of the limitations of the exhaustiveness checker
mentioned above. Sail can only check the exhaustiveness of <em>unguarded</em>
clauses, meaning that the checker only considers cases without an <code>if</code>
guard. The <code>z</code> pattern by itself is exhaustive, so the checker is
happy, but if we added a <code>if z &lt; 0</code> guard the checker would complain
that there are no unguarded patterns for it to look at. This may seem
suprising for such a simple case (we can easily see the three guards
would cover all cases!), however each guard clause could contain
arbitrarily complex logic potentially abstracted behind arbitrary
function calls, which the completeness checker cannot reason about.</p>
</div>
<div class="paragraph">
<p>We now describe all the things that can be matched on in Sail</p>
</div>
</div>
<div class="sect3">
<h4 id="_matching_on_literals">Matching on literals</h4>
<div class="paragraph">
<p>First, and as we have already seen, we can match on literal
values. These literal values can be <code>()</code>, bitvectors, the boolean values
<code>true</code> and <code>false</code>, numbers, and strings.</p>
</div>
</div>
<div class="sect3">
<h4 id="_matching_on_enumerations">Matching on enumerations</h4>
<div class="paragraph">
<p>Match can be used to match on possible values of an enum, like so:</p>
</div>
<div id="pattern-match-match_enum" class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="k">match</span><span class="w"> </span><span class="n">x</span><span class="w"> </span><span class="p">{</span><span class="w">
    </span><span class="n">A</span><span class="w"> </span><span class="p">=</span><span class="o">&gt;</span><span class="w"> </span><span class="n">print_endline</span><span class="p">(</span><span class="s">"A"</span><span class="p">),</span><span class="w">
    </span><span class="n">B</span><span class="w"> </span><span class="p">=</span><span class="o">&gt;</span><span class="w"> </span><span class="n">print_endline</span><span class="p">(</span><span class="s">"B"</span><span class="p">),</span><span class="w">
    </span><span class="n">C</span><span class="w"> </span><span class="p">=</span><span class="o">&gt;</span><span class="w"> </span><span class="n">print_endline</span><span class="p">(</span><span class="s">"C"</span><span class="p">)</span><span class="w">
</span><span class="p">}</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>Note that because Sail places no restrictions on the lexical structure
of enumeration elements to differentiate them from ordinary
identifiers, pattern matches on variables and enum elements can be
somewhat ambiguous. Issues with this are usually caught by the
exhaustiveness checker&#8201;&#8212;&#8201;it can warn you if removing an enum
constructor breaks a pattern match.</p>
</div>
</div>
<div class="sect3">
<h4 id="_matching_on_tuples">Matching on tuples</h4>
<div class="paragraph">
<p>We use match to destructure tuple types, for example:</p>
</div>
<div id="pattern-match-match_tuple" class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="k">let</span><span class="w"> </span><span class="n">x</span><span class="p">:</span><span class="w"> </span><span class="p">(</span><span class="kt">int</span><span class="p">,</span><span class="w"> </span><span class="kt">int</span><span class="p">)</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">(</span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="mi">3</span><span class="p">);</span><span class="w">
</span><span class="k">match</span><span class="w"> </span><span class="n">x</span><span class="w"> </span><span class="p">{</span><span class="w">
    </span><span class="p">(</span><span class="n">y</span><span class="p">,</span><span class="w"> </span><span class="n">z</span><span class="p">)</span><span class="w"> </span><span class="p">=</span><span class="o">&gt;</span><span class="w"> </span><span class="n">print_endline</span><span class="p">(</span><span class="s">"y = 2 and z = 3"</span><span class="p">)</span><span class="w">
</span><span class="p">}</span></code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="_matching_on_unions">Matching on unions</h4>
<div class="paragraph">
<p>Match can also be used to destructure tagged union constructors, for example
using the option type from the Sail library.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="cp">$include &lt;option.sail&gt;</span><span class="w">

</span><span class="k">val</span><span class="w"> </span><span class="nf">g</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="kt">unit</span><span class="w"> </span><span class="p">-&gt;</span><span class="w"> </span><span class="kt">option</span><span class="p">(</span><span class="kt">int</span><span class="p">)</span><span class="w">

</span><span class="k">function</span><span class="w"> </span><span class="nf">match_union</span><span class="p">()</span><span class="w"> </span><span class="p">-&gt;</span><span class="w"> </span><span class="kt">unit</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">{</span><span class="w">
    </span><span class="k">let</span><span class="w"> </span><span class="n">x</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">g</span><span class="p">();</span><span class="w">
    </span><span class="k">match</span><span class="w"> </span><span class="n">x</span><span class="w"> </span><span class="p">{</span><span class="w">
        </span><span class="n">Some</span><span class="p">(</span><span class="n">n</span><span class="p">)</span><span class="w"> </span><span class="p">=</span><span class="o">&gt;</span><span class="w"> </span><span class="n">print_int</span><span class="p">(</span><span class="s">"n = "</span><span class="p">,</span><span class="w"> </span><span class="n">n</span><span class="p">),</span><span class="w">
        </span><span class="n">None</span><span class="p">()</span><span class="w">  </span><span class="p">=</span><span class="o">&gt;</span><span class="w"> </span><span class="n">print_endline</span><span class="p">(</span><span class="s">"got None()!"</span><span class="p">),</span><span class="w">
    </span><span class="p">}</span><span class="w">
</span><span class="p">}</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>Note that like how calling a function with a unit argument can be done
as <code>f()</code> rather than <code>f(())</code>, matching on a constructor <code>C</code> with a
unit type can be achieved by using <code>C()</code> rather than <code>C(())</code>.</p>
</div>
</div>
<div class="sect3">
<h4 id="_matching_on_lists">Matching on lists</h4>
<div class="paragraph">
<p>Sail allows lists to be destructured using patterns. There are two
types of patterns for lists, cons patterns and list literal
patterns. The cons pattern destructures lists into the first element
(the <em>head</em>) and the rest of the list (the <em>tail</em>).</p>
</div>
<div id="pattern-match-match_cons" class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="k">match</span><span class="w"> </span><span class="n">ys</span><span class="w"> </span><span class="p">{</span><span class="w">
    </span><span class="n">x</span><span class="w"> </span><span class="p">::</span><span class="w"> </span><span class="n">xs</span><span class="w"> </span><span class="p">=</span><span class="o">&gt;</span><span class="w"> </span><span class="n">print_endline</span><span class="p">(</span><span class="s">"cons pattern"</span><span class="p">),</span><span class="w">
    </span><span class="p">[||]</span><span class="w">    </span><span class="p">=</span><span class="o">&gt;</span><span class="w"> </span><span class="n">print_endline</span><span class="p">(</span><span class="s">"empty list"</span><span class="p">)</span><span class="w">
</span><span class="p">}</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>On the other hand, a list pattern matches on the entire list:</p>
</div>
<div id="pattern-match-match_list" class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="k">match</span><span class="w"> </span><span class="n">ys</span><span class="w"> </span><span class="p">{</span><span class="w">
    </span><span class="p">[|</span><span class="mi">1</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="mi">3</span><span class="p">|]</span><span class="w"> </span><span class="p">=</span><span class="o">&gt;</span><span class="w"> </span><span class="n">print_endline</span><span class="p">(</span><span class="s">"list pattern"</span><span class="p">),</span><span class="w">
    </span><span class="mi">_</span><span class="w">           </span><span class="p">=</span><span class="o">&gt;</span><span class="w"> </span><span class="n">print_endline</span><span class="p">(</span><span class="s">"wildcard"</span><span class="p">)</span><span class="w">
</span><span class="p">}</span></code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="_matching_on_structs">Matching on structs</h4>
<div class="paragraph">
<p>Match can also be used for structures, for example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="k">struct</span><span class="w"> </span><span class="n">my_struct</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">{</span><span class="w">
    </span><span class="n">field1</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="kt">bits</span><span class="p">(</span><span class="mi">16</span><span class="p">),</span><span class="w">
    </span><span class="n">field2</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="kt">int</span><span class="p">,</span><span class="w">
</span><span class="p">}</span><span class="w">

</span><span class="k">function</span><span class="w"> </span><span class="nf">match_struct</span><span class="p">(</span><span class="n">value</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="n">my_struct</span><span class="p">)</span><span class="w"> </span><span class="p">-&gt;</span><span class="w"> </span><span class="kt">unit</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">{</span><span class="w">
    </span><span class="k">match</span><span class="w"> </span><span class="n">value</span><span class="w"> </span><span class="p">{</span><span class="w">
        </span><span class="c">// match against literals in the struct fields</span><span class="w">
        </span><span class="k">struct</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="n">field1</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="mh">0x0000</span><span class="p">,</span><span class="w"> </span><span class="n">field2</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="mi">3</span><span class="w"> </span><span class="p">}</span><span class="w"> </span><span class="p">=</span><span class="o">&gt;</span><span class="w"> </span><span class="p">(),</span><span class="w">

        </span><span class="c">// bind the struct field values to immutable variables</span><span class="w">
        </span><span class="k">struct</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="n">field1</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">x</span><span class="p">,</span><span class="w"> </span><span class="n">field2</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">y</span><span class="w"> </span><span class="p">}</span><span class="w"> </span><span class="p">=</span><span class="o">&gt;</span><span class="w"> </span><span class="p">{</span><span class="w">
            </span><span class="n">print_bits</span><span class="p">(</span><span class="s">"value.field1 = "</span><span class="p">,</span><span class="w"> </span><span class="n">x</span><span class="p">);</span><span class="w">
            </span><span class="n">print_int</span><span class="p">(</span><span class="s">"value.field2 = "</span><span class="p">,</span><span class="w"> </span><span class="n">y</span><span class="p">)</span><span class="w">
        </span><span class="p">}</span><span class="w">
    </span><span class="p">}</span><span class="w">
</span><span class="p">}</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>We can omit fields from the match by using a wildcard <code>_</code> in place of
some of the fields:</p>
</div>
<div id="pattern-match-match_struct2" class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="k">match</span><span class="w"> </span><span class="n">value</span><span class="w"> </span><span class="p">{</span><span class="w">
    </span><span class="k">struct</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="n">field1</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">x</span><span class="p">,</span><span class="w"> </span><span class="mi">_</span><span class="w"> </span><span class="p">}</span><span class="w"> </span><span class="p">=</span><span class="o">&gt;</span><span class="w"> </span><span class="p">{</span><span class="w">
        </span><span class="n">print_bits</span><span class="p">(</span><span class="s">"value.field1 = "</span><span class="p">,</span><span class="w"> </span><span class="n">x</span><span class="p">)</span><span class="w">
    </span><span class="p">}</span><span class="w">
</span><span class="p">}</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>Finally, if we want to create a variable with the same name as a
field, rather than typing <code>struct { field_name = field_name, _ }</code>, we
can shorten this to just <code>struct { field_name, _ }</code>, So the above
example is equivalent to:</p>
</div>
<div id="pattern-match-match_struct3" class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="k">match</span><span class="w"> </span><span class="n">value</span><span class="w"> </span><span class="p">{</span><span class="w">
    </span><span class="k">struct</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="n">field1</span><span class="p">,</span><span class="w"> </span><span class="mi">_</span><span class="w"> </span><span class="p">}</span><span class="w"> </span><span class="p">=</span><span class="o">&gt;</span><span class="w"> </span><span class="p">{</span><span class="w">
        </span><span class="n">print_bits</span><span class="p">(</span><span class="s">"value.field1 = "</span><span class="p">,</span><span class="w"> </span><span class="n">field1</span><span class="p">)</span><span class="w">
    </span><span class="p">}</span><span class="w">
</span><span class="p">}</span></code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="_as_patterns">As patterns</h4>
<div class="paragraph">
<p>Like OCaml, Sail also supports naming parts of patterns using the <code>as</code>
keyword. For example, in the above cons pattern example we could bind the
entire matched list to the <code>zs</code> variable:</p>
</div>
<div id="pattern-match-match_cons_as" class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="k">match</span><span class="w"> </span><span class="p">(</span><span class="mi">1</span><span class="w"> </span><span class="p">::</span><span class="w"> </span><span class="mi">2</span><span class="w"> </span><span class="p">::</span><span class="w"> </span><span class="n">ys</span><span class="p">)</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="n">list</span><span class="p">(</span><span class="kt">int</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w">
    </span><span class="n">x</span><span class="w"> </span><span class="p">::</span><span class="w"> </span><span class="n">xs</span><span class="w"> </span><span class="k">as</span><span class="w"> </span><span class="n">zs</span><span class="w"> </span><span class="p">=</span><span class="o">&gt;</span><span class="w"> </span><span class="n">print_endline</span><span class="p">(</span><span class="s">"cons with as pattern"</span><span class="p">),</span><span class="w">
    </span><span class="p">[||]</span><span class="w">          </span><span class="p">=</span><span class="o">&gt;</span><span class="w"> </span><span class="n">print_endline</span><span class="p">(</span><span class="s">"empty list"</span><span class="p">),</span><span class="w">
</span><span class="p">}</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>The <code>as</code> pattern has lower precedence than any other keyword or
operator in a pattern, so in this example the pattern brackets as
<code>(x :: xs) as zs</code></p>
</div>
</div>
<div class="sect3">
<h4 id="_automatic_wildcard_insertion">Automatic wildcard insertion</h4>
<div class="paragraph">
<p>The various theorem provers that Sail can produce definitions for are
often strict, and enforce that pattern matches are exhaustive.
However, their pattern exhaustiveness checkers do not understand
bitvectors in the same way Sail does. For example, Sail can tell that
the following match is complete:</p>
</div>
<div id="pattern-match-match_wildcard_remove" class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="k">match</span><span class="w"> </span><span class="p">(</span><span class="n">x</span><span class="p">,</span><span class="w"> </span><span class="n">y</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w">
    </span><span class="p">(</span><span class="mb">0b1</span><span class="p">,</span><span class="w"> </span><span class="mi">_</span><span class="p">)</span><span class="w">   </span><span class="p">=</span><span class="o">&gt;</span><span class="w"> </span><span class="n">print_endline</span><span class="p">(</span><span class="s">"1"</span><span class="p">),</span><span class="w">
    </span><span class="p">(</span><span class="mi">_</span><span class="p">,</span><span class="w"> </span><span class="mb">0b0</span><span class="p">)</span><span class="w">   </span><span class="p">=</span><span class="o">&gt;</span><span class="w"> </span><span class="n">print_endline</span><span class="p">(</span><span class="s">"2"</span><span class="p">),</span><span class="w">
    </span><span class="p">(</span><span class="mb">0b0</span><span class="p">,</span><span class="w"> </span><span class="mb">0b1</span><span class="p">)</span><span class="w"> </span><span class="p">=</span><span class="o">&gt;</span><span class="w"> </span><span class="n">print_endline</span><span class="p">(</span><span class="s">"3"</span><span class="p">),</span><span class="w">
</span><span class="p">}</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>When translating to a target without bitvector literals, this would be
rewritten to use guards:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="k">match</span><span class="w"> </span><span class="p">(</span><span class="n">x</span><span class="p">,</span><span class="w"> </span><span class="n">y</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w">
    </span><span class="p">(</span><span class="n">t1</span><span class="p">,</span><span class="w"> </span><span class="mi">_</span><span class="p">)</span><span class="w"> </span><span class="k">if</span><span class="w"> </span><span class="n">t1</span><span class="w"> </span><span class="p">==</span><span class="w"> </span><span class="mb">0b1</span><span class="w"> </span><span class="p">=</span><span class="o">&gt;</span><span class="w"> </span><span class="n">print_endline</span><span class="p">(</span><span class="s">"1"</span><span class="p">),</span><span class="w">
    </span><span class="p">(</span><span class="mi">_</span><span class="p">,</span><span class="w"> </span><span class="n">t2</span><span class="p">)</span><span class="w"> </span><span class="k">if</span><span class="w"> </span><span class="n">t2</span><span class="w"> </span><span class="p">==</span><span class="w"> </span><span class="mb">0b0</span><span class="w"> </span><span class="p">=</span><span class="o">&gt;</span><span class="w"> </span><span class="n">print_endline</span><span class="p">(</span><span class="s">"2"</span><span class="p">),</span><span class="w">
    </span><span class="p">(</span><span class="n">t1</span><span class="p">,</span><span class="w"> </span><span class="n">t2</span><span class="p">)</span><span class="w"> </span><span class="k">if</span><span class="w"> </span><span class="n">t1</span><span class="w"> </span><span class="p">==</span><span class="w"> </span><span class="mb">0b0</span><span class="w"> </span><span class="o">&amp;</span><span class="w"> </span><span class="n">t2</span><span class="w"> </span><span class="p">==</span><span class="w"> </span><span class="mb">0b1</span><span class="w"> </span><span class="p">=</span><span class="o">&gt;</span><span class="w"> </span><span class="n">print_endline</span><span class="p">(</span><span class="s">"3"</span><span class="p">),</span><span class="w">
</span><span class="p">}</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>Most targets that check pattern exhaustiveness share the same limitation
as Sail&#8201;&#8212;&#8201;they only check match arms without guards, so they
would not see that this match is complete. To avoid this, Sail will
attempt to replace literal patterns with wildcards when possible, so
the above will be rewritten to:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="k">match</span><span class="w"> </span><span class="p">(</span><span class="n">x</span><span class="p">,</span><span class="w"> </span><span class="n">y</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w">
    </span><span class="p">(</span><span class="mb">0b1</span><span class="p">,</span><span class="w"> </span><span class="mi">_</span><span class="p">)</span><span class="w"> </span><span class="p">=</span><span class="o">&gt;</span><span class="w"> </span><span class="n">print_endline</span><span class="p">(</span><span class="s">"1"</span><span class="p">),</span><span class="w">
    </span><span class="p">(</span><span class="mi">_</span><span class="p">,</span><span class="w"> </span><span class="mb">0b0</span><span class="p">)</span><span class="w"> </span><span class="p">=</span><span class="o">&gt;</span><span class="w"> </span><span class="n">print_endline</span><span class="p">(</span><span class="s">"2"</span><span class="p">),</span><span class="w">
    </span><span class="p">(</span><span class="mi">_</span><span class="p">,</span><span class="w"> </span><span class="mi">_</span><span class="p">)</span><span class="w">   </span><span class="p">=</span><span class="o">&gt;</span><span class="w"> </span><span class="n">print_endline</span><span class="p">(</span><span class="s">"3"</span><span class="p">),</span><span class="w">
</span><span class="p">}</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>which is equivalent.</p>
</div>
<div class="paragraph">
<p>One can find situations where such wildcards cannot be inserted. For example:</p>
</div>
<div id="cannot-wildcard-cannot_wildcard" class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="k">function</span><span class="w"> </span><span class="nf">cannot_wildcard</span><span class="p">(</span><span class="n">x</span><span class="p">:</span><span class="w"> </span><span class="kt">option</span><span class="p">(</span><span class="kt">bits</span><span class="p">(</span><span class="mi">1</span><span class="p">)),</span><span class="w"> </span><span class="n">y</span><span class="p">:</span><span class="w"> </span><span class="kt">option</span><span class="p">(</span><span class="kt">bits</span><span class="p">(</span><span class="mi">1</span><span class="p">)))</span><span class="w"> </span><span class="p">-&gt;</span><span class="w"> </span><span class="kt">unit</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">{</span><span class="w">
    </span><span class="k">match</span><span class="w"> </span><span class="p">(</span><span class="n">x</span><span class="p">,</span><span class="w"> </span><span class="n">y</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w">
        </span><span class="p">(</span><span class="n">Some</span><span class="p">(</span><span class="mb">0b0</span><span class="p">),</span><span class="w"> </span><span class="n">Some</span><span class="p">(</span><span class="mi">_</span><span class="p">))</span><span class="w">   </span><span class="p">=</span><span class="o">&gt;</span><span class="w"> </span><span class="n">print_endline</span><span class="p">(</span><span class="s">"1"</span><span class="p">),</span><span class="w">
        </span><span class="p">(</span><span class="n">Some</span><span class="p">(</span><span class="mb">0b1</span><span class="p">),</span><span class="w"> </span><span class="n">Some</span><span class="p">(</span><span class="mb">0b0</span><span class="p">))</span><span class="w"> </span><span class="p">=</span><span class="o">&gt;</span><span class="w"> </span><span class="n">print_endline</span><span class="p">(</span><span class="s">"2"</span><span class="p">),</span><span class="w">
        </span><span class="p">(</span><span class="n">Some</span><span class="p">(</span><span class="mb">0b1</span><span class="p">),</span><span class="w"> </span><span class="mi">_</span><span class="p">)</span><span class="w">         </span><span class="p">=</span><span class="o">&gt;</span><span class="w"> </span><span class="n">print_endline</span><span class="p">(</span><span class="s">"3"</span><span class="p">),</span><span class="w">
        </span><span class="p">(</span><span class="n">Some</span><span class="p">(</span><span class="mb">0b0</span><span class="p">),</span><span class="w"> </span><span class="n">None</span><span class="p">())</span><span class="w">    </span><span class="p">=</span><span class="o">&gt;</span><span class="w"> </span><span class="n">print_endline</span><span class="p">(</span><span class="s">"4"</span><span class="p">),</span><span class="w">
        </span><span class="p">(</span><span class="n">None</span><span class="p">(),</span><span class="w"> </span><span class="mi">_</span><span class="p">)</span><span class="w">            </span><span class="p">=</span><span class="o">&gt;</span><span class="w"> </span><span class="n">print_endline</span><span class="p">(</span><span class="s">"5"</span><span class="p">),</span><span class="w">
    </span><span class="p">}</span><span class="w">
</span><span class="p">}</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>Here the <code>0b1</code> literal in the <code>(Some(0b1), _)</code> case would need to be
replaced for an exhaustiveness checker without bitvector literals to
check the case where <code>x</code> and <code>y</code> are both <code>Some</code>, but this would
change the behavior when <code>x</code> is <code>Some</code> and <code>y</code> is <code>None</code>, hence a
wildcard cannot be inserted.</p>
</div>
<div class="paragraph">
<p>In this case Sail will print a warning explaining the problem:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code>Warning: Required literal ../examples/cannot_wildcard.sail:17.14-17:
17 |        (Some(0b1), _)         =&gt; print_endline("3"),
   |              ^-^
   | 
Sail cannot simplify the above pattern match:
This bitvector pattern literal must be kept, as it is required for Sail to show that the surrounding pattern match is complete.
When translated into prover targets (e.g. Lem, Coq) without native bitvector patterns, they may be unable to verify that the match covers all possible cases.</code></pre>
</div>
</div>
<div class="paragraph">
<p>This warning should be heeded, and the match simplified otherwise the
generated theorem prover definitions produced by Sail may be rejected
by the prover.</p>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_matching_in_let_and_function_arguments">Matching in let and function arguments</h3>
<div class="paragraph">
<p>The <code>match</code> statement isn&#8217;t the only place we can use patterns. We can
also use patterns in function arguments and with <code>let</code>, for example:</p>
</div>
<div id="funpat-span-EXAMPLE" class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="k">struct</span><span class="w"> </span><span class="n">S</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">{</span><span class="w">
    </span><span class="n">field1</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="kt">int</span><span class="p">,</span><span class="w">
    </span><span class="n">field2</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="n">string</span><span class="p">,</span><span class="w">
</span><span class="p">}</span><span class="w">

</span><span class="k">function</span><span class="w"> </span><span class="nf">example1</span><span class="p">(</span><span class="n">s</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="n">S</span><span class="p">)</span><span class="w"> </span><span class="p">-&gt;</span><span class="w"> </span><span class="kt">unit</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">{</span><span class="w">
    </span><span class="c">// Destructure 's' using let</span><span class="w">
    </span><span class="k">let</span><span class="w"> </span><span class="k">struct</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="n">field1</span><span class="p">,</span><span class="w"> </span><span class="mi">_</span><span class="w"> </span><span class="p">}</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">s</span><span class="p">;</span><span class="w">
    </span><span class="n">print_int</span><span class="p">(</span><span class="s">"field1 = "</span><span class="p">,</span><span class="w"> </span><span class="n">field1</span><span class="p">)</span><span class="w">
</span><span class="p">}</span><span class="w">

</span><span class="c">// Destructure directly in the function argument</span><span class="w">
</span><span class="k">function</span><span class="w"> </span><span class="nf">example2</span><span class="p">(</span><span class="k">struct</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="n">field1</span><span class="p">,</span><span class="w"> </span><span class="mi">_</span><span class="w"> </span><span class="p">}</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="n">S</span><span class="p">)</span><span class="w"> </span><span class="p">-&gt;</span><span class="w"> </span><span class="kt">unit</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">{</span><span class="w">
    </span><span class="n">print_int</span><span class="p">(</span><span class="s">"field1 = "</span><span class="p">,</span><span class="w"> </span><span class="n">field1</span><span class="p">)</span><span class="w">
</span><span class="p">}</span></code></pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_type_patterns">Type patterns</h3>
<div class="paragraph">
<p>In the previous section we saw as patterns, which allowed us bind
additional variables for subpatterns. However, as patterns can also be
used to bind type variables. For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="c">// Some function that returns either 32 or 64 at runtime</span><span class="w">
</span><span class="k">val</span><span class="w"> </span><span class="nf">get_current_xlen</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="kt">unit</span><span class="w"> </span><span class="p">-&gt;</span><span class="w"> </span><span class="p">{</span><span class="mi">32</span><span class="p">,</span><span class="w"> </span><span class="mi">64</span><span class="p">}</span><span class="w">

</span><span class="k">register</span><span class="w"> </span><span class="n">R</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="kt">bits</span><span class="p">(</span><span class="mi">32</span><span class="p">)</span><span class="w">

</span><span class="k">val</span><span class="w"> </span><span class="nf">example</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="kt">unit</span><span class="w"> </span><span class="p">-&gt;</span><span class="w"> </span><span class="kt">unit</span><span class="w">

</span><span class="k">function</span><span class="w"> </span><span class="nf">example</span><span class="p">()</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">{</span><span class="w">
  </span><span class="k">let</span><span class="w"> </span><span class="n">xlen</span><span class="w"> </span><span class="k">as</span><span class="w"> </span><span class="kt">int</span><span class="p">(</span><span class="nv">'n</span><span class="p">)</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">get_current_xlen</span><span class="p">()</span><span class="w">

  </span><span class="c">// Create a bitvector of length xlen</span><span class="w">
  </span><span class="k">let</span><span class="w"> </span><span class="n">bv</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="kt">bits</span><span class="p">(</span><span class="nv">'n</span><span class="p">)</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">zero_extend</span><span class="p">(</span><span class="n">xlen</span><span class="p">,</span><span class="w"> </span><span class="o">*</span><span class="n">R</span><span class="p">);</span><span class="w">

  </span><span class="n">print_bits</span><span class="p">(</span><span class="s">"bv = "</span><span class="p">,</span><span class="w"> </span><span class="n">bv</span><span class="p">)</span><span class="w">
</span><span class="p">}</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>You can think of the <code>as int('n)</code> as matching on the return type of
the <code>get_current_xlen</code> rather than the value, and binding its length
to a new type variable <code>'n</code>, which we can subsequently use in types
later in our function. Note that even though we only know if xlen will
be 32 or 64 at runtime after the call to get_current_xlen, Sail is
still able to statically check all our bitvector accesses.</p>
</div>
<div class="paragraph">
<p>If a type only contains a single type variable (as <code>int('n)</code> does),
then we allow omitting the type name and just using a variable as the
type pattern, for example the following would be equivalent to the
first line of example above:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="k">let</span><span class="w"> </span><span class="n">xlen</span><span class="w"> </span><span class="k">as</span><span class="w"> </span><span class="nv">'n</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">get_current_xlen</span><span class="p">();</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>If we want to give the variable <code>xlen</code> and the type variable <code>'n</code> the
same name, we could go further and simplify to:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="k">function</span><span class="w"> </span><span class="nf">example</span><span class="p">()</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">{</span><span class="w">
  </span><span class="k">let</span><span class="w"> </span><span class="nv">'xlen</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">get_current_xlen</span><span class="p">()</span><span class="w">

  </span><span class="c">// Create a bitvector of length xlen</span><span class="w">
  </span><span class="k">let</span><span class="w"> </span><span class="n">bv</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="kt">bits</span><span class="p">(</span><span class="nv">'xlen</span><span class="p">)</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">zero_extend</span><span class="p">(</span><span class="n">xlen</span><span class="p">,</span><span class="w"> </span><span class="o">*</span><span class="n">R</span><span class="p">);</span><span class="w">

  </span><span class="n">print_bits</span><span class="p">(</span><span class="s">"bv = "</span><span class="p">,</span><span class="w"> </span><span class="n">bv</span><span class="p">)</span><span class="w">
</span><span class="p">}</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>Here we can use xlen within the function as both a regular variable
<code>xlen</code> and as a type variable <code>'xlen</code>.</p>
</div>
</div>
<div class="sect2">
<h3 id="_mutable_variables">Mutable variables</h3>
<div class="paragraph">
<p>Bindings made using <code>let</code> are always immutable, but Sail also allows
mutable variables. Mutable variables are created by using the <code>var</code>
keyword within a block.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="p">{</span><span class="w">
  </span><span class="k">var</span><span class="w"> </span><span class="n">x</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="kt">int</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="mi">3</span><span class="p">;</span><span class="w"> </span><span class="c">// Create a new mutable variable x initialised to 3</span><span class="w">
  </span><span class="n">x</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="mi">2</span><span class="w">            </span><span class="c">// Rebind it to the value 2</span><span class="w">
</span><span class="p">}</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>Like let-bound variables, mutable variables are lexically scoped, so
they only exist within the block that declared them.</p>
</div>
<div class="paragraph">
<p>Technically, unless the <code>--strict-var</code> option is used Sail also allows
mutable variables to be implicitly declared, like so:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="p">{</span><span class="w">
  </span><span class="n">x</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="kt">int</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="mi">3</span><span class="w"> </span><span class="c">// Create a new mutable variable x initialised to 3</span><span class="w">
  </span><span class="n">x</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="mi">2</span><span class="w">       </span><span class="c">// Rebind it to the value 2</span><span class="w">
</span><span class="p">}</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>This functions identically, just without the keyword. We consider this
deprecated and strongly encourage the use of the <code>var</code> keyword going
forwards.</p>
</div>
<div class="paragraph">
<p>The assignment operator is the equality symbol, as in C and other
programming languages. Sail supports a rich language of <em>l-value</em>
forms, which can appear on the left of an assignment. These will be
described in the next section.</p>
</div>
<div class="paragraph">
<p>One important thing to note is that Sail always infers the most
specific type it can for variables, and in the presence of integer
types with constraints, these types can be <em>very</em> specific. This is
not a problem for immutable bindings, but can cause issues for mutable
variables when explicit types are omitted. The following will not
typecheck:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="p">{</span><span class="w">
  </span><span class="k">var</span><span class="w"> </span><span class="n">x</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="mi">3</span><span class="p">;</span><span class="w">
  </span><span class="n">x</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="mi">2</span><span class="p">;</span><span class="w">
</span><span class="p">}</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>The reason is that Sail (correctly) infers that <code>x</code> has the type 'the
integer equal to 3', and therefore refuses to allow us to assign <code>2</code>
to it (as it well should), because two is not equal to three. To avoid
this we must give an annotation with a less specific type like <code>int</code>.</p>
</div>
</div>
<div class="sect2">
<h3 id="_assignment_and_l_values">Assignment and l-values</h3>
<div class="paragraph">
<p>It is common in ISA specifications to assign to complex l-values,
e.g.&#160;to a subvector or named field of a bitvector register, or to
an l-value computed with some auxiliary function, e.g.&#160;to select
the appropriate register for the current execution model.</p>
</div>
<div class="paragraph">
<p>Sail has l-values that allow writing to individual elements of a
(bit)vector:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="k">var</span><span class="w"> </span><span class="n">v</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="kt">bits</span><span class="p">(</span><span class="mi">8</span><span class="p">)</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="mh">0xFF</span><span class="p">;</span><span class="w">
</span><span class="n">v</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="nb">bitzero</span><span class="p">;</span><span class="w">
</span><span class="n">assert</span><span class="p">(</span><span class="n">v</span><span class="w"> </span><span class="p">==</span><span class="w"> </span><span class="mh">0xFE</span><span class="p">)</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>As well as sub-ranges of a (bit)vector:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="k">var</span><span class="w"> </span><span class="n">v</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="kt">bits</span><span class="p">(</span><span class="mi">8</span><span class="p">)</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="mh">0xFF</span><span class="p">;</span><span class="w">
</span><span class="n">v</span><span class="p">[</span><span class="mi">3</span><span class="w"> </span><span class="o">..</span><span class="w"> </span><span class="mi">0</span><span class="p">]</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="mh">0x0</span><span class="p">;</span><span class="w"> </span><span class="c">// assume default Order dec</span><span class="w">
</span><span class="n">assert</span><span class="p">(</span><span class="n">v</span><span class="w"> </span><span class="p">==</span><span class="w"> </span><span class="mh">0xF0</span><span class="p">)</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>We also have vector concatenation l-values, which work much like
vector concatenation patterns</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="k">var</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="kt">bits</span><span class="p">(</span><span class="mi">4</span><span class="p">)</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="mh">0xF</span><span class="p">;</span><span class="w">
</span><span class="k">var</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="kt">bits</span><span class="p">(</span><span class="mi">4</span><span class="p">)</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="mh">0xF</span><span class="p">;</span><span class="w">
</span><span class="n">v1</span><span class="w"> </span><span class="p">@</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="mh">0xAB</span><span class="p">;</span><span class="w">
</span><span class="n">assert</span><span class="p">(</span><span class="n">v1</span><span class="w"> </span><span class="p">==</span><span class="w"> </span><span class="mh">0xA</span><span class="w"> </span><span class="o">&amp;</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="p">==</span><span class="w"> </span><span class="mh">0xB</span><span class="p">)</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>For structs we can write to an individual struct field as</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="c">// Assume S is a struct type with a single bits(8) field (called field)</span><span class="w">
</span><span class="k">var</span><span class="w"> </span><span class="n">s</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="n">S</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="k">struct</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="n">field</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="mh">0xFF</span><span class="w"> </span><span class="p">};</span><span class="w">
</span><span class="n">s</span><span class="o">.</span><span class="n">field</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="mh">0x00</span><span class="p">;</span><span class="w">
</span><span class="n">assert</span><span class="p">(</span><span class="n">s</span><span class="o">.</span><span class="n">field</span><span class="w"> </span><span class="p">==</span><span class="w"> </span><span class="mh">0x00</span><span class="p">)</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>We can also do multiple assignment using tuples, for example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="k">var</span><span class="w"> </span><span class="p">(</span><span class="n">x</span><span class="p">,</span><span class="w"> </span><span class="n">y</span><span class="p">)</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">(</span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="mi">3</span><span class="p">);</span><span class="w">
</span><span class="n">assert</span><span class="p">(</span><span class="n">x</span><span class="w"> </span><span class="p">==</span><span class="w"> </span><span class="mi">2</span><span class="w"> </span><span class="o">&amp;</span><span class="w"> </span><span class="n">x</span><span class="w"> </span><span class="p">==</span><span class="w"> </span><span class="mi">3</span><span class="p">)</span><span class="w">
</span><span class="c">// swap values</span><span class="w">
</span><span class="p">(</span><span class="n">y</span><span class="p">,</span><span class="w"> </span><span class="n">x</span><span class="p">)</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">(</span><span class="n">x</span><span class="p">,</span><span class="w"> </span><span class="n">y</span><span class="p">)</span><span class="w">
</span><span class="n">assert</span><span class="p">(</span><span class="n">x</span><span class="w"> </span><span class="p">==</span><span class="w"> </span><span class="mi">3</span><span class="w"> </span><span class="o">&amp;</span><span class="w"> </span><span class="n">x</span><span class="w"> </span><span class="p">==</span><span class="w"> </span><span class="mi">2</span><span class="p">)</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>Finally, we allow functions to appear in l-values. This is a very
simple way to declare <em>setter functions</em> that look like custom
l-values, for example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="n">memory</span><span class="p">(</span><span class="n">addr</span><span class="p">)</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="mh">0x0F</span><span class="w">
</span><span class="c">// is just syntactic sugar for</span><span class="w">
</span><span class="n">memory</span><span class="p">(</span><span class="n">addr</span><span class="p">,</span><span class="w"> </span><span class="mh">0x0F</span><span class="p">)</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>This feature is commonly used when setting registers or memory that
have some additional semantics when they are read or written. We
commonly use the ad-hoc overloading feature to declare what appear to
be getter/setter pairs, so for the above example we could implement a
<code>read_memory</code> function and a <code>write_memory</code> function and overload them
both as <code>memory</code> to allow us to write memory using
<code>memory(addr)&#160;=&#160;data</code> and read memory as
<code>data&#160;=&#160;memory(addr)</code>, for example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="k">val</span><span class="w"> </span><span class="nf">read_memory</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="kt">bits</span><span class="p">(</span><span class="mi">64</span><span class="p">)</span><span class="w"> </span><span class="p">-&gt;</span><span class="w"> </span><span class="kt">bits</span><span class="p">(</span><span class="mi">8</span><span class="p">)</span><span class="w">
</span><span class="k">val</span><span class="w"> </span><span class="nf">write_memory</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="p">(</span><span class="kt">bits</span><span class="p">(</span><span class="mi">64</span><span class="p">),</span><span class="w"> </span><span class="kt">bits</span><span class="p">(</span><span class="mi">8</span><span class="p">))</span><span class="w"> </span><span class="p">-&gt;</span><span class="w"> </span><span class="kt">unit</span><span class="w">

</span><span class="k">overload</span><span class="w"> </span><span class="n">memory</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">{</span><span class="n">read_memory</span><span class="p">,</span><span class="w"> </span><span class="n">write_memory</span><span class="p">}</span></code></pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_bitfields">Bitfields</h3>
<div class="paragraph">
<p>The following example creates a bitfield type called <code>cr_type</code> and a
register <code>CR</code> of that type. The underlying bitvector type (in this
case <code>bits(8)</code>) must be specified as part of the bitfield declaration.</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">
The underlying bitvector type can be specified using a type
synonym, like <code>xlenbits</code> in sail-riscv.
</td>
</tr>
</table>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="w">
</span><span class="k">bitfield</span><span class="w"> </span><span class="n">cr_type</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="kt">bits</span><span class="p">(</span><span class="mi">8</span><span class="p">)</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">{</span><span class="w">
  </span><span class="n">CR0</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="mi">7</span><span class="w"> </span><span class="o">..</span><span class="w"> </span><span class="mi">4</span><span class="p">,</span><span class="w">
  </span><span class="n">LT</span><span class="w">  </span><span class="p">:</span><span class="w"> </span><span class="mi">7</span><span class="p">,</span><span class="w">
  </span><span class="n">GT</span><span class="w">  </span><span class="p">:</span><span class="w"> </span><span class="mi">6</span><span class="p">,</span><span class="w">
  </span><span class="n">CR1</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="mi">3</span><span class="w"> </span><span class="o">..</span><span class="w"> </span><span class="mi">2</span><span class="p">,</span><span class="w">
  </span><span class="n">CR3</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="mi">1</span><span class="w"> </span><span class="o">..</span><span class="w"> </span><span class="mi">0</span><span class="w">
</span><span class="p">}</span><span class="w">

</span><span class="k">register</span><span class="w"> </span><span class="n">CR</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="n">cr_type</span><span class="w">
</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>If the bitvector is decreasing then indexes for the fields must also
be in decreasing order, and vice-versa for an increasing vector. The
field definitions can be overlapping and do not need to be contiguous.</p>
</div>
<div class="paragraph">
<p>A bitfield generates a type that is simply a struct wrapper around the
underlying bitvector, with a single field called <code>bits</code> containing
that bitvector. For the above example, this will be:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="k">struct</span><span class="w"> </span><span class="n">cr_type</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">{</span><span class="w">
  </span><span class="kt">bits</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="kt">bits</span><span class="p">(</span><span class="mi">8</span><span class="p">)</span><span class="w">
</span><span class="p">}</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>This representation is guaranteed, so it is expected that Sail code
will use the <code>bits</code> field to access the underlying bits of the
bitfield as needed. The following function shows how the bits
contained in a bitfield can be accessed:</p>
</div>
<div id="bitf-bitfield_access_example" class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="k">function</span><span class="w"> </span><span class="nf">bitfield_access_example</span><span class="p">()</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">{</span><span class="w">
  </span><span class="c">// Rather than using numeric indices, the bitfield names are used</span><span class="w">
  </span><span class="k">let</span><span class="w"> </span><span class="n">cr0_field</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="kt">bits</span><span class="p">(</span><span class="mi">4</span><span class="p">)</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">CR</span><span class="p">[</span><span class="n">CR0</span><span class="p">];</span><span class="w">

  </span><span class="c">// Bitfield accessors always return bitvector results</span><span class="w">
  </span><span class="k">let</span><span class="w"> </span><span class="n">lt_field</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="kt">bits</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">CR</span><span class="p">[</span><span class="n">LT</span><span class="p">];</span><span class="w"> </span><span class="c">// Note 'bits(1)' not 'bit'</span><span class="w">

  </span><span class="c">// Can access the underlying bitvector using the bits field</span><span class="w">
  </span><span class="k">let</span><span class="w"> </span><span class="n">some_bits</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="kt">bits</span><span class="p">(</span><span class="mi">7</span><span class="p">)</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">CR</span><span class="o">.</span><span class="kt">bits</span><span class="p">[</span><span class="mi">6</span><span class="w"> </span><span class="o">..</span><span class="w"> </span><span class="mi">0</span><span class="p">];</span><span class="w">
</span><span class="p">}</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>Similarly, bitfields can be updated much like regular vectors just
using the field names rather than numeric indices:</p>
</div>
<div id="bitf-bitfield_update_example" class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="k">function</span><span class="w"> </span><span class="nf">bitfield_update_example</span><span class="p">()</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">{</span><span class="w">
  </span><span class="c">// We can set fields on the CR register using their field names</span><span class="w">
  </span><span class="n">CR</span><span class="p">[</span><span class="n">CR3</span><span class="p">]</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="mb">0b01</span><span class="p">;</span><span class="w">

  </span><span class="c">// If we want to set the underlying bits</span><span class="w">
  </span><span class="n">CR</span><span class="o">.</span><span class="kt">bits</span><span class="p">[</span><span class="mi">1</span><span class="w"> </span><span class="o">..</span><span class="w"> </span><span class="mi">0</span><span class="p">]</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="mb">0b01</span><span class="p">;</span><span class="w">

  </span><span class="c">// We can even use vector update notation!</span><span class="w">
  </span><span class="n">CR</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">[</span><span class="n">CR</span><span class="w"> </span><span class="k">with</span><span class="w"> </span><span class="n">CR3</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="mb">0b01</span><span class="p">,</span><span class="w"> </span><span class="n">LT</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="mb">0b1</span><span class="p">];</span><span class="w">

  </span><span class="c">// Because of the representation, we could set the whole thing like:</span><span class="w">
  </span><span class="n">CR</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">(</span><span class="k">struct</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="kt">bits</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="mh">0x00</span><span class="w"> </span><span class="p">}</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="n">cr_type</span><span class="p">);</span><span class="w">
</span><span class="p">}</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>In the case of overlapping fields, the vector update notion will
update the fields in order from left to right.</p>
</div>
<div class="paragraph">
<p>Older versions of Sail did not guarantee the underlying representation
of the bitfield (because it tried to do clever things to optimise
them). This meant that bitfields had to be accessed using getter and
setter functions, like so:</p>
</div>
<div id="bitf-legacy_bitfields" class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="k">function</span><span class="w"> </span><span class="nf">legacy_bitfields</span><span class="p">()</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">{</span><span class="w">
  </span><span class="c">// Assigning to a field of a bitfield register</span><span class="w">
  </span><span class="n">CR</span><span class="p">-&gt;</span><span class="n">CR3</span><span class="p">()</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="mb">0b01</span><span class="p">;</span><span class="w">
  </span><span class="c">// '-&gt;' notation just means the setter takes the register by reference:</span><span class="w">
  </span><span class="p">(</span><span class="k">ref</span><span class="w"> </span><span class="n">CR</span><span class="p">)</span><span class="o">.</span><span class="n">CR3</span><span class="p">()</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="mb">0b01</span><span class="p">;</span><span class="w">

  </span><span class="c">// Assigning all the bits (now just 'CR.bits = 0x00')</span><span class="w">
  </span><span class="n">CR</span><span class="p">-&gt;</span><span class="kt">bits</span><span class="p">()</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="mh">0x00</span><span class="p">;</span><span class="w">

  </span><span class="c">// Accessing a field</span><span class="w">
  </span><span class="k">let</span><span class="w"> </span><span class="n">cr0_field</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="kt">bits</span><span class="p">(</span><span class="mi">4</span><span class="p">)</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">CR</span><span class="o">.</span><span class="n">CR0</span><span class="p">();</span><span class="w">

  </span><span class="c">// Updating a field</span><span class="w">
  </span><span class="n">CR</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">update_CR3</span><span class="p">(</span><span class="n">CR</span><span class="p">,</span><span class="w"> </span><span class="mb">0b01</span><span class="p">);</span><span class="w"> </span><span class="c">// now '[ CR with CR3 = 0b01 ]'</span><span class="w">

  </span><span class="c">// Construct a new CR bitfield</span><span class="w">
  </span><span class="n">CR</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">Mk_cr_type</span><span class="p">(</span><span class="mh">0x00</span><span class="p">);</span><span class="w">
</span><span class="p">}</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>The method like accessor syntax was (overly sweet) syntactic sugar for
getter and setter functions following a specific naming convention
that was generated by the bitfield. These functions are still
generated for backwards compatibility, but we would advise against
using them.</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">
Except perhaps for the <code>Mk_cr_type</code> function or equivalent for
other bitfields, which is still quite useful for creating bitfields.
</td>
</tr>
</table>
</div>
</div>
<div class="sect2">
<h3 id="_operators">Operators</h3>
<div class="paragraph">
<p>Valid operators in Sail are sequences of the following non
alpha-numeric characters: <code>!%&amp;*+-./:&lt;&gt;=@^|#</code>. Additionally, any such
sequence may be suffixed by an underscore followed by any valid
identifier, so <code>&lt;=_u</code> or even <code>&lt;=_unsigned</code> are valid operator names.
Operators may be left, right, or non-associative, and there are 10
different precedence levels, ranging from 0 to 9, with 9 binding the
tightest. To declare the precedence of an operator, we use a fixity
declaration like:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="n">infix</span><span class="w"> </span><span class="mi">4</span><span class="w"> </span><span class="o">&lt;=_u</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>For left or right associative operators, we&#8217;d use the keywords
<code>infixl</code> or <code>infixr</code> respectively. An operator can be used anywhere a
normal identifier could be used via the <code>operator</code> keyword. As such,
the <code>&lt;=_u</code> operator can be defined as:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="k">val</span><span class="w"> </span><span class="nf">operator</span><span class="w"> </span><span class="o">&lt;=_u</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="k">forall</span><span class="w"> </span><span class="nv">'n</span><span class="o">.</span><span class="w"> </span><span class="p">(</span><span class="kt">bits</span><span class="p">(</span><span class="nv">'n</span><span class="p">),</span><span class="w"> </span><span class="kt">bits</span><span class="p">(</span><span class="nv">'n</span><span class="p">))</span><span class="w"> </span><span class="p">-&gt;</span><span class="w"> </span><span class="kt">bool</span><span class="w">
</span><span class="k">function</span><span class="w"> </span><span class="nf">operator</span><span class="w"> </span><span class="o">&lt;=_u</span><span class="p">(</span><span class="n">x</span><span class="p">,</span><span class="w"> </span><span class="n">y</span><span class="p">)</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">unsigned</span><span class="p">(</span><span class="n">x</span><span class="p">)</span><span class="w"> </span><span class="o">&lt;=</span><span class="w"> </span><span class="n">unsigned</span><span class="p">(</span><span class="n">y</span><span class="p">)</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>By default, Sail defines the basic arithmetic operators <code>*</code>, <code>\</code>, <code>%</code>,
<code>+</code>, and <code>-</code>, for integer multiplication, division, modulus, addition,
and subtraction respectively. The Sail library also overloads addition
and subtraction for bitvectors, performing two&#8217;s complement arithmetic
over bitvectors with matching sizes. Adding a bitvector and an integer
is also allowed, i.e. <code>0x01 + N</code>. For small bitvectors and large
integers this is equivalent to adding 1 to the bitvector <code>N</code> times,
wrapping each time the value overflows, for example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="mh">0xFF</span><span class="w"> </span><span class="o">+</span><span class="w"> </span><span class="mi">2</span><span class="w"> </span><span class="p">==</span><span class="w"> </span><span class="p">(</span><span class="mh">0xFF</span><span class="w"> </span><span class="o">+</span><span class="w"> </span><span class="mh">0x01</span><span class="p">)</span><span class="w"> </span><span class="o">+</span><span class="w"> </span><span class="mh">0x01</span><span class="w"> </span><span class="p">==</span><span class="w"> </span><span class="mh">0x01</span><span class="w">
</span><span class="c">// Wrapping multiple times:</span><span class="w">
</span><span class="mb">0b0</span><span class="w"> </span><span class="o">+</span><span class="w"> </span><span class="mi">3</span><span class="w"> </span><span class="p">==</span><span class="w"> </span><span class="p">((</span><span class="mb">0b0</span><span class="w"> </span><span class="o">+</span><span class="w"> </span><span class="mb">0b1</span><span class="p">)</span><span class="w"> </span><span class="o">+</span><span class="w"> </span><span class="mb">0b1</span><span class="p">)</span><span class="w"> </span><span class="o">+</span><span class="w"> </span><span class="mb">0b1</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">((</span><span class="mb">0b1</span><span class="w"> </span><span class="o">+</span><span class="w"> </span><span class="mb">0b1</span><span class="p">)</span><span class="w"> </span><span class="o">+</span><span class="w"> </span><span class="mb">0b1</span><span class="p">)</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="mb">0b0</span><span class="w"> </span><span class="o">+</span><span class="w"> </span><span class="mb">0b1</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="mb">0b1</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>The comparison operators <code>&lt;</code>, <code>&#8656;</code>, <code>&gt;</code>, <code>&gt;=</code>, <code>!=</code>, and <code>==</code> all
compare integers. We don&#8217;t define bitvector comparisons by default, as
bitvectors can be compared as either signed or unsigned. Individual
ISA specifications may choose to overload these operators or define
their own as needed.</p>
</div>
<div class="paragraph">
<p>The boolean operators <code>&amp;</code> (logical and) and <code>|</code> (logical or) compare
boolean values. Note that when applied to booleans they have
short-circuiting semantics. The standard library overloads these
operators for bitwise operations on bitvectors of the same length.</p>
</div>
<div class="paragraph">
<p>The exponentiation operator <code>^</code> is slightly special. The Sail parser
recognises the special case <code>2 ^ x</code> directly and maps that to a
special <code>pow2(x)</code> function. This is because <code>2 ^ x</code> is the only form
of exponentiation we permit in numeric types. The <code>^</code> operator can
otherwise be overloaded by ISA specs as a normal operator.</p>
</div>
<div class="paragraph">
<p>The <code>@</code> operators is used to concatenate bitvectors and generic
vectors. As demonstrated in the pattern matching section <a href="#_pattern_matching">Pattern matching</a>,
it can also be used to destructure them. Similarly, the
cons operator <code>::</code> is used to construct lists (see section <a href="#The list type">[The list type]</a>).</p>
</div>
<div class="sect3">
<h4 id="_built_in_precedences">Built-in precedences</h4>
<div class="paragraph">
<p>The precedence of several common operators are built into Sail. These
include all the operators that are used in type-level numeric
expressions, as well as several common operations such as equality,
division, and modulus. The precedences for these operators are
summarised in the following table.</p>
</div>
<table class="tableblock frame-all grid-all" style="width: 80%;">
<caption class="title">Table 1. Default Sail operator precedences</caption>
<colgroup>
<col style="width: 14.2857%;">
<col style="width: 28.5714%;">
<col style="width: 28.5714%;">
<col style="width: 28.5715%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Precedence</th>
<th class="tableblock halign-left valign-top">Left associative</th>
<th class="tableblock halign-left valign-top">Non-associative</th>
<th class="tableblock halign-left valign-top">Right associative</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">9</p></td>
<td class="tableblock halign-left valign-top"></td>
<td class="tableblock halign-left valign-top"></td>
<td class="tableblock halign-left valign-top"></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">8</p></td>
<td class="tableblock halign-left valign-top"></td>
<td class="tableblock halign-left valign-top"></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>^</code></p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">7</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>*, \, %</code></p></td>
<td class="tableblock halign-left valign-top"></td>
<td class="tableblock halign-left valign-top"></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">6</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>+, -</code></p></td>
<td class="tableblock halign-left valign-top"></td>
<td class="tableblock halign-left valign-top"></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">5</p></td>
<td class="tableblock halign-left valign-top"></td>
<td class="tableblock halign-left valign-top"></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>::, @</code></p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">4</p></td>
<td class="tableblock halign-left valign-top"></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>&lt;, &#8656;, &gt;, &gt;=, !=, ==</code></p></td>
<td class="tableblock halign-left valign-top"></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">3</p></td>
<td class="tableblock halign-left valign-top"></td>
<td class="tableblock halign-left valign-top"></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>&amp;</code></p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">2</p></td>
<td class="tableblock halign-left valign-top"></td>
<td class="tableblock halign-left valign-top"></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>|</code></p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">1</p></td>
<td class="tableblock halign-left valign-top"></td>
<td class="tableblock halign-left valign-top"></td>
<td class="tableblock halign-left valign-top"></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">0</p></td>
<td class="tableblock halign-left valign-top"></td>
<td class="tableblock halign-left valign-top"></td>
<td class="tableblock halign-left valign-top"></td>
</tr>
</tbody>
</table>
</div>
</div>
<div class="sect2">
<h3 id="_ad_hoc_overloading">Ad-hoc overloading</h3>
<div class="paragraph">
<p>Sail has a flexible overloading mechanism using the overload keyword. For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="k">overload</span><span class="w"> </span><span class="n">foo</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">{</span><span class="n">bar</span><span class="p">,</span><span class="w"> </span><span class="n">baz</span><span class="p">}</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>It takes an identifier name, and a list of other identifier names to
overload that name with. When the overloaded name is seen in a Sail
definition, the type-checker will try each of the overloads (that are
in scope) in order from left to right until it finds one that causes
the resulting expression to type-check correctly.</p>
</div>
<div class="paragraph">
<p>Multiple <code>overload</code> declarations are permitted for the same
identifier, with each overload declaration after the first adding its
list of identifier names to the right of the overload list (so earlier
overload declarations take precedence over later ones). As such, we
could split every identifier from above example into its own
line like so:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="k">overload</span><span class="w"> </span><span class="n">foo</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">{</span><span class="n">bar</span><span class="p">}</span><span class="w">
</span><span class="k">overload</span><span class="w"> </span><span class="n">foo</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">{</span><span class="n">baz</span><span class="p">}</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>Note that if an overload is defined in module <code>B</code> using identifiers
provided by another module <code>A</code>, then a module <code>C</code> that requires only
<code>B</code> will not see any of the identifiers from <code>A</code>, unless it also
requires <code>A</code>. See the section on modules for details. Note that this
means an overload cannot be used to 're-export' definitions provided by
another module.</p>
</div>
<div class="paragraph">
<p>As an example for how overloaded functions can be used, consider the
following example, where we define a function <code>print_int</code> and a
function <code>print_string</code> for printing integers and strings
respectively. We overload <code>print</code> as either <code>print_int</code> or
<code>print_string</code>, so we can print either number such as 4, or strings
like <code>"Hello, World!"</code> in the following <code>main</code> function definition.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="k">val</span><span class="w"> </span><span class="nf">print_int</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="kt">int</span><span class="w"> </span><span class="p">-&gt;</span><span class="w"> </span><span class="kt">unit</span><span class="w">

</span><span class="k">val</span><span class="w"> </span><span class="nf">print_string</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="n">string</span><span class="w"> </span><span class="p">-&gt;</span><span class="w"> </span><span class="kt">unit</span><span class="w">

</span><span class="k">overload</span><span class="w"> </span><span class="n">print</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">{</span><span class="n">print_int</span><span class="p">,</span><span class="w"> </span><span class="n">print_string</span><span class="p">}</span><span class="w">

</span><span class="k">function</span><span class="w"> </span><span class="nf">main</span><span class="p">()</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="kt">unit</span><span class="w"> </span><span class="p">-&gt;</span><span class="w"> </span><span class="kt">unit</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">{</span><span class="w">
  </span><span class="n">print</span><span class="p">(</span><span class="s">"Hello, World!"</span><span class="p">);</span><span class="w">
  </span><span class="n">print</span><span class="p">(</span><span class="mi">4</span><span class="p">)</span><span class="w">
</span><span class="p">}</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>We can see that the overloading has had the desired effect by dumping
the type-checked AST to stdout using the following command
<code>sail -ddump_tc_ast examples/overload.sail</code>. This will print the
following, which shows how the overloading has been resolved</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="k">function</span><span class="w"> </span><span class="nf">main</span><span class="w"> </span><span class="p">()</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="kt">unit</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">{</span><span class="w">
  </span><span class="n">print_string</span><span class="p">(</span><span class="s">"Hello, World!"</span><span class="p">);</span><span class="w">
  </span><span class="n">print_int</span><span class="p">(</span><span class="mi">4</span><span class="p">)</span><span class="w">
</span><span class="p">}</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>This option can sometimes be quite useful for observing how
overloading has been resolved. Since the overloadings are done in the
order they are defined, it can be important to ensure that this order
is correct. A common idiom in the standard library is to have versions
of functions that guarantee more constraints about their output be
overloaded with functions that accept more inputs but guarantee less
about their results. For example, we might have two division
functions:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="k">val</span><span class="w"> </span><span class="nf">div1</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="k">forall</span><span class="w"> </span><span class="nv">'m</span><span class="w"> </span><span class="nv">'n</span><span class="p">,</span><span class="w"> </span><span class="nv">'n</span><span class="w"> </span><span class="o">&gt;=</span><span class="w"> </span><span class="mi">0</span><span class="w"> </span><span class="o">&amp;</span><span class="w"> </span><span class="nv">'m</span><span class="w"> </span><span class="o">&gt;</span><span class="w"> </span><span class="mi">0</span><span class="o">.</span><span class="w"> </span><span class="p">(</span><span class="kt">int</span><span class="p">(</span><span class="nv">'n</span><span class="p">),</span><span class="w"> </span><span class="kt">int</span><span class="p">(</span><span class="nv">'m</span><span class="p">))</span><span class="w"> </span><span class="p">-&gt;</span><span class="w"> </span><span class="p">{</span><span class="nv">'o</span><span class="p">,</span><span class="w"> </span><span class="nv">'o</span><span class="w"> </span><span class="o">&gt;=</span><span class="w"> </span><span class="mi">0</span><span class="o">.</span><span class="w"> </span><span class="kt">int</span><span class="p">(</span><span class="nv">'o</span><span class="p">)}</span><span class="w">

</span><span class="k">val</span><span class="w"> </span><span class="nf">div2</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="p">(</span><span class="kt">int</span><span class="p">,</span><span class="w"> </span><span class="kt">int</span><span class="p">)</span><span class="w"> </span><span class="p">-&gt;</span><span class="w"> </span><span class="kt">option</span><span class="p">(</span><span class="kt">int</span><span class="p">)</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>The first guarantees that if the first argument is greater than or
equal to zero, and the second argument is greater than zero, then the
result will be greater than or equal to zero. If we overload these
definitions as</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="k">overload</span><span class="w"> </span><span class="k">operator</span><span class="w"> </span><span class="o">/</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">{</span><span class="n">div1</span><span class="p">,</span><span class="w"> </span><span class="n">div2</span><span class="p">}</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>Then the first will be applied when the constraints on its inputs can
be resolved, and therefore the guarantees on its output can be
guaranteed, but the second will be used when this is not the case, and
indeed, we will need to manually check for the division by zero case
due to the option type. Notice that the return type can be different
between different cases in the overload.</p>
</div>
</div>
<div class="sect2">
<h3 id="_mappings">Mappings</h3>
<div class="paragraph">
<p>Mappings are a feature of Sail that allow concise expression of
bidirectional relationships between values that are common in ISA
specifications: for example, bit-representations of an enum type, or
the encoding-decoding of instructions.</p>
</div>
<div class="paragraph">
<p>They are defined similarly to functions, with a <code>val</code> keyword to
specify the type and a definition, using a bidirectional arrow <code>&lt;-&gt;</code>
rather than a function arrow <code>-&gt;</code>, and a separate <code>mapping</code>
definition.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="k">val</span><span class="w"> </span><span class="nf">size_bits</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="n">word_width</span><span class="w"> </span><span class="o">&lt;-&gt;</span><span class="w"> </span><span class="kt">bits</span><span class="p">(</span><span class="mi">2</span><span class="p">)</span><span class="w">

</span><span class="k">mapping</span><span class="w"> </span><span class="n">size_bits</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">{</span><span class="w">
  </span><span class="n">BYTE</span><span class="w">   </span><span class="o">&lt;-&gt;</span><span class="w"> </span><span class="mb">0b00</span><span class="p">,</span><span class="w">
  </span><span class="n">HALF</span><span class="w">   </span><span class="o">&lt;-&gt;</span><span class="w"> </span><span class="mb">0b01</span><span class="p">,</span><span class="w">
  </span><span class="n">WORD</span><span class="w">   </span><span class="o">&lt;-&gt;</span><span class="w"> </span><span class="mb">0b10</span><span class="p">,</span><span class="w">
  </span><span class="n">DOUBLE</span><span class="w"> </span><span class="o">&lt;-&gt;</span><span class="w"> </span><span class="mb">0b11</span><span class="w">
</span><span class="p">}</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>As a shorthand, you can also specify a mapping and its type
simultaneously:</p>
</div>
<div id="maps-span-M2" class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="k">mapping</span><span class="w"> </span><span class="n">size_bits2</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="n">word_width</span><span class="w"> </span><span class="o">&lt;-&gt;</span><span class="w"> </span><span class="kt">bits</span><span class="p">(</span><span class="mi">2</span><span class="p">)</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">{</span><span class="w">
  </span><span class="n">BYTE</span><span class="w">   </span><span class="o">&lt;-&gt;</span><span class="w"> </span><span class="mb">0b00</span><span class="p">,</span><span class="w">
  </span><span class="n">HALF</span><span class="w">   </span><span class="o">&lt;-&gt;</span><span class="w"> </span><span class="mb">0b01</span><span class="p">,</span><span class="w">
  </span><span class="n">WORD</span><span class="w">   </span><span class="o">&lt;-&gt;</span><span class="w"> </span><span class="mb">0b10</span><span class="p">,</span><span class="w">
  </span><span class="n">DOUBLE</span><span class="w"> </span><span class="o">&lt;-&gt;</span><span class="w"> </span><span class="mb">0b11</span><span class="w">
</span><span class="p">}</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>Mappings are used simply by calling them as if they were functions:
type inference will determine in which direction the mapping is
applied. (This gives rise to the restriction that the types on either
side of a mapping must be different.)</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="k">let</span><span class="w"> </span><span class="n">width</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="n">word_width</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">size_bits</span><span class="p">(</span><span class="mb">0b00</span><span class="p">);</span><span class="w">
</span><span class="k">let</span><span class="w"> </span><span class="n">width</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="kt">bits</span><span class="p">(</span><span class="mi">2</span><span class="p">)</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">size_bits</span><span class="p">(</span><span class="n">BYTE</span><span class="p">);</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>Sometimes, because the subset of Sail allowed in bidirectional mapping
clauses is quite restrictive, it can be useful to specify the forwards
and backwards part of a mapping separately:</p>
</div>
<div id="maps-span-M3" class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="k">mapping</span><span class="w"> </span><span class="n">size_bits3</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="n">word_width</span><span class="w"> </span><span class="o">&lt;-&gt;</span><span class="w"> </span><span class="kt">bits</span><span class="p">(</span><span class="mi">2</span><span class="p">)</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">{</span><span class="w">
  </span><span class="n">BYTE</span><span class="w"> </span><span class="o">&lt;-&gt;</span><span class="w"> </span><span class="mb">0b00</span><span class="p">,</span><span class="w">
  </span><span class="n">HALF</span><span class="w"> </span><span class="o">&lt;-&gt;</span><span class="w"> </span><span class="mb">0b01</span><span class="p">,</span><span class="w">
  </span><span class="n">WORD</span><span class="w"> </span><span class="o">&lt;-&gt;</span><span class="w"> </span><span class="mb">0b10</span><span class="p">,</span><span class="w">
  </span><span class="k">forwards</span><span class="w">  </span><span class="n">DOUBLE</span><span class="w"> </span><span class="p">=</span><span class="o">&gt;</span><span class="w"> </span><span class="mb">0b11</span><span class="p">,</span><span class="w"> </span><span class="c">// forwards is left-to-right</span><span class="w">
  </span><span class="k">backwards</span><span class="w"> </span><span class="mb">0b11</span><span class="w"> </span><span class="p">=</span><span class="o">&gt;</span><span class="w"> </span><span class="n">DOUBLE</span><span class="p">,</span><span class="w"> </span><span class="c">// backwards is right-to-left</span><span class="w">
</span><span class="p">}</span></code></pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_sizeof_and_constraint">Sizeof and constraint</h3>
<div class="paragraph">
<p>Sail allows for arbitrary type variables to be included within
expressions. However, we can go slightly further than this, and
include both arbitrary (type-level) numeric expressions in code, as
well as type constraints. For example, if we have a function that
takes two bitvectors as arguments, then there are several ways we
could compute the sum of their lengths.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="k">val</span><span class="w"> </span><span class="nf">f</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="k">forall</span><span class="w"> </span><span class="nv">'n</span><span class="w"> </span><span class="nv">'m</span><span class="o">.</span><span class="w"> </span><span class="p">(</span><span class="kt">bits</span><span class="p">(</span><span class="nv">'n</span><span class="p">),</span><span class="w"> </span><span class="kt">bits</span><span class="p">(</span><span class="nv">'m</span><span class="p">))</span><span class="w"> </span><span class="p">-&gt;</span><span class="w"> </span><span class="kt">unit</span><span class="w">

</span><span class="k">function</span><span class="w"> </span><span class="nf">f</span><span class="p">(</span><span class="n">xs</span><span class="p">,</span><span class="w"> </span><span class="n">ys</span><span class="p">)</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">{</span><span class="w">
  </span><span class="k">let</span><span class="w"> </span><span class="n">len</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">length</span><span class="p">(</span><span class="n">xs</span><span class="p">)</span><span class="w"> </span><span class="o">+</span><span class="w"> </span><span class="n">length</span><span class="p">(</span><span class="n">ys</span><span class="p">);</span><span class="w">
  </span><span class="k">let</span><span class="w"> </span><span class="n">len</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="nv">'n</span><span class="w"> </span><span class="o">+</span><span class="w"> </span><span class="nv">'m</span><span class="p">;</span><span class="w">
  </span><span class="k">let</span><span class="w"> </span><span class="n">len</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="nb">sizeof</span><span class="p">(</span><span class="nv">'n</span><span class="w"> </span><span class="o">+</span><span class="w"> </span><span class="nv">'m</span><span class="p">);</span><span class="w">
  </span><span class="p">()</span><span class="w">
</span><span class="p">}</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>Note that the second line is equivalent to</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="w">  </span><span class="k">let</span><span class="w"> </span><span class="n">len</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="nb">sizeof</span><span class="p">(</span><span class="nv">'n</span><span class="p">)</span><span class="w"> </span><span class="o">+</span><span class="w"> </span><span class="nb">sizeof</span><span class="p">(</span><span class="nv">'n</span><span class="p">)</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>There is also the <code>constraint</code> keyword, which takes a type-level
constraint and allows it to be used as a boolean expression, so we
could write:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="k">function</span><span class="w"> </span><span class="nf">f</span><span class="p">(</span><span class="n">xs</span><span class="p">,</span><span class="w"> </span><span class="n">ys</span><span class="p">)</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">{</span><span class="w">
  </span><span class="k">if</span><span class="w"> </span><span class="nb">constraint</span><span class="p">(</span><span class="nv">'n</span><span class="w"> </span><span class="o">&lt;=</span><span class="w"> </span><span class="nv">'m</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w">
    </span><span class="c">// Do something</span><span class="w">
  </span><span class="p">}</span><span class="w">
</span><span class="p">}</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>rather than the equivalent test <code>length(xs)&#160;&lt;=&#160;length(ys)</code>.
This way of writing expressions can be succinct, and can also make it
very explicit what constraints will be generated during flow typing.
However, all the constraint and sizeof definitions must be re-written
to produce executable code, which can result in the generated theorem
prover output diverging (in appearance) somewhat from the source
input. In general, it is probably best to use <code>sizeof</code> and
<code>constraint</code> sparingly on type variables.</p>
</div>
<div class="paragraph">
<p>One common use for sizeof however, is to lower type-level integers
down to the value level, for example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="c">// xlen is a type of kind 'Int'</span><span class="w">
</span><span class="k">type</span><span class="w"> </span><span class="n">xlen</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="mi">64</span><span class="w">

</span><span class="k">val</span><span class="w"> </span><span class="nf">f</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="kt">int</span><span class="w"> </span><span class="p">-&gt;</span><span class="w"> </span><span class="kt">unit</span><span class="w">

</span><span class="k">function</span><span class="w"> </span><span class="nf">xlen_example</span><span class="p">()</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">{</span><span class="w">
  </span><span class="k">let</span><span class="w"> </span><span class="n">v</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="nb">sizeof</span><span class="p">(</span><span class="n">xlen</span><span class="p">);</span><span class="w">
  </span><span class="n">f</span><span class="p">(</span><span class="n">v</span><span class="p">)</span><span class="w">
</span><span class="p">}</span></code></pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_exceptions">Exceptions</h3>
<div class="paragraph">
<p>Perhaps surprisingly for a specification language, Sail has exception
support. This is because exceptions as a language feature do sometimes
appear in vendor ISA pseudocode (they are a feature in Arm&#8217;s ASL
language), and such code would be very difficult to translate into
Sail if Sail did not itself support exceptions. In practice Sail
language-level exceptions end up being quite a nice tool for
implementing processor exceptions in ISA specifications.</p>
</div>
<div class="paragraph">
<p>For exceptions we have two language features: <code>throw</code> statements and
<code>try</code>--<code>catch</code> blocks. The throw keyword takes a value of type
<code>exception</code> as an argument, which can be any user defined type with
that name. There is no built-in exception type, so to use exceptions
one must be set up on a per-project basis. The exception type must be
a union (except it cannot be declared via <code>newtype</code>), and is usually a
scattered union to allow exceptions to be declared throughout the
specification as they would be in OCaml, for example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="k">scattered</span><span class="w"> </span><span class="k">union</span><span class="w"> </span><span class="n">exception</span><span class="w">

</span><span class="k">union</span><span class="w"> </span><span class="k">clause</span><span class="w"> </span><span class="n">exception</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">Epair</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="p">(</span><span class="n">range</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span><span class="w"> </span><span class="mi">255</span><span class="p">),</span><span class="w"> </span><span class="n">range</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span><span class="w"> </span><span class="mi">255</span><span class="p">))</span><span class="w">

</span><span class="k">union</span><span class="w"> </span><span class="k">clause</span><span class="w"> </span><span class="n">exception</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">Eunknown</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="n">string</span><span class="w">

</span><span class="k">function</span><span class="w"> </span><span class="nf">main</span><span class="p">()</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="kt">unit</span><span class="w"> </span><span class="p">-&gt;</span><span class="w"> </span><span class="kt">unit</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">{</span><span class="w">
    </span><span class="k">try</span><span class="w"> </span><span class="p">{</span><span class="w">
        </span><span class="k">throw</span><span class="p">(</span><span class="n">Eunknown</span><span class="p">(</span><span class="s">"foo"</span><span class="p">))</span><span class="w">
    </span><span class="p">}</span><span class="w"> </span><span class="k">catch</span><span class="w"> </span><span class="p">{</span><span class="w">
        </span><span class="n">Eunknown</span><span class="p">(</span><span class="n">msg</span><span class="p">)</span><span class="w"> </span><span class="p">=</span><span class="o">&gt;</span><span class="w"> </span><span class="n">print_endline</span><span class="p">(</span><span class="n">msg</span><span class="p">),</span><span class="w">
        </span><span class="mi">_</span><span class="w"> </span><span class="p">=</span><span class="o">&gt;</span><span class="w"> </span><span class="nb">exit</span><span class="p">()</span><span class="w">
    </span><span class="p">}</span><span class="w">
</span><span class="p">}</span><span class="w">

</span><span class="k">union</span><span class="w"> </span><span class="k">clause</span><span class="w"> </span><span class="n">exception</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">Eint</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="kt">int</span><span class="w">

</span><span class="k">end</span><span class="w"> </span><span class="n">exception</span></code></pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_scattered_definitions">Scattered definitions</h3>
<div class="paragraph">
<p>In a Sail specification, sometimes it is desirable to collect together
the definitions relating to each machine instruction (or group
thereof), e.g.~grouping the clauses of an AST type with the associated
clauses of decode and execute functions, as in
the <a href="#_a_tutorial_risc_v_style_example">A tutorial RISC-V style example</a> section.
Sail permits this with syntactic sugar for `scattered' definitions.
Functions, mappings, unions, and enums can be scattered.</p>
</div>
<div class="paragraph">
<p>One begins a scattered definition by declaring the name and kind
(either function or union) of the scattered definition, e.g.</p>
</div>
<div id="sdef-span-DECS" class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="c">// We can declare scattered types, for either unions or enums</span><span class="w">
</span><span class="k">scattered</span><span class="w"> </span><span class="k">union</span><span class="w"> </span><span class="n">U</span><span class="w">

</span><span class="k">scattered</span><span class="w"> </span><span class="k">enum</span><span class="w"> </span><span class="n">E</span><span class="w">

</span><span class="c">// For scattered functions and mappings, we have to provide a type signature with val</span><span class="w">
</span><span class="k">val</span><span class="w"> </span><span class="nf">foo</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="n">U</span><span class="w"> </span><span class="p">-&gt;</span><span class="w"> </span><span class="kt">bits</span><span class="p">(</span><span class="mi">64</span><span class="p">)</span><span class="w">

</span><span class="k">scattered</span><span class="w"> </span><span class="k">function</span><span class="w"> </span><span class="nf">foo</span><span class="w">

</span><span class="k">val</span><span class="w"> </span><span class="nf">bar</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="n">E</span><span class="w"> </span><span class="o">&lt;-&gt;</span><span class="w"> </span><span class="n">string</span><span class="w">

</span><span class="k">scattered</span><span class="w"> </span><span class="k">mapping</span><span class="w"> </span><span class="n">bar</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>This is then followed by <em>clauses</em> for either, which can be freely
interleaved with other definitions. It is common to define both a
scattered type (either union or enum), with a scattered function that
operates on newly defined clauses of that type, as is shown below:</p>
</div>
<div id="sdef-span-CLAUSES" class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="k">enum</span><span class="w"> </span><span class="k">clause</span><span class="w"> </span><span class="n">E</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">E_one</span><span class="w">

</span><span class="k">union</span><span class="w"> </span><span class="k">clause</span><span class="w"> </span><span class="n">U</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">U_one</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="kt">bits</span><span class="p">(</span><span class="mi">64</span><span class="p">)</span><span class="w">

</span><span class="k">function</span><span class="w"> </span><span class="nf">clause</span><span class="w"> </span><span class="n">foo</span><span class="p">(</span><span class="n">U_one</span><span class="p">(</span><span class="n">x</span><span class="p">))</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">x</span><span class="w">

</span><span class="k">mapping</span><span class="w"> </span><span class="k">clause</span><span class="w"> </span><span class="n">bar</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">E_one</span><span class="w"> </span><span class="o">&lt;-&gt;</span><span class="w"> </span><span class="s">"first member of E"</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>Finally the scattered definitions are ended with the <code>end</code> keyword, like so:</p>
</div>
<div id="sdef-span-ENDS" class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="k">end</span><span class="w"> </span><span class="n">E</span><span class="w">

</span><span class="k">end</span><span class="w"> </span><span class="n">U</span><span class="w">

</span><span class="k">end</span><span class="w"> </span><span class="n">foo</span><span class="w">

</span><span class="k">end</span><span class="w"> </span><span class="n">bar</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>Technically the <code>end</code> keyword is not required, but it is good practice
to include it as it informs Sail that the clauses are now complete,
which forbids new clauses and means subsequent pattern completeness
checks no longer have to require extra wildcards to account for new
clauses being added.</p>
</div>
<div class="paragraph">
<p>Semantically, scattered definitions for types appear at the start of
their definition (note however, that this does not mean that a module
that requires just the start <code>scattered union</code> definition can access
any constructors of a union defined in modules it does not require).
Scattered definitions for functions and mappings appear at the
end. A scattered function definition can be recursive, but mutually
recursive scattered function definitions should be avoided.</p>
</div>
</div>
<div class="sect2">
<h3 id="_preludes_and_default_environment">Preludes and default environment</h3>
<div class="paragraph">
<p>By default Sail has almost no built-in types or functions, except for
the primitive types described in this Chapter. This is because
different vendor-pseudocodes have varying naming conventions and
styles for even the most basic operators, so we aim to provide
flexibility and avoid committing to any particular naming convention or
set of built-ins. However, each Sail backend typically implements
specific external names, so for a PowerPC ISA description one might
have:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="k">val</span><span class="w"> </span><span class="nf">EXTZ</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="s">"zero_extend"</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="o">...</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>while for ARM, to mimic ASL, one would have</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="k">val</span><span class="w"> </span><span class="nf">ZeroExtend</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="s">"zero_extend"</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="o">...</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>where each backend knows about the <code>"zero_extend"</code> external name, but
the actual Sail functions are named appropriately for each vendor&#8217;s
pseudocode. As such each ISA spec written in Sail tends to have its
own prelude.</p>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_model_configuration">Model Configuration</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Sail includes a configuration system that allows building
specifications that can be configured at either runtime (if supported
by the Sail backend in use) or statically at build-time using a set of
options.</p>
</div>
<div class="paragraph">
<p>From the perspective of the specification author, one uses the
<code>config</code> construct to include a value in the specification, for
example:</p>
</div>
<div id="conf-example1" class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="k">let</span><span class="w"> </span><span class="n">some_value</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="n">string</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">config</span><span class="w"> </span><span class="n">foo</span><span class="o">.</span><span class="n">bar</span><span class="p">;</span><span class="w">
</span><span class="n">print_endline</span><span class="p">(</span><span class="n">some_value</span><span class="p">);</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>The configuration is some key-value store with dot-separated
hierachical keys, so we access the value stored at <code>foo.bar</code> key as
some string value. In practice, we use JSON to represent these
configurations. In this example, the JSON might look something like:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="json"><span class="p">{</span><span class="w">
    </span><span class="nl">"foo"</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w">
        </span><span class="nl">"bar"</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="s2">"Hello, World!"</span><span class="w">
    </span><span class="p">}</span><span class="w">
</span><span class="p">}</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>Which when used will cause the specification to print <code>"Hello,
World!"</code>. If we want to statically apply this configuration (and
convert the Sail source to OCaml), we could run the following,
assuming the configration file is called <code>file.json</code> and the Sail file
containing the above code is <code>file.sail</code>.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="console"><span class="gp">$</span><span class="w"> </span>sail <span class="nt">--ocaml</span> <span class="nt">--config</span> file.json file.sail</code></pre>
</div>
</div>
<div class="sect2">
<h3 id="_json_representation_of_sail_types">JSON representation of Sail types</h3>
<div class="paragraph">
<p>The following example demonstrates how basic Sail types are
represented in the JSON configuration file. We can load integers,
booleans, and strings, all of which correspond directly to the
equivalent JSON type. Integers are allowed to be arbitrary precision,
as they are in Sail.</p>
</div>
<div id="confbasic-example" class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="w">  </span><span class="k">let</span><span class="w"> </span><span class="n">some_string</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="n">string</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">config</span><span class="w"> </span><span class="n">some</span><span class="o">.</span><span class="n">string_value</span><span class="p">;</span><span class="w">
  </span><span class="n">print_endline</span><span class="p">(</span><span class="n">some_string</span><span class="p">);</span><span class="w">

  </span><span class="c">// Booleans are represented as JSON booleans</span><span class="w">
  </span><span class="k">let</span><span class="w"> </span><span class="n">some_bool</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="kt">bool</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">config</span><span class="w"> </span><span class="n">some</span><span class="o">.</span><span class="n">bool_value</span><span class="p">;</span><span class="w">
  </span><span class="k">if</span><span class="w"> </span><span class="n">some_bool</span><span class="w"> </span><span class="k">then</span><span class="w"> </span><span class="p">{</span><span class="w">
    </span><span class="n">print_endline</span><span class="p">(</span><span class="s">"some_bool is true"</span><span class="p">)</span><span class="w">
  </span><span class="p">};</span><span class="w">

  </span><span class="c">// Integers are represented as JSON integers</span><span class="w">
  </span><span class="k">let</span><span class="w"> </span><span class="n">some_int</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="kt">int</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">config</span><span class="w"> </span><span class="n">some</span><span class="o">.</span><span class="n">int_value</span><span class="p">;</span><span class="w">
  </span><span class="n">print_int</span><span class="p">(</span><span class="s">"some_int = "</span><span class="p">,</span><span class="w"> </span><span class="n">some_int</span><span class="p">);</span><span class="w">

  </span><span class="c">// Bitvectors have a few allowed representations:</span><span class="w">
  </span><span class="c">// We can use a JSON list of booleans</span><span class="w">
  </span><span class="k">let</span><span class="w"> </span><span class="n">some_bits1</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="kt">bits</span><span class="p">(</span><span class="mi">4</span><span class="p">)</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">config</span><span class="w"> </span><span class="n">some</span><span class="o">.</span><span class="n">bits_value</span><span class="o">.</span><span class="n">one</span><span class="p">;</span><span class="w">
  </span><span class="n">print_bits</span><span class="p">(</span><span class="s">"some_bits1 = "</span><span class="p">,</span><span class="w"> </span><span class="n">some_bits1</span><span class="p">);</span><span class="w">

  </span><span class="c">// That would be unwieldy for larger bitvectors, so we can</span><span class="w">
  </span><span class="c">// parse a bitvector from a string with an explicit length.</span><span class="w">
  </span><span class="k">let</span><span class="w"> </span><span class="n">some_bits2</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="kt">bits</span><span class="p">(</span><span class="mi">32</span><span class="p">)</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">config</span><span class="w"> </span><span class="n">some</span><span class="o">.</span><span class="n">bits_value</span><span class="o">.</span><span class="n">two</span><span class="p">;</span><span class="w">
  </span><span class="n">print_bits</span><span class="p">(</span><span class="s">"some_bits2 = "</span><span class="p">,</span><span class="w"> </span><span class="n">some_bits2</span><span class="p">);</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>The following JSON can be used to instantiate the above Sail source:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="json"><span class="p">{</span><span class="w">
    </span><span class="nl">"some"</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w">
        </span><span class="nl">"string_value"</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="s2">"A string value"</span><span class="p">,</span><span class="w">
        </span><span class="nl">"bool_value"</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span><span class="w">
        </span><span class="nl">"int_value"</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="mi">48527836473615487354835566752135643523565426</span><span class="p">,</span><span class="w">
        </span><span class="nl">"bits_value"</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w">
            </span><span class="nl">"one"</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="kc">true</span><span class="p">,</span><span class="w"> </span><span class="kc">false</span><span class="p">,</span><span class="w"> </span><span class="kc">false</span><span class="p">,</span><span class="w"> </span><span class="kc">true</span><span class="p">],</span><span class="w">
            </span><span class="nl">"two"</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nl">"len"</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="mi">32</span><span class="p">,</span><span class="w"> </span><span class="nl">"value"</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="s2">"0xFF"</span><span class="w"> </span><span class="p">}</span><span class="w">
        </span><span class="p">}</span><span class="w">
    </span><span class="p">}</span><span class="w">
</span><span class="p">}</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>Note the two permissible representations for bitvectors. First, we can
represent them as a list of JSON booleans. This representation has the
advantage of being simple and unambiguous regarding the length of the
bitvector, but is verbose. Second, we can use a string containing the
bitvector value formatted as a Sail bitvector literal (so <code>_</code>
can be used as a separator) with an explicit integer length. If the
value is shorter than the desired width it will be zero-extended. If
it is larger then any high bits above the stated width will be ignored
(care should be taken to avoid this). In addition to <code>0b</code> and <code>0x</code>
prefixed literals, a decimal value can also be used (also supporting
<code>_</code> separators), for example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="json"><span class="p">{</span><span class="w"> </span><span class="nl">"len"</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="mi">32</span><span class="p">,</span><span class="w"> </span><span class="nl">"value"</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="s2">"1_000_000"</span><span class="w"> </span><span class="p">}</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>There are some cases where a specification might need many
configuration options. Consider the case of RISC-V PMP registers,
where there are up to 64 such registers, and each one might be
configured differently. To support this, we allow reading sequences of
JSON values into Sail vectors and lists. For example:</p>
</div>
<div id="confvec-example" class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="w">  </span><span class="k">let</span><span class="w"> </span><span class="n">some_vector</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="n">vector</span><span class="p">(</span><span class="mi">5</span><span class="p">,</span><span class="w"> </span><span class="kt">int</span><span class="p">)</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">config</span><span class="w"> </span><span class="n">some</span><span class="o">.</span><span class="n">json_list</span><span class="p">;</span><span class="w">

  </span><span class="c">// We can also read the configuration value into a Sail list</span><span class="w">
  </span><span class="k">let</span><span class="w"> </span><span class="n">some_list</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="n">list</span><span class="p">(</span><span class="kt">int</span><span class="p">)</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">config</span><span class="w"> </span><span class="n">some</span><span class="o">.</span><span class="n">json_list</span><span class="p">;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>with the configuration file:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="json"><span class="p">{</span><span class="w">
    </span><span class="nl">"some"</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w">
        </span><span class="nl">"json_list"</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="mi">1</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="mi">3</span><span class="p">,</span><span class="w"> </span><span class="mi">4</span><span class="p">,</span><span class="w"> </span><span class="mi">5</span><span class="p">]</span><span class="w">
    </span><span class="p">}</span><span class="w">
</span><span class="p">}</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>More complex user defined types can also be read from the
configuration file. For example, one can read a struct value:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="k">struct</span><span class="w"> </span><span class="n">my_struct</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">{</span><span class="w">
  </span><span class="n">field1</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="kt">int</span><span class="p">,</span><span class="w">
  </span><span class="n">field2</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="n">string</span><span class="p">,</span><span class="w">
</span><span class="p">}</span><span class="w">

</span><span class="k">function</span><span class="w"> </span><span class="nf">example1</span><span class="p">()</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">{</span><span class="w">
  </span><span class="k">let</span><span class="w"> </span><span class="n">v</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="n">my_struct</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">config</span><span class="w"> </span><span class="n">some</span><span class="o">.</span><span class="n">json_struct</span><span class="p">;</span><span class="w">
  </span><span class="n">print_endline</span><span class="p">(</span><span class="n">v</span><span class="o">.</span><span class="n">field2</span><span class="p">);</span><span class="w">
</span><span class="p">}</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>or a union value:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="k">union</span><span class="w"> </span><span class="n">my_union</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">{</span><span class="w">
  </span><span class="n">Constructor1</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="kt">int</span><span class="p">,</span><span class="w">
  </span><span class="n">Constructor2</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="n">string</span><span class="p">,</span><span class="w">
</span><span class="p">}</span><span class="w">

</span><span class="k">function</span><span class="w"> </span><span class="nf">example2</span><span class="p">()</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">{</span><span class="w">
  </span><span class="k">let</span><span class="w"> </span><span class="n">v</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="n">my_union</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">config</span><span class="w"> </span><span class="n">some</span><span class="o">.</span><span class="n">json_union</span><span class="p">;</span><span class="w">
  </span><span class="k">match</span><span class="w"> </span><span class="n">v</span><span class="w"> </span><span class="p">{</span><span class="w">
    </span><span class="n">Constructor1</span><span class="p">(</span><span class="n">n</span><span class="p">)</span><span class="w"> </span><span class="p">=</span><span class="o">&gt;</span><span class="w"> </span><span class="n">print_int</span><span class="p">(</span><span class="s">"Got integer "</span><span class="p">,</span><span class="w"> </span><span class="n">n</span><span class="p">),</span><span class="w">
    </span><span class="n">Constructor2</span><span class="p">(</span><span class="n">message</span><span class="p">)</span><span class="w"> </span><span class="p">=</span><span class="o">&gt;</span><span class="w"> </span><span class="n">print_endline</span><span class="p">(</span><span class="n">message</span><span class="p">),</span><span class="w">
  </span><span class="p">}</span><span class="w">
</span><span class="p">}</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>from the configuration file:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="json"><span class="p">{</span><span class="w">
    </span><span class="nl">"some"</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w">
        </span><span class="nl">"json_struct"</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w">
            </span><span class="nl">"field1"</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="mi">3287589457</span><span class="p">,</span><span class="w">
            </span><span class="nl">"field2"</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="s2">"A string value"</span><span class="w">
        </span><span class="p">},</span><span class="w">
        </span><span class="nl">"json_union"</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w">
            </span><span class="nl">"Constructor2"</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="s2">"Another string value"</span><span class="w">
        </span><span class="p">}</span><span class="w">
    </span><span class="p">}</span><span class="w">
</span><span class="p">}</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>A Sail struct is represented as a JSON object with keys and values for
each field in the struct. There must be a key in the JSON object for
every field. A Sail union is represented as a JSON object with exactly
one key/value pair. The key must be the name of a constructor in the
union, and the value is parsed as the type of the constructor
argument.</p>
</div>
</div>
<div class="sect2">
<h3 id="_runtime_configuration_with_sail_to_c">Runtime Configuration with Sail to C</h3>
<div class="paragraph">
<p>The runtime configuration functions are included in the
<code>sail_config.h</code> header in the <code>lib/json</code> subdirectory of the Sail
distribution. The <code>sail_config_set_file</code> function loads a
configuration, and should be called before running any code in a
configurable model. The loaded configuration data can be freed by
using the <code>sail_config_cleanup</code> function.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="c"><span class="kt">void</span> <span class="nf">sail_config_set_file</span><span class="p">(</span><span class="k">const</span> <span class="kt">char</span> <span class="o">*</span><span class="n">path</span><span class="p">);</span>

<span class="kt">void</span> <span class="nf">sail_config_cleanup</span><span class="p">(</span><span class="kt">void</span><span class="p">);</span></code></pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_configurable_abstract_types">Configurable abstract types</h3>
<div class="paragraph">
<p>The <a href="#_abstract_types">Abstract types</a> section we described how to write a type like
<code>xlen</code> below without providing a concrete value, in such a way that
the specification is parametric over the choice of <code>xlen</code>.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="k">type</span><span class="w"> </span><span class="n">xlen</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="kt">Int</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>In practice, we likely want to configure this type to have some
specific value at runtime. This can be done by associating a
configuration option with the abstract type as</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="k">type</span><span class="w"> </span><span class="n">xlen</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="kt">Int</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">config</span><span class="w"> </span><span class="n">arch</span><span class="o">.</span><span class="n">xlen</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>which could be instantiated using the following configuration JSON</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="json"><span class="p">{</span><span class="w"> </span><span class="nl">"arch"</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nl">"xlen"</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="mi">32</span><span class="w"> </span><span class="p">}</span><span class="w"> </span><span class="p">}</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>We can then create (configurable) bitvector values of length <code>xlen</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="k">let</span><span class="w"> </span><span class="n">x</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="kt">bits</span><span class="p">(</span><span class="n">xlen</span><span class="p">)</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">config</span><span class="w"> </span><span class="n">some</span><span class="o">.</span><span class="n">bitvector_value</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>In the configuration file, we specify these by using the string
<code>"xlen"</code> as the length:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="json"><span class="p">{</span><span class="w"> </span><span class="nl">"some"</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nl">"bitvector_value"</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nl">"len"</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="s2">"xlen"</span><span class="p">,</span><span class="w"> </span><span class="nl">"value"</span><span class="p">:</span><span class="w"> </span><span class="s2">"0xFFFF_FFFF"</span><span class="w"> </span><span class="p">}</span><span class="w"> </span><span class="p">}</span><span class="w"> </span><span class="p">}</span></code></pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_validating_configurations_with_json_schema">Validating Configurations with JSON Schema</h3>
<div class="paragraph">
<p>Above, we discussed how JSON values are mapped onto Sail types, but
some questions remain:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>What happens if the configuration we pass at runtime contains impossible values?</p>
</li>
<li>
<p>Are all Sail types representable in the JSON configuration?</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>Note that what we are defining here will necessarily be a weaker
notion (i.e. more permissive in the configurations that are possible)
than one might consider as the valid configuration space for an ISA
definition, as it cannot capture all possible dependencies between different
configuration options.</p>
</div>
<div class="paragraph">
<p>What we want to do is capture is some basic notion of <em>safety</em>, i.e.
what values can we pass into the model at runtime that won&#8217;t break
Sail&#8217;s typing rules. For example, we might have:</p>
</div>
<div id="confschema-example" class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="k">let</span><span class="w"> </span><span class="n">n</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="mi">32</span><span class="p">,</span><span class="w"> </span><span class="mi">64</span><span class="p">}</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">config</span><span class="w"> </span><span class="n">some</span><span class="o">.</span><span class="n">integer</span><span class="p">;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>Then, using the configuration</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="json"><span class="p">{</span><span class="w">
    </span><span class="nl">"some"</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w">
        </span><span class="nl">"integer"</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="mi">72</span><span class="w">
    </span><span class="p">}</span><span class="w">
</span><span class="p">}</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>we would potentially have some serious problems. Sail could optimize
the source using the type annotation that <code>n</code> is only 32 or 64, so
when we pass 72 at runtime, type-safety would be violated and the
model could potentially fail or even exhibit undefined-behaviour when
compiled to C! Naturally, we want a way to prevent this from occuring.</p>
</div>
<div class="paragraph">
<p>To do this we create a <a href="https://json-schema.org">JSON schema</a> from the
way in which the Sail source interacts with the model. JSON schema is
an open standard with a wide variety of validators and tooling written
in multiple languages.</p>
</div>
<div class="paragraph">
<p>For the above simple example, the following schema will be generated
by Sail when using the <code>--output-schema</code> option:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="json"><span class="p">{</span><span class="w">
  </span><span class="nl">"$schema"</span><span class="p">:</span><span class="w"> </span><span class="s2">"https://json-schema.org/draft/2020-12/schema"</span><span class="p">,</span><span class="w">
  </span><span class="nl">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"object"</span><span class="p">,</span><span class="w">
  </span><span class="nl">"properties"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w">
    </span><span class="nl">"some"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w">
      </span><span class="nl">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"object"</span><span class="p">,</span><span class="w">
      </span><span class="nl">"properties"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w">
        </span><span class="nl">"integer"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w">
          </span><span class="nl">"description"</span><span class="p">:</span><span class="w"> </span><span class="s2">"../examples/config_schema.sail:8.21-8.40"</span><span class="p">,</span><span class="w">
          </span><span class="nl">"anyOf"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="w">
            </span><span class="p">{</span><span class="w"> </span><span class="nl">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"integer"</span><span class="p">,</span><span class="w"> </span><span class="nl">"const"</span><span class="p">:</span><span class="w"> </span><span class="mi">32</span><span class="w"> </span><span class="p">},</span><span class="w">
            </span><span class="p">{</span><span class="w"> </span><span class="nl">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"integer"</span><span class="p">,</span><span class="w"> </span><span class="nl">"const"</span><span class="p">:</span><span class="w"> </span><span class="mi">64</span><span class="w"> </span><span class="p">}</span><span class="w">
          </span><span class="p">]</span><span class="w">
        </span><span class="p">}</span><span class="w">
      </span><span class="p">},</span><span class="w">
      </span><span class="nl">"required"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="w"> </span><span class="s2">"integer"</span><span class="w"> </span><span class="p">]</span><span class="w">
    </span><span class="p">}</span><span class="w">
  </span><span class="p">},</span><span class="w">
  </span><span class="nl">"required"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="w"> </span><span class="s2">"some"</span><span class="w"> </span><span class="p">]</span><span class="w">
</span><span class="p">}</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>Now if we attempt to validate the above schema using the JSON
containing 72 as the value for the integer, we will get an error</p>
</div>
<div class="listingblock">
<div class="content">
<pre>schema sail_schema/config_schema.json: ok

instance sail_config/config_schema.json: failed
- at '/some/integer': anyOf failed
  - at '/some/integer': value must be 32
  - at '/some/integer': value must be 64</pre>
</div>
</div>
<div class="paragraph">
<p>In general, whenever we have <code>config key : T</code> in the Sail source, we
require that the type <code>T</code> can be converted into a JSON schema, and
raise an error if this is not possible.</p>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_modular_sail_specifications">Modular Sail Specifications</h2>
<div class="sectionbody">
<div class="sect2">
<h3 id="_modules">Modules</h3>
<div class="paragraph">
<p>Sail provides support for organizing large specifications into
<em>modules</em>. Modules provide an access control mechanism, meaning a Sail
definition in one module cannot access or use definitions provided by
another module unless it explicitly <em>requires</em> the other module.</p>
</div>
<div class="paragraph">
<p>The module structure of a Sail project/specification is specified in a
separate <code>.sail_project</code> file.</p>
</div>
<div class="paragraph">
<p>For a simple example, let&#8217;s assume we have two Sail files <code>amod.sail</code> and
<code>bmod.sail</code>:</p>
</div>
<div class="listingblock">
<div class="title"><code>amod.sail</code></div>
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="k">val</span><span class="w"> </span><span class="nf">alfa</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="kt">unit</span><span class="w"> </span><span class="p">-&gt;</span><span class="w"> </span><span class="kt">int</span><span class="w">

</span><span class="k">function</span><span class="w"> </span><span class="nf">alfa</span><span class="p">()</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="mi">3</span></code></pre>
</div>
</div>
<div class="listingblock">
<div class="title"><code>bmod.sail</code></div>
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="k">val</span><span class="w"> </span><span class="nf">bravo</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="kt">unit</span><span class="w"> </span><span class="p">-&gt;</span><span class="w"> </span><span class="kt">unit</span><span class="w">

</span><span class="k">function</span><span class="w"> </span><span class="nf">bravo</span><span class="p">()</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">{</span><span class="w">
    </span><span class="k">let</span><span class="w"> </span><span class="n">x</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">alfa</span><span class="p">();</span><span class="w">
    </span><span class="n">print_int</span><span class="p">(</span><span class="s">"alfa returned: "</span><span class="p">,</span><span class="w"> </span><span class="n">x</span><span class="p">)</span><span class="w">
</span><span class="p">}</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>We can use the following <code>.sail_project</code> file:</p>
</div>
<div class="listingblock">
<div class="title"><code>simple_mod.sail_project</code></div>
<div class="content">
<pre class="rouge highlight"><code>A {
  files amod.sail
}

B {
  requires A
  files bmod.sail
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>This file defines two modules <code>A</code> and <code>B</code>, with module <code>A</code> containing
the file <code>amod.sail</code> and module B containing the file <code>bmod.sail</code>.
Module <code>B</code> requires module <code>A</code>, so it can use the <code>alfa</code> function
defined in <code>A</code>. What would happen if we removed the requires line? We
would get the following error:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code>Type error:
../examples/bmod.sail:6.12-16:
6 |    let x = alfa();
  |            ^--^
  | Not in scope
  | 
  | Try requiring module A to bring the following into scope for module B:
  | ../examples/amod.sail:6.4-8:
  | 6 |val alfa : unit -&gt; int
  |   |    ^--^ definition here in A
  | ../examples/simple_mod_err.sail_project:5.0-1:
  | 5 |B {
  |   |^ add 'requires A' within B here</code></pre>
</div>
</div>
<div class="paragraph">
<p>This error tells us that <code>alfa</code> is not in scope, but Sail knows it
exists as it has already checked module <code>A</code>, so it points us at the
definition and suggests how we could resolve the error by adding the
requires line we just removed.</p>
</div>
<div class="paragraph">
<p>When using a <code>.sail_project</code> file we do not have to pass all the files
on the command line, so we can invoke Sail simply as</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="shell">sail simple_mod.sail_project</code></pre>
</div>
</div>
<div class="paragraph">
<p>and it will know where to find <code>amod.sail</code> and <code>bmod.sail</code> relative to
the location of the project file.</p>
</div>
<div class="paragraph">
<p>A module can have more than one Sail file. These files are processed
sequentially in the order they are listed. This is exactly like what
happens when we pass multiple Sail files on the command line without a
<code>.sail_project</code> file to define the module structure. A module can
therefore be thought of as a sequence of Sail files that is treated as
a single logical unit. As an example, we could add a third module to
our above file, which is comprised of three Sail files and depends on
A and B.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code>C {
  requires A, B
  files
    foo.sail,
    bar.sail,
    baz.sail
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>Note that comments and trailing commas are allowed, and we could optionally delimit
the lists using <code>[</code> and <code>]</code>, like so:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code>C {
  // Require both our previous modules
  requires [A, B]
  /* Both types of Sail comments are allowed! */
  files [
    foo.sail,
    bar.sail,
    baz.sail,
  ]
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>If we wanted to we could define <code>C</code> in a separate file, rather than
adding it to our previous file, and pass multiple project files to
Sail like so:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="shell">sail simple_mod.sail_project new_file_with_C.sail_project</code></pre>
</div>
</div>
<div class="paragraph">
<p>These will be treated together as a single large project file. A use
case might be if you were defining an out-of-tree extension <code>Xfoo</code> for
sail-riscv, you could do something like:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="shell">sail sail-riscv/riscv.sail_project src/Xfoo.sail_project</code></pre>
</div>
</div>
<div class="paragraph">
<p>and the modules you define in <code>Xfoo.sail_project</code> can require modules
from <code>riscv.sail_project</code>, and also vice-versa, although it makes less
sense in this example.</p>
</div>
</div>
<div class="sect2">
<h3 id="_working_with_makefiles">Working with Makefiles</h3>
<div class="paragraph">
<p>The <code>--list-files</code> option can be used to list all the files within a
project file, which allows them to be used in a Makefile prerequisite.
As an example, to build the module examples in this very manual, we
use the rule below to generate documentation indexes (which our
Asciidoctor plugin consumes) for every <code>.sail</code> file within a project
file.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight nowrap"><code data-lang="make"><span class="nl">.SECONDEXPANSION</span><span class="o">:</span>

<span class="nl">module_sail_doc/%.json</span><span class="o">:</span> <span class="nf">../examples/%.sail_project $$(shell sail ../examples/%.sail_project -list_files)</span>
	<span class="nb">mkdir</span> <span class="nt">-p</span> module_sail_doc
	sail <span class="nt">--doc</span> <span class="p">$(</span>addprefix <span class="nt">-doc_file</span> ,<span class="p">$(</span>shell sail <span class="nv">$&lt;</span> <span class="nt">--list-files</span><span class="p">))</span> <span class="nt">--doc-embed</span> plain <span class="nt">--doc-bundle</span> <span class="p">$(</span>notdir <span class="nv">$@</span><span class="p">)</span> <span class="nt">-o</span> module_sail_doc <span class="nv">$&lt;</span></code></pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_conditional_compilation_within_modules">Conditional compilation within modules</h3>
<div class="paragraph">
<p>We can use <em>variables</em> in our project files to control either file
inclusion within a module or to control whether a module requires
another or not. A variable can even contain a sequence of modules,
that can then be used in a require statement, as shown in the
following example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code>variable ARCH = A64
variable ARCH_MODULES = if ARCH == A64 then arch64_only else []

arch_prelude {
  files
    prelude.sail,
    if $ARCH == A32 then arch_xlen32.sail
    else if $ARCH == A64 then [
      arch_xlen64.sail,
      arch_xlen64_helpers.sail
    ] else error("Invalid value for ARCH")
}

arch64_only {
  requires arch_prelude
  files
    instructions64.sail
}

arch_instructions {
  requires arch_prelude
  files
    instructions.sail
}

arch_end {
  requires arch_instructions, $ARCH_MODULES
  files
    end.sail
}</code></pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_optional_and_default_modules">Optional and default modules</h3>
<div class="paragraph">
<p>Modules can be marked as either <code>optional</code> or <code>default</code>. Default
modules are those that form the base part of a specification, whereas
optional modules are intended to implement extensions which may or may
not be present. Default modules cannot require optional modules.</p>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_the_sail_grammar">The Sail Grammar</h2>
<div class="sectionbody">
<div class="paragraph">
<p>This appendix contains a grammar for the Sail language that is
automatically generated from the
<a href="https://gallium.inria.fr/~fpottier/menhir">Menhir</a> parser definition.</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">
This means that the grammar is stated in such a way that the
parser generator can see it is free of LR shift/reduce and
reduce/reduce conflicts, rather than being optimised for human
readability.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>First, we need some lexical conventions:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>ID</code> is any valid Sail identifier</p>
</li>
<li>
<p><code>OPERATOR</code> is any valid Sail operator, as defined in <a href="#_operators">Operators</a>.</p>
</li>
<li>
<p><code>TYPE_VARIABLE</code> is a valid Sail identifier with a leading single quote <code>'</code>.</p>
</li>
<li>
<p><code>NUMBER</code> is a non-empty sequence of decimal digits <code>[0-9]+</code>.</p>
</li>
<li>
<p><code>HEXADECIMAL_LITERAL</code> is <code>0x[A-Ba-f0-9_]+</code></p>
</li>
<li>
<p><code>BINARY_LITERAL</code> is <code>0b[0-1_]+</code></p>
</li>
<li>
<p><code>STRING_LITERAL</code> is a Sail string literal.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p><code>$[ATTRIBUTE]</code> and <code>$LINE_DIRECTIVE</code> represent attributes and single
line directives. Examples of line directives would be things like
<code>$include</code>, <code>$ifdef</code> and so on. These start with a leading <code>$</code>, are
followed by the directive name (which follows the same lexical rules
as a Sail identifier), is followed by one or more spaces, then
proceeds to the end of the line, with everything between the
identifier and the line ending being the line directive&#8217;s argument
(with leading and trailing whitespace removed). An attribute starts
with <code>$[</code> and ends with <code>]</code>, and in between consists of an attribute
name, followed by at least one whitespace character, then any
arbitrary sequence of characters that does not contain <code>]</code>.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sail"><span class="o">&lt;</span><span class="n">separated_nonempty_list_trailing</span><span class="p">(</span><span class="n">SEP</span><span class="p">,</span><span class="w"> </span><span class="n">ELEM</span><span class="p">)</span><span class="o">&gt;</span><span class="w"> </span><span class="p">::=</span><span class="w"> </span><span class="n">ELEM</span><span class="w"> </span><span class="p">[</span><span class="n">SEP</span><span class="p">]</span><span class="w">
                                                </span><span class="o">|</span><span class="w"> </span><span class="n">ELEM</span><span class="w"> </span><span class="n">SEP</span><span class="w"> </span><span class="o">&lt;</span><span class="n">separated_nonempty_list_trailing</span><span class="p">(</span><span class="n">SEP</span><span class="p">,</span><span class="w"> </span><span class="n">ELEM</span><span class="p">)</span><span class="o">&gt;</span><span class="w">

</span><span class="o">&lt;</span><span class="n">id</span><span class="o">&gt;</span><span class="w"> </span><span class="p">::=</span><span class="w"> </span><span class="n">ID</span><span class="w">
       </span><span class="o">|</span><span class="w"> </span><span class="k">operator</span><span class="w"> </span><span class="n">OPERATOR</span><span class="w">
       </span><span class="o">|</span><span class="w"> </span><span class="k">operator</span><span class="w"> </span><span class="o">-</span><span class="w">
       </span><span class="o">|</span><span class="w"> </span><span class="k">operator</span><span class="w"> </span><span class="o">|</span><span class="w">
       </span><span class="o">|</span><span class="w"> </span><span class="k">operator</span><span class="w"> </span><span class="o">^</span><span class="w">
       </span><span class="o">|</span><span class="w"> </span><span class="k">operator</span><span class="w"> </span><span class="o">*</span><span class="w">

</span><span class="o">&lt;</span><span class="n">op_no_caret</span><span class="o">&gt;</span><span class="w"> </span><span class="p">::=</span><span class="w"> </span><span class="n">OPERATOR</span><span class="w">
                </span><span class="o">|</span><span class="w"> </span><span class="o">-</span><span class="w">
                </span><span class="o">|</span><span class="w"> </span><span class="o">|</span><span class="w">
                </span><span class="o">|</span><span class="w"> </span><span class="o">*</span><span class="w">
                </span><span class="o">|</span><span class="w"> </span><span class="k">in</span><span class="w">

</span><span class="o">&lt;</span><span class="n">op</span><span class="o">&gt;</span><span class="w"> </span><span class="p">::=</span><span class="w"> </span><span class="n">OPERATOR</span><span class="w">
       </span><span class="o">|</span><span class="w"> </span><span class="o">-</span><span class="w">
       </span><span class="o">|</span><span class="w"> </span><span class="o">|</span><span class="w">
       </span><span class="o">|</span><span class="w"> </span><span class="o">^</span><span class="w">
       </span><span class="o">|</span><span class="w"> </span><span class="o">*</span><span class="w">
       </span><span class="o">|</span><span class="w"> </span><span class="k">in</span><span class="w">

</span><span class="o">&lt;</span><span class="n">exp_op</span><span class="o">&gt;</span><span class="w"> </span><span class="p">::=</span><span class="w"> </span><span class="n">OPERATOR</span><span class="w">
           </span><span class="o">|</span><span class="w"> </span><span class="o">-</span><span class="w">
           </span><span class="o">|</span><span class="w"> </span><span class="o">|</span><span class="w">
           </span><span class="o">|</span><span class="w"> </span><span class="p">@</span><span class="w">
           </span><span class="o">|</span><span class="w"> </span><span class="p">::</span><span class="w">
           </span><span class="o">|</span><span class="w"> </span><span class="o">^</span><span class="w">
           </span><span class="o">|</span><span class="w"> </span><span class="o">*</span><span class="w">

</span><span class="o">&lt;</span><span class="n">pat_op</span><span class="o">&gt;</span><span class="w"> </span><span class="p">::=</span><span class="w"> </span><span class="p">@</span><span class="w">
           </span><span class="o">|</span><span class="w"> </span><span class="p">::</span><span class="w">
           </span><span class="o">|</span><span class="w"> </span><span class="o">^</span><span class="w">

</span><span class="o">&lt;</span><span class="n">typ_var</span><span class="o">&gt;</span><span class="w"> </span><span class="p">::=</span><span class="w"> </span><span class="n">TYPE_VARIABLE</span><span class="w">

</span><span class="o">&lt;</span><span class="n">tyarg</span><span class="o">&gt;</span><span class="w"> </span><span class="p">::=</span><span class="w"> </span><span class="p">(</span><span class="w"> </span><span class="o">&lt;</span><span class="n">typ_list</span><span class="o">&gt;</span><span class="w"> </span><span class="p">)</span><span class="w">


</span><span class="o">&lt;</span><span class="n">prefix_typ_op</span><span class="o">&gt;</span><span class="w"> </span><span class="p">::=</span><span class="w"> </span><span class="n">epsilon</span><span class="w">
                  </span><span class="o">|</span><span class="w"> </span><span class="mi">2</span><span class="o">^</span><span class="w">
                  </span><span class="o">|</span><span class="w"> </span><span class="o">-</span><span class="w">
                  </span><span class="o">|</span><span class="w"> </span><span class="o">*</span><span class="w">

</span><span class="o">&lt;</span><span class="n">postfix_typ</span><span class="o">&gt;</span><span class="w"> </span><span class="p">::=</span><span class="w"> </span><span class="o">&lt;</span><span class="n">atomic_typ</span><span class="o">&gt;</span><span class="w">

</span><span class="o">&lt;</span><span class="n">typ_no_caret</span><span class="o">&gt;</span><span class="w"> </span><span class="p">::=</span><span class="w"> </span><span class="o">&lt;</span><span class="n">prefix_typ_op</span><span class="o">&gt;</span><span class="w"> </span><span class="o">&lt;</span><span class="n">postfix_typ</span><span class="o">&gt;</span><span class="w"> </span><span class="p">(</span><span class="o">&lt;</span><span class="n">op_no_caret</span><span class="o">&gt;</span><span class="w"> </span><span class="o">&lt;</span><span class="n">prefix_typ_op</span><span class="o">&gt;</span><span class="w"> </span><span class="o">&lt;</span><span class="n">postfix_typ</span><span class="o">&gt;</span><span class="p">)</span><span class="o">*</span><span class="w">

</span><span class="o">&lt;</span><span class="n">typ</span><span class="o">&gt;</span><span class="w"> </span><span class="p">::=</span><span class="w"> </span><span class="k">if</span><span class="w"> </span><span class="o">&lt;</span><span class="n">infix_typ</span><span class="o">&gt;</span><span class="w"> </span><span class="k">then</span><span class="w"> </span><span class="o">&lt;</span><span class="n">infix_typ</span><span class="o">&gt;</span><span class="w"> </span><span class="k">else</span><span class="w"> </span><span class="o">&lt;</span><span class="n">typ</span><span class="o">&gt;</span><span class="w">
        </span><span class="o">|</span><span class="w"> </span><span class="o">&lt;</span><span class="n">infix_typ</span><span class="o">&gt;</span><span class="w">

</span><span class="o">&lt;</span><span class="n">infix_typ</span><span class="o">&gt;</span><span class="w"> </span><span class="p">::=</span><span class="w"> </span><span class="o">&lt;</span><span class="n">prefix_typ_op</span><span class="o">&gt;</span><span class="w"> </span><span class="o">&lt;</span><span class="n">postfix_typ</span><span class="o">&gt;</span><span class="w"> </span><span class="p">(</span><span class="o">&lt;</span><span class="n">op</span><span class="o">&gt;</span><span class="w"> </span><span class="o">&lt;</span><span class="n">prefix_typ_op</span><span class="o">&gt;</span><span class="w"> </span><span class="o">&lt;</span><span class="n">postfix_typ</span><span class="o">&gt;</span><span class="p">)</span><span class="o">*</span><span class="w">

</span><span class="o">&lt;</span><span class="n">atomic_typ</span><span class="o">&gt;</span><span class="w"> </span><span class="p">::=</span><span class="w"> </span><span class="o">&lt;</span><span class="n">id</span><span class="o">&gt;</span><span class="w">
               </span><span class="o">|</span><span class="w"> </span><span class="mi">_</span><span class="w">
               </span><span class="o">|</span><span class="w"> </span><span class="o">&lt;</span><span class="n">typ_var</span><span class="o">&gt;</span><span class="w">
               </span><span class="o">|</span><span class="w"> </span><span class="o">&lt;</span><span class="n">lit</span><span class="o">&gt;</span><span class="w">
               </span><span class="o">|</span><span class="w"> </span><span class="kt">dec</span><span class="w">
               </span><span class="o">|</span><span class="w"> </span><span class="kt">inc</span><span class="w">
               </span><span class="o">|</span><span class="w"> </span><span class="o">&lt;</span><span class="n">id</span><span class="o">&gt;</span><span class="w"> </span><span class="o">&lt;</span><span class="n">tyarg</span><span class="o">&gt;</span><span class="w">
               </span><span class="o">|</span><span class="w"> </span><span class="k">register</span><span class="w"> </span><span class="p">(</span><span class="w"> </span><span class="o">&lt;</span><span class="n">typ</span><span class="o">&gt;</span><span class="w"> </span><span class="p">)</span><span class="w">
               </span><span class="o">|</span><span class="w"> </span><span class="p">(</span><span class="w"> </span><span class="o">&lt;</span><span class="n">typ</span><span class="o">&gt;</span><span class="w"> </span><span class="p">)</span><span class="w">
               </span><span class="o">|</span><span class="w"> </span><span class="p">(</span><span class="w"> </span><span class="o">&lt;</span><span class="n">typ</span><span class="o">&gt;</span><span class="w"> </span><span class="p">,</span><span class="w"> </span><span class="o">&lt;</span><span class="n">typ_list</span><span class="o">&gt;</span><span class="w"> </span><span class="p">)</span><span class="w">
               </span><span class="o">|</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="n">NUMBER</span><span class="w"> </span><span class="p">(,</span><span class="w"> </span><span class="n">NUMBER</span><span class="p">)</span><span class="o">*</span><span class="w"> </span><span class="p">}</span><span class="w">
               </span><span class="o">|</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="o">&lt;</span><span class="n">kopt</span><span class="o">&gt;</span><span class="w"> </span><span class="o">.</span><span class="w"> </span><span class="o">&lt;</span><span class="n">typ</span><span class="o">&gt;</span><span class="w"> </span><span class="p">}</span><span class="w">
               </span><span class="o">|</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="o">&lt;</span><span class="n">kopt</span><span class="o">&gt;</span><span class="w"> </span><span class="p">,</span><span class="w"> </span><span class="o">&lt;</span><span class="n">typ</span><span class="o">&gt;</span><span class="w"> </span><span class="o">.</span><span class="w"> </span><span class="o">&lt;</span><span class="n">typ</span><span class="o">&gt;</span><span class="w"> </span><span class="p">}</span><span class="w">

</span><span class="o">&lt;</span><span class="n">typ_list</span><span class="o">&gt;</span><span class="w"> </span><span class="p">::=</span><span class="w"> </span><span class="o">&lt;</span><span class="n">typ</span><span class="o">&gt;</span><span class="w"> </span><span class="p">[,]</span><span class="w">
             </span><span class="o">|</span><span class="w"> </span><span class="o">&lt;</span><span class="n">typ</span><span class="o">&gt;</span><span class="w"> </span><span class="p">,</span><span class="w"> </span><span class="o">&lt;</span><span class="n">typ_list</span><span class="o">&gt;</span><span class="w">

</span><span class="o">&lt;</span><span class="n">kind</span><span class="o">&gt;</span><span class="w"> </span><span class="p">::=</span><span class="w"> </span><span class="n">INT</span><span class="w">
         </span><span class="o">|</span><span class="w"> </span><span class="n">NAT</span><span class="w">
         </span><span class="o">|</span><span class="w"> </span><span class="kt">Type</span><span class="w">
         </span><span class="o">|</span><span class="w"> </span><span class="n">ORDER</span><span class="w">
         </span><span class="o">|</span><span class="w"> </span><span class="n">BOOL</span><span class="w">

</span><span class="o">&lt;</span><span class="n">kopt</span><span class="o">&gt;</span><span class="w"> </span><span class="p">::=</span><span class="w"> </span><span class="p">(</span><span class="w"> </span><span class="kr">constant</span><span class="w"> </span><span class="o">&lt;</span><span class="n">typ_var</span><span class="o">&gt;</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="o">&lt;</span><span class="n">kind</span><span class="o">&gt;</span><span class="w"> </span><span class="p">)</span><span class="w">
         </span><span class="o">|</span><span class="w"> </span><span class="p">(</span><span class="w"> </span><span class="o">&lt;</span><span class="n">typ_var</span><span class="o">&gt;</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="o">&lt;</span><span class="n">kind</span><span class="o">&gt;</span><span class="w"> </span><span class="p">)</span><span class="w">
         </span><span class="o">|</span><span class="w"> </span><span class="o">&lt;</span><span class="n">typ_var</span><span class="o">&gt;</span><span class="w">

</span><span class="o">&lt;</span><span class="n">quantifier</span><span class="o">&gt;</span><span class="w"> </span><span class="p">::=</span><span class="w"> </span><span class="o">&lt;</span><span class="n">kopt</span><span class="o">&gt;</span><span class="w"> </span><span class="p">,</span><span class="w"> </span><span class="o">&lt;</span><span class="n">typ</span><span class="o">&gt;</span><span class="w">
             </span><span class="o">|</span><span class="w"> </span><span class="o">&lt;</span><span class="n">kopt</span><span class="o">&gt;</span><span class="w">


</span><span class="o">&lt;</span><span class="kr">effect</span><span class="o">&gt;</span><span class="w"> </span><span class="p">::=</span><span class="w"> </span><span class="o">&lt;</span><span class="n">id</span><span class="o">&gt;</span><span class="w">

</span><span class="o">&lt;</span><span class="n">effect_set</span><span class="o">&gt;</span><span class="w"> </span><span class="p">::=</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="o">&lt;</span><span class="kr">effect</span><span class="o">&gt;</span><span class="w"> </span><span class="p">(,</span><span class="w"> </span><span class="o">&lt;</span><span class="kr">effect</span><span class="o">&gt;</span><span class="p">)</span><span class="o">*</span><span class="w"> </span><span class="p">}</span><span class="w">
               </span><span class="o">|</span><span class="w"> </span><span class="k">pure</span><span class="w">

</span><span class="o">&lt;</span><span class="n">typschm</span><span class="o">&gt;</span><span class="w"> </span><span class="p">::=</span><span class="w"> </span><span class="o">&lt;</span><span class="n">typ</span><span class="o">&gt;</span><span class="w"> </span><span class="p">-&gt;</span><span class="w"> </span><span class="o">&lt;</span><span class="n">typ</span><span class="o">&gt;</span><span class="w">
            </span><span class="o">|</span><span class="w"> </span><span class="k">forall</span><span class="w"> </span><span class="o">&lt;</span><span class="n">quantifier</span><span class="o">&gt;</span><span class="w"> </span><span class="o">.</span><span class="w"> </span><span class="o">&lt;</span><span class="n">typ</span><span class="o">&gt;</span><span class="w"> </span><span class="p">-&gt;</span><span class="w"> </span><span class="o">&lt;</span><span class="n">typ</span><span class="o">&gt;</span><span class="w">
            </span><span class="o">|</span><span class="w"> </span><span class="o">&lt;</span><span class="n">typ</span><span class="o">&gt;</span><span class="w"> </span><span class="o">&lt;-&gt;</span><span class="w"> </span><span class="o">&lt;</span><span class="n">typ</span><span class="o">&gt;</span><span class="w">
            </span><span class="o">|</span><span class="w"> </span><span class="k">forall</span><span class="w"> </span><span class="o">&lt;</span><span class="n">quantifier</span><span class="o">&gt;</span><span class="w"> </span><span class="o">.</span><span class="w"> </span><span class="o">&lt;</span><span class="n">typ</span><span class="o">&gt;</span><span class="w"> </span><span class="o">&lt;-&gt;</span><span class="w"> </span><span class="o">&lt;</span><span class="n">typ</span><span class="o">&gt;</span><span class="w">


</span><span class="o">&lt;</span><span class="n">pat1</span><span class="o">&gt;</span><span class="w"> </span><span class="p">::=</span><span class="w"> </span><span class="o">&lt;</span><span class="n">atomic_pat</span><span class="o">&gt;</span><span class="w"> </span><span class="p">(</span><span class="o">&lt;</span><span class="n">pat_op</span><span class="o">&gt;</span><span class="w"> </span><span class="o">&lt;</span><span class="n">atomic_pat</span><span class="o">&gt;</span><span class="p">)</span><span class="o">*</span><span class="w">

</span><span class="o">&lt;</span><span class="n">pat</span><span class="o">&gt;</span><span class="w"> </span><span class="p">::=</span><span class="w"> </span><span class="o">&lt;</span><span class="n">pat1</span><span class="o">&gt;</span><span class="w">
        </span><span class="o">|</span><span class="w"> </span><span class="o">&lt;</span><span class="n">attribute</span><span class="o">&gt;</span><span class="w"> </span><span class="o">&lt;</span><span class="n">pat</span><span class="o">&gt;</span><span class="w">
        </span><span class="o">|</span><span class="w"> </span><span class="o">&lt;</span><span class="n">pat1</span><span class="o">&gt;</span><span class="w"> </span><span class="k">as</span><span class="w"> </span><span class="o">&lt;</span><span class="n">typ</span><span class="o">&gt;</span><span class="w">

</span><span class="o">&lt;</span><span class="n">pat_list</span><span class="o">&gt;</span><span class="w"> </span><span class="p">::=</span><span class="w"> </span><span class="o">&lt;</span><span class="n">pat</span><span class="o">&gt;</span><span class="w"> </span><span class="p">[,]</span><span class="w">
             </span><span class="o">|</span><span class="w"> </span><span class="o">&lt;</span><span class="n">pat</span><span class="o">&gt;</span><span class="w"> </span><span class="p">,</span><span class="w"> </span><span class="o">&lt;</span><span class="n">pat_list</span><span class="o">&gt;</span><span class="w">

</span><span class="o">&lt;</span><span class="n">atomic_pat</span><span class="o">&gt;</span><span class="w"> </span><span class="p">::=</span><span class="w"> </span><span class="mi">_</span><span class="w">
               </span><span class="o">|</span><span class="w"> </span><span class="o">&lt;</span><span class="n">lit</span><span class="o">&gt;</span><span class="w">
               </span><span class="o">|</span><span class="w"> </span><span class="o">&lt;</span><span class="n">id</span><span class="o">&gt;</span><span class="w">
               </span><span class="o">|</span><span class="w"> </span><span class="o">&lt;</span><span class="n">typ_var</span><span class="o">&gt;</span><span class="w">
               </span><span class="o">|</span><span class="w"> </span><span class="o">&lt;</span><span class="n">id</span><span class="o">&gt;</span><span class="w"> </span><span class="p">()</span><span class="w">
               </span><span class="o">|</span><span class="w"> </span><span class="o">&lt;</span><span class="n">id</span><span class="o">&gt;</span><span class="w"> </span><span class="p">[</span><span class="w"> </span><span class="n">NUMBER</span><span class="w"> </span><span class="p">]</span><span class="w">
               </span><span class="o">|</span><span class="w"> </span><span class="o">&lt;</span><span class="n">id</span><span class="o">&gt;</span><span class="w"> </span><span class="p">[</span><span class="w"> </span><span class="n">NUMBER</span><span class="w"> </span><span class="o">..</span><span class="w"> </span><span class="n">NUMBER</span><span class="w"> </span><span class="p">]</span><span class="w">
               </span><span class="o">|</span><span class="w"> </span><span class="o">&lt;</span><span class="n">id</span><span class="o">&gt;</span><span class="w"> </span><span class="p">(</span><span class="w"> </span><span class="o">&lt;</span><span class="n">pat_list</span><span class="o">&gt;</span><span class="w"> </span><span class="p">)</span><span class="w">
               </span><span class="o">|</span><span class="w"> </span><span class="o">&lt;</span><span class="n">atomic_pat</span><span class="o">&gt;</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="o">&lt;</span><span class="n">typ_no_caret</span><span class="o">&gt;</span><span class="w">
               </span><span class="o">|</span><span class="w"> </span><span class="p">(</span><span class="w"> </span><span class="o">&lt;</span><span class="n">pat</span><span class="o">&gt;</span><span class="w"> </span><span class="p">)</span><span class="w">
               </span><span class="o">|</span><span class="w"> </span><span class="p">(</span><span class="w"> </span><span class="o">&lt;</span><span class="n">pat</span><span class="o">&gt;</span><span class="w"> </span><span class="p">,</span><span class="w"> </span><span class="o">&lt;</span><span class="n">pat_list</span><span class="o">&gt;</span><span class="w"> </span><span class="p">)</span><span class="w">
               </span><span class="o">|</span><span class="w"> </span><span class="p">[</span><span class="w"> </span><span class="o">&lt;</span><span class="n">pat_list</span><span class="o">&gt;</span><span class="w"> </span><span class="p">]</span><span class="w">
               </span><span class="o">|</span><span class="w"> </span><span class="p">[|</span><span class="w"> </span><span class="p">|]</span><span class="w">
               </span><span class="o">|</span><span class="w"> </span><span class="p">[|</span><span class="w"> </span><span class="o">&lt;</span><span class="n">pat_list</span><span class="o">&gt;</span><span class="w"> </span><span class="p">|]</span><span class="w">
               </span><span class="o">|</span><span class="w"> </span><span class="k">struct</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="o">&lt;</span><span class="n">separated_nonempty_list_trailing</span><span class="p">(,,</span><span class="w"> </span><span class="o">&lt;</span><span class="n">fpat</span><span class="o">&gt;</span><span class="p">)</span><span class="o">&gt;</span><span class="w"> </span><span class="p">}</span><span class="w">

</span><span class="o">&lt;</span><span class="n">fpat</span><span class="o">&gt;</span><span class="w"> </span><span class="p">::=</span><span class="w"> </span><span class="o">&lt;</span><span class="n">id</span><span class="o">&gt;</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="o">&lt;</span><span class="n">pat</span><span class="o">&gt;</span><span class="w">
         </span><span class="o">|</span><span class="w"> </span><span class="o">&lt;</span><span class="n">id</span><span class="o">&gt;</span><span class="w">
         </span><span class="o">|</span><span class="w"> </span><span class="mi">_</span><span class="w">

</span><span class="o">&lt;</span><span class="n">lit</span><span class="o">&gt;</span><span class="w"> </span><span class="p">::=</span><span class="w"> </span><span class="nb">true</span><span class="w">
        </span><span class="o">|</span><span class="w"> </span><span class="nb">false</span><span class="w">
        </span><span class="o">|</span><span class="w"> </span><span class="p">()</span><span class="w">
        </span><span class="o">|</span><span class="w"> </span><span class="n">NUMBER</span><span class="w">
        </span><span class="o">|</span><span class="w"> </span><span class="nb">undefined</span><span class="w">
        </span><span class="o">|</span><span class="w"> </span><span class="nb">bitzero</span><span class="w">
        </span><span class="o">|</span><span class="w"> </span><span class="nb">bitone</span><span class="w">
        </span><span class="o">|</span><span class="w"> </span><span class="n">BINARY_LITERAL</span><span class="w">
        </span><span class="o">|</span><span class="w"> </span><span class="n">HEXADECIMAL_LITERAL</span><span class="w">
        </span><span class="o">|</span><span class="w"> </span><span class="n">STRING_LITERAL</span><span class="w">


</span><span class="o">&lt;</span><span class="n">exp</span><span class="o">&gt;</span><span class="w"> </span><span class="p">::=</span><span class="w"> </span><span class="o">&lt;</span><span class="n">exp0</span><span class="o">&gt;</span><span class="w">
        </span><span class="o">|</span><span class="w"> </span><span class="o">&lt;</span><span class="n">attribute</span><span class="o">&gt;</span><span class="w"> </span><span class="o">&lt;</span><span class="n">exp</span><span class="o">&gt;</span><span class="w">
        </span><span class="o">|</span><span class="w"> </span><span class="o">&lt;</span><span class="n">exp0</span><span class="o">&gt;</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="o">&lt;</span><span class="n">exp</span><span class="o">&gt;</span><span class="w">
        </span><span class="o">|</span><span class="w"> </span><span class="k">let</span><span class="w"> </span><span class="o">&lt;</span><span class="n">letbind</span><span class="o">&gt;</span><span class="w"> </span><span class="k">in</span><span class="w"> </span><span class="o">&lt;</span><span class="n">exp</span><span class="o">&gt;</span><span class="w">
        </span><span class="o">|</span><span class="w"> </span><span class="k">var</span><span class="w"> </span><span class="o">&lt;</span><span class="n">atomic_exp</span><span class="o">&gt;</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="o">&lt;</span><span class="n">exp</span><span class="o">&gt;</span><span class="w"> </span><span class="k">in</span><span class="w"> </span><span class="o">&lt;</span><span class="n">exp</span><span class="o">&gt;</span><span class="w">
        </span><span class="o">|</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="o">&lt;</span><span class="n">block</span><span class="o">&gt;</span><span class="w"> </span><span class="p">}</span><span class="w">
        </span><span class="o">|</span><span class="w"> </span><span class="k">return</span><span class="w"> </span><span class="o">&lt;</span><span class="n">exp</span><span class="o">&gt;</span><span class="w">
        </span><span class="o">|</span><span class="w"> </span><span class="k">throw</span><span class="w"> </span><span class="o">&lt;</span><span class="n">exp</span><span class="o">&gt;</span><span class="w">
        </span><span class="o">|</span><span class="w"> </span><span class="k">if</span><span class="w"> </span><span class="o">&lt;</span><span class="n">exp</span><span class="o">&gt;</span><span class="w"> </span><span class="k">then</span><span class="w"> </span><span class="o">&lt;</span><span class="n">exp</span><span class="o">&gt;</span><span class="w"> </span><span class="k">else</span><span class="w"> </span><span class="o">&lt;</span><span class="n">exp</span><span class="o">&gt;</span><span class="w">
        </span><span class="o">|</span><span class="w"> </span><span class="k">if</span><span class="w"> </span><span class="o">&lt;</span><span class="n">exp</span><span class="o">&gt;</span><span class="w"> </span><span class="k">then</span><span class="w"> </span><span class="o">&lt;</span><span class="n">exp</span><span class="o">&gt;</span><span class="w">
        </span><span class="o">|</span><span class="w"> </span><span class="k">match</span><span class="w"> </span><span class="o">&lt;</span><span class="n">exp</span><span class="o">&gt;</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="o">&lt;</span><span class="n">case_list</span><span class="o">&gt;</span><span class="w"> </span><span class="p">}</span><span class="w">
        </span><span class="o">|</span><span class="w"> </span><span class="k">try</span><span class="w"> </span><span class="o">&lt;</span><span class="n">exp</span><span class="o">&gt;</span><span class="w"> </span><span class="k">catch</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="o">&lt;</span><span class="n">case_list</span><span class="o">&gt;</span><span class="w"> </span><span class="p">}</span><span class="w">
        </span><span class="o">|</span><span class="w"> </span><span class="k">foreach</span><span class="w"> </span><span class="p">(</span><span class="w"> </span><span class="o">&lt;</span><span class="n">id</span><span class="o">&gt;</span><span class="w"> </span><span class="n">ID</span><span class="w"> </span><span class="o">&lt;</span><span class="n">atomic_exp</span><span class="o">&gt;</span><span class="w"> </span><span class="n">ID</span><span class="w"> </span><span class="o">&lt;</span><span class="n">atomic_exp</span><span class="o">&gt;</span><span class="w"> </span><span class="k">by</span><span class="w"> </span><span class="o">&lt;</span><span class="n">atomic_exp</span><span class="o">&gt;</span><span class="w"> </span><span class="k">in</span><span class="w"> </span><span class="o">&lt;</span><span class="n">typ</span><span class="o">&gt;</span><span class="w"> </span><span class="p">)</span><span class="w"> </span><span class="o">&lt;</span><span class="n">exp</span><span class="o">&gt;</span><span class="w">
        </span><span class="o">|</span><span class="w"> </span><span class="k">foreach</span><span class="w"> </span><span class="p">(</span><span class="w"> </span><span class="o">&lt;</span><span class="n">id</span><span class="o">&gt;</span><span class="w"> </span><span class="n">ID</span><span class="w"> </span><span class="o">&lt;</span><span class="n">atomic_exp</span><span class="o">&gt;</span><span class="w"> </span><span class="n">ID</span><span class="w"> </span><span class="o">&lt;</span><span class="n">atomic_exp</span><span class="o">&gt;</span><span class="w"> </span><span class="k">by</span><span class="w"> </span><span class="o">&lt;</span><span class="n">atomic_exp</span><span class="o">&gt;</span><span class="w"> </span><span class="p">)</span><span class="w"> </span><span class="o">&lt;</span><span class="n">exp</span><span class="o">&gt;</span><span class="w">
        </span><span class="o">|</span><span class="w"> </span><span class="k">foreach</span><span class="w"> </span><span class="p">(</span><span class="w"> </span><span class="o">&lt;</span><span class="n">id</span><span class="o">&gt;</span><span class="w"> </span><span class="n">ID</span><span class="w"> </span><span class="o">&lt;</span><span class="n">atomic_exp</span><span class="o">&gt;</span><span class="w"> </span><span class="n">ID</span><span class="w"> </span><span class="o">&lt;</span><span class="n">atomic_exp</span><span class="o">&gt;</span><span class="w"> </span><span class="p">)</span><span class="w"> </span><span class="o">&lt;</span><span class="n">exp</span><span class="o">&gt;</span><span class="w">
        </span><span class="o">|</span><span class="w"> </span><span class="k">repeat</span><span class="w"> </span><span class="p">[</span><span class="kr">termination_measure</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="o">&lt;</span><span class="n">exp</span><span class="o">&gt;</span><span class="w"> </span><span class="p">}]</span><span class="w"> </span><span class="o">&lt;</span><span class="n">exp</span><span class="o">&gt;</span><span class="w"> </span><span class="k">until</span><span class="w"> </span><span class="o">&lt;</span><span class="n">exp</span><span class="o">&gt;</span><span class="w">
        </span><span class="o">|</span><span class="w"> </span><span class="k">while</span><span class="w"> </span><span class="p">[</span><span class="kr">termination_measure</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="o">&lt;</span><span class="n">exp</span><span class="o">&gt;</span><span class="w"> </span><span class="p">}]</span><span class="w"> </span><span class="o">&lt;</span><span class="n">exp</span><span class="o">&gt;</span><span class="w"> </span><span class="k">do</span><span class="w"> </span><span class="o">&lt;</span><span class="n">exp</span><span class="o">&gt;</span><span class="w">

</span><span class="o">&lt;</span><span class="n">prefix_op</span><span class="o">&gt;</span><span class="w"> </span><span class="p">::=</span><span class="w"> </span><span class="n">epsilon</span><span class="w">
              </span><span class="o">|</span><span class="w"> </span><span class="mi">2</span><span class="o">^</span><span class="w">
              </span><span class="o">|</span><span class="w"> </span><span class="o">-</span><span class="w">
              </span><span class="o">|</span><span class="w"> </span><span class="o">*</span><span class="w">

</span><span class="o">&lt;</span><span class="n">exp0</span><span class="o">&gt;</span><span class="w"> </span><span class="p">::=</span><span class="w"> </span><span class="o">&lt;</span><span class="n">prefix_op</span><span class="o">&gt;</span><span class="w"> </span><span class="o">&lt;</span><span class="n">atomic_exp</span><span class="o">&gt;</span><span class="w"> </span><span class="p">(</span><span class="o">&lt;</span><span class="n">exp_op</span><span class="o">&gt;</span><span class="w"> </span><span class="o">&lt;</span><span class="n">prefix_op</span><span class="o">&gt;</span><span class="w"> </span><span class="o">&lt;</span><span class="n">atomic_exp</span><span class="o">&gt;</span><span class="p">)</span><span class="o">*</span><span class="w">

</span><span class="o">&lt;</span><span class="n">case</span><span class="o">&gt;</span><span class="w"> </span><span class="p">::=</span><span class="w"> </span><span class="o">&lt;</span><span class="n">pat</span><span class="o">&gt;</span><span class="w"> </span><span class="p">=</span><span class="o">&gt;</span><span class="w"> </span><span class="o">&lt;</span><span class="n">exp</span><span class="o">&gt;</span><span class="w">
         </span><span class="o">|</span><span class="w"> </span><span class="o">&lt;</span><span class="n">pat</span><span class="o">&gt;</span><span class="w"> </span><span class="k">if</span><span class="w"> </span><span class="o">&lt;</span><span class="n">exp</span><span class="o">&gt;</span><span class="w"> </span><span class="p">=</span><span class="o">&gt;</span><span class="w"> </span><span class="o">&lt;</span><span class="n">exp</span><span class="o">&gt;</span><span class="w">
         </span><span class="o">|</span><span class="w"> </span><span class="o">&lt;</span><span class="n">attribute</span><span class="o">&gt;</span><span class="w"> </span><span class="p">(</span><span class="w"> </span><span class="o">&lt;</span><span class="n">case</span><span class="o">&gt;</span><span class="w"> </span><span class="p">)</span><span class="w">

</span><span class="o">&lt;</span><span class="n">case_list</span><span class="o">&gt;</span><span class="w"> </span><span class="p">::=</span><span class="w"> </span><span class="o">&lt;</span><span class="n">case</span><span class="o">&gt;</span><span class="w">
              </span><span class="o">|</span><span class="w"> </span><span class="o">&lt;</span><span class="n">case</span><span class="o">&gt;</span><span class="w"> </span><span class="p">,</span><span class="w">
              </span><span class="o">|</span><span class="w"> </span><span class="o">&lt;</span><span class="n">case</span><span class="o">&gt;</span><span class="w"> </span><span class="p">,</span><span class="w"> </span><span class="o">&lt;</span><span class="n">case_list</span><span class="o">&gt;</span><span class="w">

</span><span class="o">&lt;</span><span class="n">block</span><span class="o">&gt;</span><span class="w"> </span><span class="p">::=</span><span class="w"> </span><span class="o">&lt;</span><span class="n">exp</span><span class="o">&gt;</span><span class="w"> </span><span class="p">[;]</span><span class="w">
          </span><span class="o">|</span><span class="w"> </span><span class="k">let</span><span class="w"> </span><span class="o">&lt;</span><span class="n">letbind</span><span class="o">&gt;</span><span class="w"> </span><span class="p">[;]</span><span class="w">
          </span><span class="o">|</span><span class="w"> </span><span class="k">let</span><span class="w"> </span><span class="o">&lt;</span><span class="n">letbind</span><span class="o">&gt;</span><span class="w"> </span><span class="p">;</span><span class="w"> </span><span class="o">&lt;</span><span class="n">block</span><span class="o">&gt;</span><span class="w">
          </span><span class="o">|</span><span class="w"> </span><span class="k">var</span><span class="w"> </span><span class="o">&lt;</span><span class="n">atomic_exp</span><span class="o">&gt;</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="o">&lt;</span><span class="n">exp</span><span class="o">&gt;</span><span class="w"> </span><span class="p">[;]</span><span class="w">
          </span><span class="o">|</span><span class="w"> </span><span class="k">var</span><span class="w"> </span><span class="o">&lt;</span><span class="n">atomic_exp</span><span class="o">&gt;</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="o">&lt;</span><span class="n">exp</span><span class="o">&gt;</span><span class="w"> </span><span class="p">;</span><span class="w"> </span><span class="o">&lt;</span><span class="n">block</span><span class="o">&gt;</span><span class="w">
          </span><span class="o">|</span><span class="w"> </span><span class="o">&lt;</span><span class="n">exp</span><span class="o">&gt;</span><span class="w"> </span><span class="p">;</span><span class="w"> </span><span class="o">&lt;</span><span class="n">block</span><span class="o">&gt;</span><span class="w">

</span><span class="o">&lt;</span><span class="n">letbind</span><span class="o">&gt;</span><span class="w"> </span><span class="p">::=</span><span class="w"> </span><span class="o">&lt;</span><span class="n">pat</span><span class="o">&gt;</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="o">&lt;</span><span class="n">exp</span><span class="o">&gt;</span><span class="w">

</span><span class="o">&lt;</span><span class="n">atomic_exp</span><span class="o">&gt;</span><span class="w"> </span><span class="p">::=</span><span class="w"> </span><span class="o">&lt;</span><span class="n">atomic_exp</span><span class="o">&gt;</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="o">&lt;</span><span class="n">atomic_typ</span><span class="o">&gt;</span><span class="w">
               </span><span class="o">|</span><span class="w"> </span><span class="n">Config</span><span class="w"> </span><span class="n">ID</span><span class="w">
               </span><span class="o">|</span><span class="w"> </span><span class="o">&lt;</span><span class="n">lit</span><span class="o">&gt;</span><span class="w">
               </span><span class="o">|</span><span class="w"> </span><span class="o">&lt;</span><span class="n">id</span><span class="o">&gt;</span><span class="w"> </span><span class="p">-&gt;</span><span class="w"> </span><span class="o">&lt;</span><span class="n">id</span><span class="o">&gt;</span><span class="w"> </span><span class="p">()</span><span class="w">
               </span><span class="o">|</span><span class="w"> </span><span class="o">&lt;</span><span class="n">id</span><span class="o">&gt;</span><span class="w"> </span><span class="p">-&gt;</span><span class="w"> </span><span class="o">&lt;</span><span class="n">id</span><span class="o">&gt;</span><span class="w"> </span><span class="p">(</span><span class="w"> </span><span class="o">&lt;</span><span class="n">exp_list</span><span class="o">&gt;</span><span class="w"> </span><span class="p">)</span><span class="w">
               </span><span class="o">|</span><span class="w"> </span><span class="o">&lt;</span><span class="n">atomic_exp</span><span class="o">&gt;</span><span class="w"> </span><span class="o">.</span><span class="w"> </span><span class="o">&lt;</span><span class="n">id</span><span class="o">&gt;</span><span class="w"> </span><span class="p">()</span><span class="w">
               </span><span class="o">|</span><span class="w"> </span><span class="o">&lt;</span><span class="n">atomic_exp</span><span class="o">&gt;</span><span class="w"> </span><span class="o">.</span><span class="w"> </span><span class="o">&lt;</span><span class="n">id</span><span class="o">&gt;</span><span class="w"> </span><span class="p">(</span><span class="w"> </span><span class="o">&lt;</span><span class="n">exp_list</span><span class="o">&gt;</span><span class="w"> </span><span class="p">)</span><span class="w">
               </span><span class="o">|</span><span class="w"> </span><span class="o">&lt;</span><span class="n">atomic_exp</span><span class="o">&gt;</span><span class="w"> </span><span class="o">.</span><span class="w"> </span><span class="o">&lt;</span><span class="n">id</span><span class="o">&gt;</span><span class="w">
               </span><span class="o">|</span><span class="w"> </span><span class="o">&lt;</span><span class="n">id</span><span class="o">&gt;</span><span class="w">
               </span><span class="o">|</span><span class="w"> </span><span class="o">&lt;</span><span class="n">typ_var</span><span class="o">&gt;</span><span class="w">
               </span><span class="o">|</span><span class="w"> </span><span class="k">ref</span><span class="w"> </span><span class="o">&lt;</span><span class="n">id</span><span class="o">&gt;</span><span class="w">
               </span><span class="o">|</span><span class="w"> </span><span class="o">&lt;</span><span class="n">id</span><span class="o">&gt;</span><span class="w"> </span><span class="p">()</span><span class="w">
               </span><span class="o">|</span><span class="w"> </span><span class="o">&lt;</span><span class="n">id</span><span class="o">&gt;</span><span class="w"> </span><span class="p">(</span><span class="w"> </span><span class="o">&lt;</span><span class="n">exp_list</span><span class="o">&gt;</span><span class="w"> </span><span class="p">)</span><span class="w">
               </span><span class="o">|</span><span class="w"> </span><span class="nb">sizeof</span><span class="w"> </span><span class="p">(</span><span class="w"> </span><span class="o">&lt;</span><span class="n">typ</span><span class="o">&gt;</span><span class="w"> </span><span class="p">)</span><span class="w">
               </span><span class="o">|</span><span class="w"> </span><span class="nb">constraint</span><span class="w"> </span><span class="p">(</span><span class="w"> </span><span class="o">&lt;</span><span class="n">typ</span><span class="o">&gt;</span><span class="w"> </span><span class="p">)</span><span class="w">
               </span><span class="o">|</span><span class="w"> </span><span class="o">&lt;</span><span class="n">atomic_exp</span><span class="o">&gt;</span><span class="w"> </span><span class="p">[</span><span class="w"> </span><span class="o">&lt;</span><span class="n">exp</span><span class="o">&gt;</span><span class="w"> </span><span class="p">]</span><span class="w">
               </span><span class="o">|</span><span class="w"> </span><span class="o">&lt;</span><span class="n">atomic_exp</span><span class="o">&gt;</span><span class="w"> </span><span class="p">[</span><span class="w"> </span><span class="o">&lt;</span><span class="n">exp</span><span class="o">&gt;</span><span class="w"> </span><span class="o">..</span><span class="w"> </span><span class="o">&lt;</span><span class="n">exp</span><span class="o">&gt;</span><span class="w"> </span><span class="p">]</span><span class="w">
               </span><span class="o">|</span><span class="w"> </span><span class="o">&lt;</span><span class="n">atomic_exp</span><span class="o">&gt;</span><span class="w"> </span><span class="p">[</span><span class="w"> </span><span class="o">&lt;</span><span class="n">exp</span><span class="o">&gt;</span><span class="w"> </span><span class="p">,</span><span class="w"> </span><span class="o">&lt;</span><span class="n">exp</span><span class="o">&gt;</span><span class="w"> </span><span class="p">]</span><span class="w">
               </span><span class="o">|</span><span class="w"> </span><span class="k">struct</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="o">&lt;</span><span class="n">fexp_exp_list</span><span class="o">&gt;</span><span class="w"> </span><span class="p">}</span><span class="w">
               </span><span class="o">|</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="o">&lt;</span><span class="n">exp</span><span class="o">&gt;</span><span class="w"> </span><span class="k">with</span><span class="w"> </span><span class="o">&lt;</span><span class="n">fexp_exp_list</span><span class="o">&gt;</span><span class="w"> </span><span class="p">}</span><span class="w">
               </span><span class="o">|</span><span class="w"> </span><span class="p">[</span><span class="w"> </span><span class="p">]</span><span class="w">
               </span><span class="o">|</span><span class="w"> </span><span class="p">[</span><span class="w"> </span><span class="o">&lt;</span><span class="n">exp_list</span><span class="o">&gt;</span><span class="w"> </span><span class="p">]</span><span class="w">
               </span><span class="o">|</span><span class="w"> </span><span class="p">[</span><span class="w"> </span><span class="o">&lt;</span><span class="n">exp</span><span class="o">&gt;</span><span class="w"> </span><span class="k">with</span><span class="w"> </span><span class="o">&lt;</span><span class="n">vector_update_list</span><span class="o">&gt;</span><span class="w"> </span><span class="p">]</span><span class="w">
               </span><span class="o">|</span><span class="w"> </span><span class="p">[|</span><span class="w"> </span><span class="p">|]</span><span class="w">
               </span><span class="o">|</span><span class="w"> </span><span class="p">[|</span><span class="w"> </span><span class="o">&lt;</span><span class="n">exp_list</span><span class="o">&gt;</span><span class="w"> </span><span class="p">|]</span><span class="w">
               </span><span class="o">|</span><span class="w"> </span><span class="p">(</span><span class="w"> </span><span class="o">&lt;</span><span class="n">exp</span><span class="o">&gt;</span><span class="w"> </span><span class="p">)</span><span class="w">
               </span><span class="o">|</span><span class="w"> </span><span class="p">(</span><span class="w"> </span><span class="o">&lt;</span><span class="n">exp</span><span class="o">&gt;</span><span class="w"> </span><span class="p">,</span><span class="w"> </span><span class="o">&lt;</span><span class="n">exp_list</span><span class="o">&gt;</span><span class="w"> </span><span class="p">)</span><span class="w">

</span><span class="o">&lt;</span><span class="n">fexp_exp</span><span class="o">&gt;</span><span class="w"> </span><span class="p">::=</span><span class="w"> </span><span class="o">&lt;</span><span class="n">atomic_exp</span><span class="o">&gt;</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="o">&lt;</span><span class="n">exp</span><span class="o">&gt;</span><span class="w">
             </span><span class="o">|</span><span class="w"> </span><span class="o">&lt;</span><span class="n">id</span><span class="o">&gt;</span><span class="w">

</span><span class="o">&lt;</span><span class="n">fexp_exp_list</span><span class="o">&gt;</span><span class="w"> </span><span class="p">::=</span><span class="w"> </span><span class="o">&lt;</span><span class="n">fexp_exp</span><span class="o">&gt;</span><span class="w">
                  </span><span class="o">|</span><span class="w"> </span><span class="o">&lt;</span><span class="n">fexp_exp</span><span class="o">&gt;</span><span class="w"> </span><span class="p">,</span><span class="w">
                  </span><span class="o">|</span><span class="w"> </span><span class="o">&lt;</span><span class="n">fexp_exp</span><span class="o">&gt;</span><span class="w"> </span><span class="p">,</span><span class="w"> </span><span class="o">&lt;</span><span class="n">fexp_exp_list</span><span class="o">&gt;</span><span class="w">

</span><span class="o">&lt;</span><span class="n">exp_list</span><span class="o">&gt;</span><span class="w"> </span><span class="p">::=</span><span class="w"> </span><span class="o">&lt;</span><span class="n">exp</span><span class="o">&gt;</span><span class="w"> </span><span class="p">[,]</span><span class="w">
             </span><span class="o">|</span><span class="w"> </span><span class="o">&lt;</span><span class="n">exp</span><span class="o">&gt;</span><span class="w"> </span><span class="p">,</span><span class="w"> </span><span class="o">&lt;</span><span class="n">exp_list</span><span class="o">&gt;</span><span class="w">

</span><span class="o">&lt;</span><span class="n">vector_update</span><span class="o">&gt;</span><span class="w"> </span><span class="p">::=</span><span class="w"> </span><span class="o">&lt;</span><span class="n">atomic_exp</span><span class="o">&gt;</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="o">&lt;</span><span class="n">exp</span><span class="o">&gt;</span><span class="w">
                  </span><span class="o">|</span><span class="w"> </span><span class="o">&lt;</span><span class="n">atomic_exp</span><span class="o">&gt;</span><span class="w"> </span><span class="o">..</span><span class="w"> </span><span class="o">&lt;</span><span class="n">atomic_exp</span><span class="o">&gt;</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="o">&lt;</span><span class="n">exp</span><span class="o">&gt;</span><span class="w">
                  </span><span class="o">|</span><span class="w"> </span><span class="o">&lt;</span><span class="n">id</span><span class="o">&gt;</span><span class="w">

</span><span class="o">&lt;</span><span class="n">vector_update_list</span><span class="o">&gt;</span><span class="w"> </span><span class="p">::=</span><span class="w"> </span><span class="o">&lt;</span><span class="n">vector_update</span><span class="o">&gt;</span><span class="w"> </span><span class="p">[,]</span><span class="w">
                       </span><span class="o">|</span><span class="w"> </span><span class="o">&lt;</span><span class="n">vector_update</span><span class="o">&gt;</span><span class="w"> </span><span class="p">,</span><span class="w"> </span><span class="o">&lt;</span><span class="n">vector_update_list</span><span class="o">&gt;</span><span class="w">

</span><span class="o">&lt;</span><span class="n">attribute_data_key_value</span><span class="o">&gt;</span><span class="w"> </span><span class="p">::=</span><span class="w"> </span><span class="n">ID</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="o">&lt;</span><span class="n">attribute_data</span><span class="o">&gt;</span><span class="w">
                             </span><span class="o">|</span><span class="w"> </span><span class="n">STRING_LITERAL</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="o">&lt;</span><span class="n">attribute_data</span><span class="o">&gt;</span><span class="w">

</span><span class="o">&lt;</span><span class="n">attribute_data</span><span class="o">&gt;</span><span class="w"> </span><span class="p">::=</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="p">[</span><span class="o">&lt;</span><span class="n">attribute_data_key_value</span><span class="o">&gt;</span><span class="w"> </span><span class="p">(,</span><span class="w"> </span><span class="o">&lt;</span><span class="n">attribute_data_key_value</span><span class="o">&gt;</span><span class="p">)</span><span class="o">*</span><span class="p">]</span><span class="w"> </span><span class="p">}</span><span class="w">
                   </span><span class="o">|</span><span class="w"> </span><span class="n">NUMBER</span><span class="w">
                   </span><span class="o">|</span><span class="w"> </span><span class="n">STRING_LITERAL</span><span class="w">
                   </span><span class="o">|</span><span class="w"> </span><span class="n">ID</span><span class="w">
                   </span><span class="o">|</span><span class="w"> </span><span class="nb">true</span><span class="w">
                   </span><span class="o">|</span><span class="w"> </span><span class="nb">false</span><span class="w">
                   </span><span class="o">|</span><span class="w"> </span><span class="p">[</span><span class="w"> </span><span class="p">[</span><span class="o">&lt;</span><span class="n">attribute_data</span><span class="o">&gt;</span><span class="w"> </span><span class="p">(,</span><span class="w"> </span><span class="o">&lt;</span><span class="n">attribute_data</span><span class="o">&gt;</span><span class="p">)</span><span class="o">*</span><span class="p">]</span><span class="w"> </span><span class="p">]</span><span class="w">

</span><span class="o">&lt;</span><span class="n">attribute</span><span class="o">&gt;</span><span class="w"> </span><span class="p">::=</span><span class="w"> </span><span class="cp">$[ATTRIBUTE ]</span><span class="w">
              </span><span class="o">|</span><span class="w"> </span><span class="cp">$[ATTRIBUTE &lt;attribute_data&gt; ]</span><span class="w">


</span><span class="o">&lt;</span><span class="n">funcl_annotation</span><span class="o">&gt;</span><span class="w"> </span><span class="p">::=</span><span class="w"> </span><span class="n">Private</span><span class="w">
                     </span><span class="o">|</span><span class="w"> </span><span class="o">&lt;</span><span class="n">attribute</span><span class="o">&gt;</span><span class="w">

</span><span class="o">&lt;</span><span class="n">funcl_patexp</span><span class="o">&gt;</span><span class="w"> </span><span class="p">::=</span><span class="w"> </span><span class="o">&lt;</span><span class="n">pat</span><span class="o">&gt;</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="o">&lt;</span><span class="n">exp</span><span class="o">&gt;</span><span class="w">
                 </span><span class="o">|</span><span class="w"> </span><span class="p">(</span><span class="w"> </span><span class="o">&lt;</span><span class="n">pat</span><span class="o">&gt;</span><span class="w"> </span><span class="k">if</span><span class="w"> </span><span class="o">&lt;</span><span class="n">exp</span><span class="o">&gt;</span><span class="w"> </span><span class="p">)</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="o">&lt;</span><span class="n">exp</span><span class="o">&gt;</span><span class="w">

</span><span class="o">&lt;</span><span class="n">funcl_patexp_typ</span><span class="o">&gt;</span><span class="w"> </span><span class="p">::=</span><span class="w"> </span><span class="o">&lt;</span><span class="n">pat</span><span class="o">&gt;</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="o">&lt;</span><span class="n">exp</span><span class="o">&gt;</span><span class="w">
                     </span><span class="o">|</span><span class="w"> </span><span class="o">&lt;</span><span class="n">pat</span><span class="o">&gt;</span><span class="w"> </span><span class="p">-&gt;</span><span class="w"> </span><span class="o">&lt;</span><span class="n">typ</span><span class="o">&gt;</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="o">&lt;</span><span class="n">exp</span><span class="o">&gt;</span><span class="w">
                     </span><span class="o">|</span><span class="w"> </span><span class="k">forall</span><span class="w"> </span><span class="o">&lt;</span><span class="n">quantifier</span><span class="o">&gt;</span><span class="w"> </span><span class="o">.</span><span class="w"> </span><span class="o">&lt;</span><span class="n">pat</span><span class="o">&gt;</span><span class="w"> </span><span class="p">-&gt;</span><span class="w"> </span><span class="o">&lt;</span><span class="n">typ</span><span class="o">&gt;</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="o">&lt;</span><span class="n">exp</span><span class="o">&gt;</span><span class="w">
                     </span><span class="o">|</span><span class="w"> </span><span class="p">(</span><span class="w"> </span><span class="o">&lt;</span><span class="n">pat</span><span class="o">&gt;</span><span class="w"> </span><span class="k">if</span><span class="w"> </span><span class="o">&lt;</span><span class="n">exp</span><span class="o">&gt;</span><span class="w"> </span><span class="p">)</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="o">&lt;</span><span class="n">exp</span><span class="o">&gt;</span><span class="w">
                     </span><span class="o">|</span><span class="w"> </span><span class="p">(</span><span class="w"> </span><span class="o">&lt;</span><span class="n">pat</span><span class="o">&gt;</span><span class="w"> </span><span class="k">if</span><span class="w"> </span><span class="o">&lt;</span><span class="n">exp</span><span class="o">&gt;</span><span class="w"> </span><span class="p">)</span><span class="w"> </span><span class="p">-&gt;</span><span class="w"> </span><span class="o">&lt;</span><span class="n">typ</span><span class="o">&gt;</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="o">&lt;</span><span class="n">exp</span><span class="o">&gt;</span><span class="w">
                     </span><span class="o">|</span><span class="w"> </span><span class="k">forall</span><span class="w"> </span><span class="o">&lt;</span><span class="n">quantifier</span><span class="o">&gt;</span><span class="w"> </span><span class="o">.</span><span class="w"> </span><span class="p">(</span><span class="w"> </span><span class="o">&lt;</span><span class="n">pat</span><span class="o">&gt;</span><span class="w"> </span><span class="k">if</span><span class="w"> </span><span class="o">&lt;</span><span class="n">exp</span><span class="o">&gt;</span><span class="w"> </span><span class="p">)</span><span class="w"> </span><span class="p">-&gt;</span><span class="w"> </span><span class="o">&lt;</span><span class="n">typ</span><span class="o">&gt;</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="o">&lt;</span><span class="n">exp</span><span class="o">&gt;</span><span class="w">

</span><span class="o">&lt;</span><span class="n">funcl</span><span class="o">&gt;</span><span class="w"> </span><span class="p">::=</span><span class="w"> </span><span class="o">&lt;</span><span class="n">funcl_annotation</span><span class="o">&gt;</span><span class="w"> </span><span class="o">&lt;</span><span class="n">id</span><span class="o">&gt;</span><span class="w"> </span><span class="o">&lt;</span><span class="n">funcl_patexp</span><span class="o">&gt;</span><span class="w">
          </span><span class="o">|</span><span class="w"> </span><span class="o">&lt;</span><span class="n">id</span><span class="o">&gt;</span><span class="w"> </span><span class="o">&lt;</span><span class="n">funcl_patexp</span><span class="o">&gt;</span><span class="w">

</span><span class="o">&lt;</span><span class="n">funcls</span><span class="o">&gt;</span><span class="w"> </span><span class="p">::=</span><span class="w"> </span><span class="o">&lt;</span><span class="n">funcl_annotation</span><span class="o">&gt;</span><span class="w"> </span><span class="o">&lt;</span><span class="n">id</span><span class="o">&gt;</span><span class="w"> </span><span class="o">&lt;</span><span class="n">funcl_patexp_typ</span><span class="o">&gt;</span><span class="w">
           </span><span class="o">|</span><span class="w"> </span><span class="o">&lt;</span><span class="n">id</span><span class="o">&gt;</span><span class="w"> </span><span class="o">&lt;</span><span class="n">funcl_patexp_typ</span><span class="o">&gt;</span><span class="w">
           </span><span class="o">|</span><span class="w"> </span><span class="o">&lt;</span><span class="n">funcl_annotation</span><span class="o">&gt;</span><span class="w"> </span><span class="o">&lt;</span><span class="n">id</span><span class="o">&gt;</span><span class="w"> </span><span class="o">&lt;</span><span class="n">funcl_patexp</span><span class="o">&gt;</span><span class="w"> </span><span class="k">and</span><span class="w"> </span><span class="o">&lt;</span><span class="n">funcl</span><span class="o">&gt;</span><span class="w"> </span><span class="p">(</span><span class="k">and</span><span class="w"> </span><span class="o">&lt;</span><span class="n">funcl</span><span class="o">&gt;</span><span class="p">)</span><span class="o">*</span><span class="w">
           </span><span class="o">|</span><span class="w"> </span><span class="o">&lt;</span><span class="n">id</span><span class="o">&gt;</span><span class="w"> </span><span class="o">&lt;</span><span class="n">funcl_patexp</span><span class="o">&gt;</span><span class="w"> </span><span class="k">and</span><span class="w"> </span><span class="o">&lt;</span><span class="n">funcl</span><span class="o">&gt;</span><span class="w"> </span><span class="p">(</span><span class="k">and</span><span class="w"> </span><span class="o">&lt;</span><span class="n">funcl</span><span class="o">&gt;</span><span class="p">)</span><span class="o">*</span><span class="w">

</span><span class="o">&lt;</span><span class="n">funcl_typ</span><span class="o">&gt;</span><span class="w"> </span><span class="p">::=</span><span class="w"> </span><span class="k">forall</span><span class="w"> </span><span class="o">&lt;</span><span class="n">quantifier</span><span class="o">&gt;</span><span class="w"> </span><span class="o">.</span><span class="w"> </span><span class="o">&lt;</span><span class="n">typ</span><span class="o">&gt;</span><span class="w">
              </span><span class="o">|</span><span class="w"> </span><span class="o">&lt;</span><span class="n">typ</span><span class="o">&gt;</span><span class="w">

</span><span class="o">&lt;</span><span class="n">paren_index_range</span><span class="o">&gt;</span><span class="w"> </span><span class="p">::=</span><span class="w"> </span><span class="p">(</span><span class="w"> </span><span class="o">&lt;</span><span class="n">paren_index_range</span><span class="o">&gt;</span><span class="w"> </span><span class="p">@</span><span class="w"> </span><span class="o">&lt;</span><span class="n">paren_index_range</span><span class="o">&gt;</span><span class="w"> </span><span class="p">(@</span><span class="w"> </span><span class="o">&lt;</span><span class="n">paren_index_range</span><span class="o">&gt;</span><span class="p">)</span><span class="o">*</span><span class="w"> </span><span class="p">)</span><span class="w">
                      </span><span class="o">|</span><span class="w"> </span><span class="o">&lt;</span><span class="n">atomic_index_range</span><span class="o">&gt;</span><span class="w">

</span><span class="o">&lt;</span><span class="n">atomic_index_range</span><span class="o">&gt;</span><span class="w"> </span><span class="p">::=</span><span class="w"> </span><span class="o">&lt;</span><span class="n">typ</span><span class="o">&gt;</span><span class="w">
                       </span><span class="o">|</span><span class="w"> </span><span class="o">&lt;</span><span class="n">typ</span><span class="o">&gt;</span><span class="w"> </span><span class="o">..</span><span class="w"> </span><span class="o">&lt;</span><span class="n">typ</span><span class="o">&gt;</span><span class="w">
                       </span><span class="o">|</span><span class="w"> </span><span class="p">(</span><span class="w"> </span><span class="o">&lt;</span><span class="n">typ</span><span class="o">&gt;</span><span class="w"> </span><span class="o">..</span><span class="w"> </span><span class="o">&lt;</span><span class="n">typ</span><span class="o">&gt;</span><span class="w"> </span><span class="p">)</span><span class="w">

</span><span class="o">&lt;</span><span class="n">r_id_def</span><span class="o">&gt;</span><span class="w"> </span><span class="p">::=</span><span class="w"> </span><span class="o">&lt;</span><span class="n">id</span><span class="o">&gt;</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="o">&lt;</span><span class="n">paren_index_range</span><span class="o">&gt;</span><span class="w"> </span><span class="p">(@</span><span class="w"> </span><span class="o">&lt;</span><span class="n">paren_index_range</span><span class="o">&gt;</span><span class="p">)</span><span class="o">*</span><span class="w">

</span><span class="o">&lt;</span><span class="n">r_def_body</span><span class="o">&gt;</span><span class="w"> </span><span class="p">::=</span><span class="w"> </span><span class="o">&lt;</span><span class="n">r_id_def</span><span class="o">&gt;</span><span class="w">
               </span><span class="o">|</span><span class="w"> </span><span class="o">&lt;</span><span class="n">r_id_def</span><span class="o">&gt;</span><span class="w"> </span><span class="p">,</span><span class="w">
               </span><span class="o">|</span><span class="w"> </span><span class="o">&lt;</span><span class="n">r_id_def</span><span class="o">&gt;</span><span class="w"> </span><span class="p">,</span><span class="w"> </span><span class="o">&lt;</span><span class="n">r_def_body</span><span class="o">&gt;</span><span class="w">

</span><span class="o">&lt;</span><span class="n">param_kopt</span><span class="o">&gt;</span><span class="w"> </span><span class="p">::=</span><span class="w"> </span><span class="o">&lt;</span><span class="n">typ_var</span><span class="o">&gt;</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="o">&lt;</span><span class="n">kind</span><span class="o">&gt;</span><span class="w">
               </span><span class="o">|</span><span class="w"> </span><span class="o">&lt;</span><span class="n">typ_var</span><span class="o">&gt;</span><span class="w">

</span><span class="o">&lt;</span><span class="n">typaram</span><span class="o">&gt;</span><span class="w"> </span><span class="p">::=</span><span class="w"> </span><span class="p">(</span><span class="w"> </span><span class="o">&lt;</span><span class="n">separated_nonempty_list_trailing</span><span class="p">(,,</span><span class="w"> </span><span class="o">&lt;</span><span class="n">param_kopt</span><span class="o">&gt;</span><span class="p">)</span><span class="o">&gt;</span><span class="w"> </span><span class="p">)</span><span class="w"> </span><span class="p">,</span><span class="w"> </span><span class="o">&lt;</span><span class="n">typ</span><span class="o">&gt;</span><span class="w">
            </span><span class="o">|</span><span class="w"> </span><span class="p">(</span><span class="w"> </span><span class="o">&lt;</span><span class="n">separated_nonempty_list_trailing</span><span class="p">(,,</span><span class="w"> </span><span class="o">&lt;</span><span class="n">param_kopt</span><span class="o">&gt;</span><span class="p">)</span><span class="o">&gt;</span><span class="w"> </span><span class="p">)</span><span class="w">

</span><span class="o">&lt;</span><span class="n">type_def</span><span class="o">&gt;</span><span class="w"> </span><span class="p">::=</span><span class="w"> </span><span class="k">type</span><span class="w"> </span><span class="o">&lt;</span><span class="n">id</span><span class="o">&gt;</span><span class="w"> </span><span class="o">&lt;</span><span class="n">typaram</span><span class="o">&gt;</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="o">&lt;</span><span class="n">typ</span><span class="o">&gt;</span><span class="w">
             </span><span class="o">|</span><span class="w"> </span><span class="k">type</span><span class="w"> </span><span class="o">&lt;</span><span class="n">id</span><span class="o">&gt;</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="o">&lt;</span><span class="n">typ</span><span class="o">&gt;</span><span class="w">
             </span><span class="o">|</span><span class="w"> </span><span class="k">type</span><span class="w"> </span><span class="o">&lt;</span><span class="n">id</span><span class="o">&gt;</span><span class="w"> </span><span class="o">&lt;</span><span class="n">typaram</span><span class="o">&gt;</span><span class="w"> </span><span class="p">-&gt;</span><span class="w"> </span><span class="o">&lt;</span><span class="n">kind</span><span class="o">&gt;</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="o">&lt;</span><span class="n">typ</span><span class="o">&gt;</span><span class="w">
             </span><span class="o">|</span><span class="w"> </span><span class="k">type</span><span class="w"> </span><span class="o">&lt;</span><span class="n">id</span><span class="o">&gt;</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="o">&lt;</span><span class="n">kind</span><span class="o">&gt;</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="o">&lt;</span><span class="n">typ</span><span class="o">&gt;</span><span class="w">
             </span><span class="o">|</span><span class="w"> </span><span class="k">type</span><span class="w"> </span><span class="o">&lt;</span><span class="n">id</span><span class="o">&gt;</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="o">&lt;</span><span class="n">kind</span><span class="o">&gt;</span><span class="w"> </span><span class="p">[=</span><span class="w"> </span><span class="n">Config</span><span class="w"> </span><span class="n">ID</span><span class="w"> </span><span class="p">(</span><span class="o">.</span><span class="w"> </span><span class="n">ID</span><span class="p">)</span><span class="o">*</span><span class="p">]</span><span class="w">
             </span><span class="o">|</span><span class="w"> </span><span class="k">struct</span><span class="w"> </span><span class="o">&lt;</span><span class="n">id</span><span class="o">&gt;</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="o">&lt;</span><span class="n">struct_fields</span><span class="o">&gt;</span><span class="w"> </span><span class="p">}</span><span class="w">
             </span><span class="o">|</span><span class="w"> </span><span class="k">struct</span><span class="w"> </span><span class="o">&lt;</span><span class="n">id</span><span class="o">&gt;</span><span class="w"> </span><span class="o">&lt;</span><span class="n">typaram</span><span class="o">&gt;</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="o">&lt;</span><span class="n">struct_fields</span><span class="o">&gt;</span><span class="w"> </span><span class="p">}</span><span class="w">
             </span><span class="o">|</span><span class="w"> </span><span class="k">enum</span><span class="w"> </span><span class="o">&lt;</span><span class="n">id</span><span class="o">&gt;</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="o">&lt;</span><span class="n">id</span><span class="o">&gt;</span><span class="w"> </span><span class="p">(</span><span class="o">|</span><span class="w"> </span><span class="o">&lt;</span><span class="n">id</span><span class="o">&gt;</span><span class="p">)</span><span class="o">*</span><span class="w">
             </span><span class="o">|</span><span class="w"> </span><span class="k">enum</span><span class="w"> </span><span class="o">&lt;</span><span class="n">id</span><span class="o">&gt;</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="o">&lt;</span><span class="n">enum_comma</span><span class="o">&gt;</span><span class="w"> </span><span class="p">}</span><span class="w">
             </span><span class="o">|</span><span class="w"> </span><span class="k">enum</span><span class="w"> </span><span class="o">&lt;</span><span class="n">id</span><span class="o">&gt;</span><span class="w"> </span><span class="k">with</span><span class="w"> </span><span class="o">&lt;</span><span class="n">enum_functions</span><span class="o">&gt;</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="o">&lt;</span><span class="n">enum_comma</span><span class="o">&gt;</span><span class="w"> </span><span class="p">}</span><span class="w">
             </span><span class="o">|</span><span class="w"> </span><span class="k">union</span><span class="w"> </span><span class="o">&lt;</span><span class="n">id</span><span class="o">&gt;</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="o">&lt;</span><span class="n">type_unions</span><span class="o">&gt;</span><span class="w"> </span><span class="p">}</span><span class="w">
             </span><span class="o">|</span><span class="w"> </span><span class="k">union</span><span class="w"> </span><span class="o">&lt;</span><span class="n">id</span><span class="o">&gt;</span><span class="w"> </span><span class="o">&lt;</span><span class="n">typaram</span><span class="o">&gt;</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="o">&lt;</span><span class="n">type_unions</span><span class="o">&gt;</span><span class="w"> </span><span class="p">}</span><span class="w">
             </span><span class="o">|</span><span class="w"> </span><span class="k">bitfield</span><span class="w"> </span><span class="o">&lt;</span><span class="n">id</span><span class="o">&gt;</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="o">&lt;</span><span class="n">typ</span><span class="o">&gt;</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="o">&lt;</span><span class="n">r_def_body</span><span class="o">&gt;</span><span class="w"> </span><span class="p">}</span><span class="w">

</span><span class="o">&lt;</span><span class="n">enum_functions</span><span class="o">&gt;</span><span class="w"> </span><span class="p">::=</span><span class="w"> </span><span class="o">&lt;</span><span class="n">id</span><span class="o">&gt;</span><span class="w"> </span><span class="p">-&gt;</span><span class="w"> </span><span class="o">&lt;</span><span class="n">typ</span><span class="o">&gt;</span><span class="w"> </span><span class="p">,</span><span class="w"> </span><span class="o">&lt;</span><span class="n">enum_functions</span><span class="o">&gt;</span><span class="w">
                   </span><span class="o">|</span><span class="w"> </span><span class="o">&lt;</span><span class="n">id</span><span class="o">&gt;</span><span class="w"> </span><span class="p">-&gt;</span><span class="w"> </span><span class="o">&lt;</span><span class="n">typ</span><span class="o">&gt;</span><span class="w"> </span><span class="p">,</span><span class="w">
                   </span><span class="o">|</span><span class="w"> </span><span class="o">&lt;</span><span class="n">id</span><span class="o">&gt;</span><span class="w"> </span><span class="p">-&gt;</span><span class="w"> </span><span class="o">&lt;</span><span class="n">typ</span><span class="o">&gt;</span><span class="w">

</span><span class="o">&lt;</span><span class="n">enum_comma</span><span class="o">&gt;</span><span class="w"> </span><span class="p">::=</span><span class="w"> </span><span class="o">&lt;</span><span class="n">id</span><span class="o">&gt;</span><span class="w"> </span><span class="p">[,]</span><span class="w">
         </span><span class="o">|</span><span class="w"> </span><span class="o">&lt;</span><span class="n">id</span><span class="o">&gt;</span><span class="w"> </span><span class="p">=</span><span class="o">&gt;</span><span class="w"> </span><span class="o">&lt;</span><span class="n">exp</span><span class="o">&gt;</span><span class="w"> </span><span class="p">[,]</span><span class="w">
         </span><span class="o">|</span><span class="w"> </span><span class="o">&lt;</span><span class="n">id</span><span class="o">&gt;</span><span class="w"> </span><span class="p">,</span><span class="w"> </span><span class="o">&lt;</span><span class="n">enum_comma</span><span class="o">&gt;</span><span class="w">
         </span><span class="o">|</span><span class="w"> </span><span class="o">&lt;</span><span class="n">id</span><span class="o">&gt;</span><span class="w"> </span><span class="p">=</span><span class="o">&gt;</span><span class="w"> </span><span class="o">&lt;</span><span class="n">exp</span><span class="o">&gt;</span><span class="w"> </span><span class="p">,</span><span class="w"> </span><span class="o">&lt;</span><span class="n">enum_comma</span><span class="o">&gt;</span><span class="w">

</span><span class="o">&lt;</span><span class="n">struct_field</span><span class="o">&gt;</span><span class="w"> </span><span class="p">::=</span><span class="w"> </span><span class="o">&lt;</span><span class="n">id</span><span class="o">&gt;</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="o">&lt;</span><span class="n">typ</span><span class="o">&gt;</span><span class="w">

</span><span class="o">&lt;</span><span class="n">struct_fields</span><span class="o">&gt;</span><span class="w"> </span><span class="p">::=</span><span class="w"> </span><span class="o">&lt;</span><span class="n">struct_field</span><span class="o">&gt;</span><span class="w">
                  </span><span class="o">|</span><span class="w"> </span><span class="o">&lt;</span><span class="n">struct_field</span><span class="o">&gt;</span><span class="w"> </span><span class="p">,</span><span class="w">
                  </span><span class="o">|</span><span class="w"> </span><span class="o">&lt;</span><span class="n">struct_field</span><span class="o">&gt;</span><span class="w"> </span><span class="p">,</span><span class="w"> </span><span class="o">&lt;</span><span class="n">struct_fields</span><span class="o">&gt;</span><span class="w">

</span><span class="o">&lt;</span><span class="n">type_union</span><span class="o">&gt;</span><span class="w"> </span><span class="p">::=</span><span class="w"> </span><span class="n">Private</span><span class="w"> </span><span class="o">&lt;</span><span class="n">type_union</span><span class="o">&gt;</span><span class="w">
               </span><span class="o">|</span><span class="w"> </span><span class="o">&lt;</span><span class="n">attribute</span><span class="o">&gt;</span><span class="w"> </span><span class="o">&lt;</span><span class="n">type_union</span><span class="o">&gt;</span><span class="w">
               </span><span class="o">|</span><span class="w"> </span><span class="o">&lt;</span><span class="n">id</span><span class="o">&gt;</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="o">&lt;</span><span class="n">typ</span><span class="o">&gt;</span><span class="w">
               </span><span class="o">|</span><span class="w"> </span><span class="o">&lt;</span><span class="n">id</span><span class="o">&gt;</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="o">&lt;</span><span class="n">struct_fields</span><span class="o">&gt;</span><span class="w"> </span><span class="p">}</span><span class="w">

</span><span class="o">&lt;</span><span class="n">type_unions</span><span class="o">&gt;</span><span class="w"> </span><span class="p">::=</span><span class="w"> </span><span class="o">&lt;</span><span class="n">type_union</span><span class="o">&gt;</span><span class="w"> </span><span class="p">[,]</span><span class="w">
                </span><span class="o">|</span><span class="w"> </span><span class="o">&lt;</span><span class="n">type_union</span><span class="o">&gt;</span><span class="w"> </span><span class="p">,</span><span class="w"> </span><span class="o">&lt;</span><span class="n">type_unions</span><span class="o">&gt;</span><span class="w">

</span><span class="o">&lt;</span><span class="n">rec_measure</span><span class="o">&gt;</span><span class="w"> </span><span class="p">::=</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="o">&lt;</span><span class="n">pat</span><span class="o">&gt;</span><span class="w"> </span><span class="p">=</span><span class="o">&gt;</span><span class="w"> </span><span class="o">&lt;</span><span class="n">exp</span><span class="o">&gt;</span><span class="w"> </span><span class="p">}</span><span class="w">

</span><span class="o">&lt;</span><span class="n">fun_def</span><span class="o">&gt;</span><span class="w"> </span><span class="p">::=</span><span class="w"> </span><span class="k">function</span><span class="w"> </span><span class="p">[</span><span class="o">&lt;</span><span class="n">rec_measure</span><span class="o">&gt;</span><span class="p">]</span><span class="w"> </span><span class="o">&lt;</span><span class="n">funcls</span><span class="o">&gt;</span><span class="w">

</span><span class="o">&lt;</span><span class="n">mpat</span><span class="o">&gt;</span><span class="w"> </span><span class="p">::=</span><span class="w"> </span><span class="o">&lt;</span><span class="n">atomic_mpat</span><span class="o">&gt;</span><span class="w"> </span><span class="p">(</span><span class="o">&lt;</span><span class="n">pat_op</span><span class="o">&gt;</span><span class="w"> </span><span class="o">&lt;</span><span class="n">atomic_mpat</span><span class="o">&gt;</span><span class="p">)</span><span class="o">*</span><span class="w">
         </span><span class="o">|</span><span class="w"> </span><span class="o">&lt;</span><span class="n">atomic_mpat</span><span class="o">&gt;</span><span class="w"> </span><span class="k">as</span><span class="w"> </span><span class="o">&lt;</span><span class="n">id</span><span class="o">&gt;</span><span class="w">

</span><span class="o">&lt;</span><span class="n">mpat_list</span><span class="o">&gt;</span><span class="w"> </span><span class="p">::=</span><span class="w"> </span><span class="o">&lt;</span><span class="n">mpat</span><span class="o">&gt;</span><span class="w"> </span><span class="p">[,]</span><span class="w">
              </span><span class="o">|</span><span class="w"> </span><span class="o">&lt;</span><span class="n">mpat</span><span class="o">&gt;</span><span class="w"> </span><span class="p">,</span><span class="w"> </span><span class="o">&lt;</span><span class="n">mpat_list</span><span class="o">&gt;</span><span class="w">

</span><span class="o">&lt;</span><span class="n">atomic_mpat</span><span class="o">&gt;</span><span class="w"> </span><span class="p">::=</span><span class="w"> </span><span class="o">&lt;</span><span class="n">lit</span><span class="o">&gt;</span><span class="w">
                </span><span class="o">|</span><span class="w"> </span><span class="o">&lt;</span><span class="n">id</span><span class="o">&gt;</span><span class="w">
                </span><span class="o">|</span><span class="w"> </span><span class="o">&lt;</span><span class="n">id</span><span class="o">&gt;</span><span class="w"> </span><span class="p">[</span><span class="w"> </span><span class="n">NUMBER</span><span class="w"> </span><span class="p">]</span><span class="w">
                </span><span class="o">|</span><span class="w"> </span><span class="o">&lt;</span><span class="n">id</span><span class="o">&gt;</span><span class="w"> </span><span class="p">[</span><span class="w"> </span><span class="n">NUMBER</span><span class="w"> </span><span class="o">..</span><span class="w"> </span><span class="n">NUMBER</span><span class="w"> </span><span class="p">]</span><span class="w">
                </span><span class="o">|</span><span class="w"> </span><span class="o">&lt;</span><span class="n">id</span><span class="o">&gt;</span><span class="w"> </span><span class="p">()</span><span class="w">
                </span><span class="o">|</span><span class="w"> </span><span class="o">&lt;</span><span class="n">id</span><span class="o">&gt;</span><span class="w"> </span><span class="p">(</span><span class="w"> </span><span class="o">&lt;</span><span class="n">mpat_list</span><span class="o">&gt;</span><span class="w"> </span><span class="p">)</span><span class="w">
                </span><span class="o">|</span><span class="w"> </span><span class="p">(</span><span class="w"> </span><span class="o">&lt;</span><span class="n">mpat</span><span class="o">&gt;</span><span class="w"> </span><span class="p">)</span><span class="w">
                </span><span class="o">|</span><span class="w"> </span><span class="p">(</span><span class="w"> </span><span class="o">&lt;</span><span class="n">mpat</span><span class="o">&gt;</span><span class="w"> </span><span class="p">,</span><span class="w"> </span><span class="o">&lt;</span><span class="n">mpat_list</span><span class="o">&gt;</span><span class="w"> </span><span class="p">)</span><span class="w">
                </span><span class="o">|</span><span class="w"> </span><span class="p">[</span><span class="w"> </span><span class="o">&lt;</span><span class="n">mpat_list</span><span class="o">&gt;</span><span class="w"> </span><span class="p">]</span><span class="w">
                </span><span class="o">|</span><span class="w"> </span><span class="p">[|</span><span class="w"> </span><span class="p">|]</span><span class="w">
                </span><span class="o">|</span><span class="w"> </span><span class="p">[|</span><span class="w"> </span><span class="o">&lt;</span><span class="n">mpat_list</span><span class="o">&gt;</span><span class="w"> </span><span class="p">|]</span><span class="w">
                </span><span class="o">|</span><span class="w"> </span><span class="o">&lt;</span><span class="n">atomic_mpat</span><span class="o">&gt;</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="o">&lt;</span><span class="n">typ_no_caret</span><span class="o">&gt;</span><span class="w">
                </span><span class="o">|</span><span class="w"> </span><span class="k">struct</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="o">&lt;</span><span class="n">separated_nonempty_list_trailing</span><span class="p">(,,</span><span class="w"> </span><span class="o">&lt;</span><span class="n">fmpat</span><span class="o">&gt;</span><span class="p">)</span><span class="o">&gt;</span><span class="w"> </span><span class="p">}</span><span class="w">

</span><span class="o">&lt;</span><span class="n">fmpat</span><span class="o">&gt;</span><span class="w"> </span><span class="p">::=</span><span class="w"> </span><span class="o">&lt;</span><span class="n">id</span><span class="o">&gt;</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="o">&lt;</span><span class="n">mpat</span><span class="o">&gt;</span><span class="w">
          </span><span class="o">|</span><span class="w"> </span><span class="o">&lt;</span><span class="n">id</span><span class="o">&gt;</span><span class="w">

</span><span class="o">&lt;</span><span class="n">mpexp</span><span class="o">&gt;</span><span class="w"> </span><span class="p">::=</span><span class="w"> </span><span class="o">&lt;</span><span class="n">mpat</span><span class="o">&gt;</span><span class="w">
          </span><span class="o">|</span><span class="w"> </span><span class="o">&lt;</span><span class="n">mpat</span><span class="o">&gt;</span><span class="w"> </span><span class="k">if</span><span class="w"> </span><span class="o">&lt;</span><span class="n">exp</span><span class="o">&gt;</span><span class="w">

</span><span class="o">&lt;</span><span class="n">mapcl</span><span class="o">&gt;</span><span class="w"> </span><span class="p">::=</span><span class="w"> </span><span class="o">&lt;</span><span class="n">attribute</span><span class="o">&gt;</span><span class="w"> </span><span class="o">&lt;</span><span class="n">mapcl</span><span class="o">&gt;</span><span class="w">
          </span><span class="o">|</span><span class="w"> </span><span class="o">&lt;</span><span class="n">mapcl0</span><span class="o">&gt;</span><span class="w">
          </span><span class="o">|</span><span class="w"> </span><span class="o">&lt;</span><span class="n">mapcl0</span><span class="o">&gt;</span><span class="w"> </span><span class="n">When</span><span class="w"> </span><span class="o">&lt;</span><span class="n">exp</span><span class="o">&gt;</span><span class="w">

</span><span class="o">&lt;</span><span class="n">mapcl0</span><span class="o">&gt;</span><span class="w"> </span><span class="p">::=</span><span class="w"> </span><span class="o">&lt;</span><span class="n">mpexp</span><span class="o">&gt;</span><span class="w"> </span><span class="o">&lt;-&gt;</span><span class="w"> </span><span class="o">&lt;</span><span class="n">mpexp</span><span class="o">&gt;</span><span class="w">
           </span><span class="o">|</span><span class="w"> </span><span class="o">&lt;</span><span class="n">mpexp</span><span class="o">&gt;</span><span class="w"> </span><span class="p">=</span><span class="o">&gt;</span><span class="w"> </span><span class="o">&lt;</span><span class="n">exp</span><span class="o">&gt;</span><span class="w">
           </span><span class="o">|</span><span class="w"> </span><span class="k">forwards</span><span class="w"> </span><span class="o">&lt;</span><span class="n">case</span><span class="o">&gt;</span><span class="w">
           </span><span class="o">|</span><span class="w"> </span><span class="k">backwards</span><span class="w"> </span><span class="o">&lt;</span><span class="n">case</span><span class="o">&gt;</span><span class="w">

</span><span class="o">&lt;</span><span class="n">mapcl_list</span><span class="o">&gt;</span><span class="w"> </span><span class="p">::=</span><span class="w"> </span><span class="o">&lt;</span><span class="n">mapcl</span><span class="o">&gt;</span><span class="w"> </span><span class="p">[,]</span><span class="w">
               </span><span class="o">|</span><span class="w"> </span><span class="o">&lt;</span><span class="n">mapcl</span><span class="o">&gt;</span><span class="w"> </span><span class="p">,</span><span class="w"> </span><span class="o">&lt;</span><span class="n">mapcl_list</span><span class="o">&gt;</span><span class="w">

</span><span class="o">&lt;</span><span class="n">map_def</span><span class="o">&gt;</span><span class="w"> </span><span class="p">::=</span><span class="w"> </span><span class="k">mapping</span><span class="w"> </span><span class="o">&lt;</span><span class="n">id</span><span class="o">&gt;</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="o">&lt;</span><span class="n">mapcl_list</span><span class="o">&gt;</span><span class="w"> </span><span class="p">}</span><span class="w">
            </span><span class="o">|</span><span class="w"> </span><span class="k">mapping</span><span class="w"> </span><span class="o">&lt;</span><span class="n">id</span><span class="o">&gt;</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="o">&lt;</span><span class="n">typschm</span><span class="o">&gt;</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="o">&lt;</span><span class="n">mapcl_list</span><span class="o">&gt;</span><span class="w"> </span><span class="p">}</span><span class="w">

</span><span class="o">&lt;</span><span class="n">let_def</span><span class="o">&gt;</span><span class="w"> </span><span class="p">::=</span><span class="w"> </span><span class="k">let</span><span class="w"> </span><span class="o">&lt;</span><span class="n">letbind</span><span class="o">&gt;</span><span class="w">


             </span><span class="o">|</span><span class="w"> </span><span class="n">impure</span><span class="w">
             </span><span class="o">|</span><span class="w"> </span><span class="k">pure</span><span class="w">

</span><span class="o">&lt;</span><span class="n">extern_binding</span><span class="o">&gt;</span><span class="w"> </span><span class="p">::=</span><span class="w"> </span><span class="o">&lt;</span><span class="n">id</span><span class="o">&gt;</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="n">STRING_LITERAL</span><span class="w">
                   </span><span class="o">|</span><span class="w"> </span><span class="mi">_</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="n">STRING_LITERAL</span><span class="w">

</span><span class="o">&lt;</span><span class="n">externs</span><span class="o">&gt;</span><span class="w"> </span><span class="p">::=</span><span class="w"> </span><span class="n">epsilon</span><span class="w">
            </span><span class="o">|</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">STRING_LITERAL</span><span class="w">
            </span><span class="o">|</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="o">&lt;</span><span class="n">separated_nonempty_list_trailing</span><span class="p">(,,</span><span class="w"> </span><span class="o">&lt;</span><span class="n">extern_binding</span><span class="o">&gt;</span><span class="p">)</span><span class="o">&gt;</span><span class="w"> </span><span class="p">}</span><span class="w">
            </span><span class="o">|</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="o">&lt;</span><span class="n">pure_opt</span><span class="o">&gt;</span><span class="w"> </span><span class="n">STRING_LITERAL</span><span class="w">
            </span><span class="o">|</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="o">&lt;</span><span class="n">pure_opt</span><span class="o">&gt;</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="o">&lt;</span><span class="n">separated_nonempty_list_trailing</span><span class="p">(,,</span><span class="w"> </span><span class="o">&lt;</span><span class="n">extern_binding</span><span class="o">&gt;</span><span class="p">)</span><span class="o">&gt;</span><span class="w"> </span><span class="p">}</span><span class="w">

</span><span class="o">&lt;</span><span class="n">val_spec_def</span><span class="o">&gt;</span><span class="w"> </span><span class="p">::=</span><span class="w"> </span><span class="k">val</span><span class="w"> </span><span class="nf">STRING_LITERAL</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="o">&lt;</span><span class="n">typschm</span><span class="o">&gt;</span><span class="w">
                 </span><span class="o">|</span><span class="w"> </span><span class="k">val</span><span class="w"> </span><span class="o">&lt;</span><span class="n">id</span><span class="o">&gt;</span><span class="w"> </span><span class="o">&lt;</span><span class="n">externs</span><span class="o">&gt;</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="o">&lt;</span><span class="n">typschm</span><span class="o">&gt;</span><span class="w">

</span><span class="o">&lt;</span><span class="n">register_def</span><span class="o">&gt;</span><span class="w"> </span><span class="p">::=</span><span class="w"> </span><span class="k">register</span><span class="w"> </span><span class="o">&lt;</span><span class="n">id</span><span class="o">&gt;</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="o">&lt;</span><span class="n">typ</span><span class="o">&gt;</span><span class="w">
                 </span><span class="o">|</span><span class="w"> </span><span class="k">register</span><span class="w"> </span><span class="o">&lt;</span><span class="n">id</span><span class="o">&gt;</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="o">&lt;</span><span class="n">typ</span><span class="o">&gt;</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="o">&lt;</span><span class="n">exp</span><span class="o">&gt;</span><span class="w">

</span><span class="o">&lt;</span><span class="n">default_def</span><span class="o">&gt;</span><span class="w"> </span><span class="p">::=</span><span class="w"> </span><span class="k">default</span><span class="w"> </span><span class="o">&lt;</span><span class="n">kind</span><span class="o">&gt;</span><span class="w"> </span><span class="kt">inc</span><span class="w">
                </span><span class="o">|</span><span class="w"> </span><span class="k">default</span><span class="w"> </span><span class="o">&lt;</span><span class="n">kind</span><span class="o">&gt;</span><span class="w"> </span><span class="kt">dec</span><span class="w">

</span><span class="o">&lt;</span><span class="n">scattered_def</span><span class="o">&gt;</span><span class="w"> </span><span class="p">::=</span><span class="w"> </span><span class="k">scattered</span><span class="w"> </span><span class="k">enum</span><span class="w"> </span><span class="o">&lt;</span><span class="n">id</span><span class="o">&gt;</span><span class="w">
                  </span><span class="o">|</span><span class="w"> </span><span class="k">scattered</span><span class="w"> </span><span class="k">union</span><span class="w"> </span><span class="o">&lt;</span><span class="n">id</span><span class="o">&gt;</span><span class="w"> </span><span class="o">&lt;</span><span class="n">typaram</span><span class="o">&gt;</span><span class="w">
                  </span><span class="o">|</span><span class="w"> </span><span class="k">scattered</span><span class="w"> </span><span class="k">union</span><span class="w"> </span><span class="o">&lt;</span><span class="n">id</span><span class="o">&gt;</span><span class="w">
                  </span><span class="o">|</span><span class="w"> </span><span class="k">scattered</span><span class="w"> </span><span class="k">function</span><span class="w"> </span><span class="o">&lt;</span><span class="n">id</span><span class="o">&gt;</span><span class="w">
                  </span><span class="o">|</span><span class="w"> </span><span class="k">scattered</span><span class="w"> </span><span class="k">mapping</span><span class="w"> </span><span class="o">&lt;</span><span class="n">id</span><span class="o">&gt;</span><span class="w">
                  </span><span class="o">|</span><span class="w"> </span><span class="k">scattered</span><span class="w"> </span><span class="k">mapping</span><span class="w"> </span><span class="o">&lt;</span><span class="n">id</span><span class="o">&gt;</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="o">&lt;</span><span class="n">funcl_typ</span><span class="o">&gt;</span><span class="w">
                  </span><span class="o">|</span><span class="w"> </span><span class="k">enum</span><span class="w"> </span><span class="k">clause</span><span class="w"> </span><span class="o">&lt;</span><span class="n">id</span><span class="o">&gt;</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="o">&lt;</span><span class="n">id</span><span class="o">&gt;</span><span class="w">
                  </span><span class="o">|</span><span class="w"> </span><span class="k">function</span><span class="w"> </span><span class="nf">clause</span><span class="w"> </span><span class="o">&lt;</span><span class="n">funcl</span><span class="o">&gt;</span><span class="w">
                  </span><span class="o">|</span><span class="w"> </span><span class="k">union</span><span class="w"> </span><span class="k">clause</span><span class="w"> </span><span class="o">&lt;</span><span class="n">id</span><span class="o">&gt;</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="o">&lt;</span><span class="n">type_union</span><span class="o">&gt;</span><span class="w">
                  </span><span class="o">|</span><span class="w"> </span><span class="k">mapping</span><span class="w"> </span><span class="k">clause</span><span class="w"> </span><span class="o">&lt;</span><span class="n">id</span><span class="o">&gt;</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="o">&lt;</span><span class="n">mapcl</span><span class="o">&gt;</span><span class="w">
                  </span><span class="o">|</span><span class="w"> </span><span class="k">end</span><span class="w"> </span><span class="o">&lt;</span><span class="n">id</span><span class="o">&gt;</span><span class="w">

</span><span class="o">&lt;</span><span class="n">loop_measure</span><span class="o">&gt;</span><span class="w"> </span><span class="p">::=</span><span class="w"> </span><span class="k">until</span><span class="w"> </span><span class="o">&lt;</span><span class="n">exp</span><span class="o">&gt;</span><span class="w">
                 </span><span class="o">|</span><span class="w"> </span><span class="k">repeat</span><span class="w"> </span><span class="o">&lt;</span><span class="n">exp</span><span class="o">&gt;</span><span class="w">
                 </span><span class="o">|</span><span class="w"> </span><span class="k">while</span><span class="w"> </span><span class="o">&lt;</span><span class="n">exp</span><span class="o">&gt;</span><span class="w">

</span><span class="o">&lt;</span><span class="n">subst</span><span class="o">&gt;</span><span class="w"> </span><span class="p">::=</span><span class="w"> </span><span class="o">&lt;</span><span class="n">typ_var</span><span class="o">&gt;</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="o">&lt;</span><span class="n">typ</span><span class="o">&gt;</span><span class="w">
          </span><span class="o">|</span><span class="w"> </span><span class="o">&lt;</span><span class="n">id</span><span class="o">&gt;</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="o">&lt;</span><span class="n">id</span><span class="o">&gt;</span><span class="w">

</span><span class="o">&lt;</span><span class="n">instantiation_def</span><span class="o">&gt;</span><span class="w"> </span><span class="p">::=</span><span class="w"> </span><span class="k">instantiation</span><span class="w"> </span><span class="o">&lt;</span><span class="n">id</span><span class="o">&gt;</span><span class="w">
                      </span><span class="o">|</span><span class="w"> </span><span class="k">instantiation</span><span class="w"> </span><span class="o">&lt;</span><span class="n">id</span><span class="o">&gt;</span><span class="w"> </span><span class="k">with</span><span class="w"> </span><span class="o">&lt;</span><span class="n">subst</span><span class="o">&gt;</span><span class="w"> </span><span class="p">(,</span><span class="w"> </span><span class="o">&lt;</span><span class="n">subst</span><span class="o">&gt;</span><span class="p">)</span><span class="o">*</span><span class="w">

</span><span class="o">&lt;</span><span class="n">overload_def</span><span class="o">&gt;</span><span class="w"> </span><span class="p">::=</span><span class="w"> </span><span class="k">overload</span><span class="w"> </span><span class="o">&lt;</span><span class="n">id</span><span class="o">&gt;</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="o">&lt;</span><span class="n">id</span><span class="o">&gt;</span><span class="w"> </span><span class="p">(,</span><span class="w"> </span><span class="o">&lt;</span><span class="n">id</span><span class="o">&gt;</span><span class="p">)</span><span class="o">*</span><span class="w"> </span><span class="p">}</span><span class="w">
                 </span><span class="o">|</span><span class="w"> </span><span class="k">overload</span><span class="w"> </span><span class="o">&lt;</span><span class="n">id</span><span class="o">&gt;</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="o">&lt;</span><span class="n">id</span><span class="o">&gt;</span><span class="w"> </span><span class="p">(</span><span class="o">|</span><span class="w"> </span><span class="o">&lt;</span><span class="n">id</span><span class="o">&gt;</span><span class="p">)</span><span class="o">*</span><span class="w">

</span><span class="o">&lt;</span><span class="n">def_aux</span><span class="o">&gt;</span><span class="w"> </span><span class="p">::=</span><span class="w"> </span><span class="o">&lt;</span><span class="n">fun_def</span><span class="o">&gt;</span><span class="w">
            </span><span class="o">|</span><span class="w"> </span><span class="o">&lt;</span><span class="n">map_def</span><span class="o">&gt;</span><span class="w">
            </span><span class="o">|</span><span class="w"> </span><span class="n">FIXITY_DEF</span><span class="w">
            </span><span class="o">|</span><span class="w"> </span><span class="o">&lt;</span><span class="n">val_spec_def</span><span class="o">&gt;</span><span class="w">
            </span><span class="o">|</span><span class="w"> </span><span class="o">&lt;</span><span class="n">instantiation_def</span><span class="o">&gt;</span><span class="w">
            </span><span class="o">|</span><span class="w"> </span><span class="o">&lt;</span><span class="n">type_def</span><span class="o">&gt;</span><span class="w">
            </span><span class="o">|</span><span class="w"> </span><span class="o">&lt;</span><span class="n">let_def</span><span class="o">&gt;</span><span class="w">
            </span><span class="o">|</span><span class="w"> </span><span class="o">&lt;</span><span class="n">register_def</span><span class="o">&gt;</span><span class="w">
            </span><span class="o">|</span><span class="w"> </span><span class="o">&lt;</span><span class="n">overload_def</span><span class="o">&gt;</span><span class="w">
            </span><span class="o">|</span><span class="w"> </span><span class="o">&lt;</span><span class="n">scattered_def</span><span class="o">&gt;</span><span class="w">
            </span><span class="o">|</span><span class="w"> </span><span class="o">&lt;</span><span class="n">default_def</span><span class="o">&gt;</span><span class="w">
            </span><span class="o">|</span><span class="w"> </span><span class="nb">constraint</span><span class="w"> </span><span class="o">&lt;</span><span class="n">typ</span><span class="o">&gt;</span><span class="w">
            </span><span class="o">|</span><span class="w"> </span><span class="n">structured</span><span class="cp">$LINE_DIRECTIVE [&lt;attribute_data_key_value&gt; (, &lt;attribute_data_key_value&gt;)*] }</span><span class="w">
            </span><span class="o">|</span><span class="w"> </span><span class="cp">$LINE_DIRECTIVE</span><span class="w">
            </span><span class="o">|</span><span class="w"> </span><span class="kr">termination_measure</span><span class="w"> </span><span class="o">&lt;</span><span class="n">id</span><span class="o">&gt;</span><span class="w"> </span><span class="o">&lt;</span><span class="n">pat</span><span class="o">&gt;</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="o">&lt;</span><span class="n">exp</span><span class="o">&gt;</span><span class="w">
            </span><span class="o">|</span><span class="w"> </span><span class="kr">termination_measure</span><span class="w"> </span><span class="o">&lt;</span><span class="n">id</span><span class="o">&gt;</span><span class="w"> </span><span class="o">&lt;</span><span class="n">loop_measure</span><span class="o">&gt;</span><span class="w"> </span><span class="p">(,</span><span class="w"> </span><span class="o">&lt;</span><span class="n">loop_measure</span><span class="o">&gt;</span><span class="p">)</span><span class="o">*</span><span class="w">

</span><span class="o">&lt;</span><span class="n">def</span><span class="o">&gt;</span><span class="w"> </span><span class="p">::=</span><span class="w"> </span><span class="n">Private</span><span class="w"> </span><span class="o">&lt;</span><span class="n">def</span><span class="o">&gt;</span><span class="w">
        </span><span class="o">|</span><span class="w"> </span><span class="o">&lt;</span><span class="n">attribute</span><span class="o">&gt;</span><span class="w"> </span><span class="o">&lt;</span><span class="n">def</span><span class="o">&gt;</span><span class="w">
        </span><span class="o">|</span><span class="w"> </span><span class="o">&lt;</span><span class="n">def_aux</span><span class="o">&gt;</span><span class="w">


</span></code></pre>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_references">References</h2>
<div class="sectionbody">
<div class="paragraph">
<p><a id="Intel61"></a>[1] Intel, “Intel 64 and IA-32 Architectures Software Developer’s Manual.” <a href="https://software.intel.com/en-us/articles/intel-sdm" class="bare">software.intel.com/en-us/articles/intel-sdm</a> , Dec. 2016.</p>
</div>
<div class="paragraph">
<p><a id="AMD_3_21"></a>[2] AMD, “AMD64 Architecture Programmer’s Manual Volume 1: Application Programming.” <a href="http://support.amd.com/TechDocs/24592.pdf" class="bare">support.amd.com/TechDocs/24592.pdf</a> , Oct. 2013.</p>
</div>
<div class="paragraph">
<p><a id="Power3.0B"></a>[3] <em>Power ISA Version 3.0B</em>. OpenPOWER Foundation, 2017.</p>
</div>
<div class="paragraph">
<p><a id="Leighton21"></a>[4] L. Leighton, “The Libre-SOC Project.” EuroPython Society, 2021.</p>
</div>
<div class="paragraph">
<p><a id="armarmv8"></a>[5] <em>ARM Architecture Reference Manual (ARMv8, for ARMv8-A architecture profile)</em>. ARM Ltd., 2015.</p>
</div>
<div class="paragraph">
<p><a id="Reid16"></a>[6] A. Reid, “Trustworthy Specifications of ARM v8-A and v8-M System Level Architecture,” 2016.</p>
</div>
<div class="paragraph">
<p><a id="MIPS64-II"></a>[7] MIPS Technologies, Inc., “MIPS64 Architecture For Programmers. Volume II: The MIPS64 Instruction Set.” Jul. 2005.</p>
</div>
<div class="paragraph">
<p><a id="MIPS64-III"></a>[8] MIPS Technologies, Inc., “MIPS64 Architecture For Programmers. Volume III: The MIPS64 Privileged Resource Architecture.” Jul. 2005.</p>
</div>
<div class="paragraph">
<p><a id="Lem-icfp2014"></a>[9] D. P. Mulligan, S. Owens, K. E. Gray, T. Ridge, and P. Sewell, “Lem: reusable engineering of real-world semantics,” in <em>Proceedings of ICFP 2014: the 19th ACM SIGPLAN International Conference on Functional Programming</em>, 2014, pp. 175–188, doi: 10.1145/2628136.2628143.</p>
</div>
<div class="paragraph">
<p><a id="Lemcode"></a>[10] “Lem implementation.” <a href="https://bitbucket.org/Peter_Sewell/lem/" class="bare">bitbucket.org/Peter_Sewell/lem/</a> , 2017.</p>
</div>
<div class="paragraph">
<p><a id="UCAM-CL-TR-868"></a>[11] R. N. M. Watson <em>et al.</em>, “Bluespec Extensible RISC Implementation: BERI Hardware reference,” University of Cambridge, Computer Laboratory, UCAM-CL-TR-868, Apr. 2015. [Online]. Available: <a href="http://www.cl.cam.ac.uk/techreports/UCAM-CL-TR-868.pdf" class="bare">www.cl.cam.ac.uk/techreports/UCAM-CL-TR-868.pdf</a>.</p>
</div>
<div class="paragraph">
<p><a id="MIPS4000"></a>[12] J. Heinrich, <em>MIPS R4000 Microprocessor User’s Manual (Second Edition)</em>. MIPS Technologies, Inc., 1994.</p>
</div>
<div class="paragraph">
<p><a id="MIPS32-I"></a>[13] MIPS Technologies, Inc., “MIPS32 Architecture For Programmers. Volume I: Introduction to the MIPS32 Architecture.” Mar. 2001.</p>
</div>
<div class="paragraph">
<p><a id="UCAM-CL-TR-891"></a>[14] R. N. M. Watson <em>et al.</em>, “Capability Hardware Enhanced RISC Instructions: CHERI Instruction-Set Architecture (Version 5),” University of Cambridge, Computer Laboratory, UCAM-CL-TR-891, Jun. 2016. [Online]. Available: <a href="http://www.cl.cam.ac.uk/techreports/UCAM-CL-TR-891.pdf" class="bare">www.cl.cam.ac.uk/techreports/UCAM-CL-TR-891.pdf</a>.</p>
</div>
</div>
</div>
</div>
<div id="footnotes">
<hr>
<div class="footnote" id="_footnotedef_1">
<a href="#_footnoteref_1">1</a>. ARM v8-A   Architecture Specification: <a href="https://github.com/meriac/archex" class="bare">github.com/meriac/archex</a>
</div>
</div>
<div id="footer">
<div id="footer-text">
Last updated 2025-03-06 17:50:57 UTC
</div>
</div>
</body>
</html>