Documentation site

.gitignore

@@ -0,0 +1,6 @@
+_site
+.sass-cache
+.jekyll-cache
+.jekyll-metadata
+vendor
+.bundle

404.html

@@ -0,0 +1,25 @@
+---
+permalink: /404.html
+layout: default
+---
+
+<style type="text/css" media="screen">
+  .container {
+    margin: 10px auto;
+    max-width: 600px;
+    text-align: center;
+  }
+  h1 {
+    margin: 30px 0;
+    font-size: 4em;
+    line-height: 1;
+    letter-spacing: -1px;
+  }
+</style>
+
+<div class="container">
+  <h1>404</h1>
+
+  <p><strong>Page not found :(</strong></p>
+  <p>The requested page could not be found.</p>
+</div>

Gemfile

@@ -0,0 +1,33 @@
+source "https://rubygems.org"
+# Hello! This is where you manage which Jekyll version is used to run.
+# When you want to use a different version, change it below, save the
+# file and run `bundle install`. Run Jekyll with `bundle exec`, like so:
+#
+#     bundle exec jekyll serve
+#
+# This will help ensure the proper Jekyll version is running.
+# Happy Jekylling!
+gem "jekyll", "~> 4.3.4"
+# This is the default theme for new Jekyll sites. You may change this to anything you like.
+gem "minima", "~> 2.5"
+# If you want to use GitHub Pages, remove the "gem "jekyll"" above and
+# uncomment the line below. To upgrade, run `bundle update github-pages`.
+# gem "github-pages", group: :jekyll_plugins
+# If you have any plugins, put them here!
+group :jekyll_plugins do
+  gem "jekyll-feed", "~> 0.12"
+end
+
+# Windows and JRuby does not include zoneinfo files, so bundle the tzinfo-data gem
+# and associated library.
+platforms :mingw, :x64_mingw, :mswin, :jruby do
+  gem "tzinfo", ">= 1", "< 3"
+  gem "tzinfo-data"
+end
+
+# Performance-booster for watching directories on Windows
+gem "wdm", "~> 0.1", :platforms => [:mingw, :x64_mingw, :mswin]
+
+# Lock `http_parser.rb` gem to `v0.6.x` on JRuby builds since newer versions of the gem
+# do not have a Java counterpart.
+gem "http_parser.rb", "~> 0.6.0", :platforms => [:jruby]

_config.yml

@@ -0,0 +1,60 @@
+# Welcome to Jekyll!
+#
+# This config file is meant for settings that affect your whole blog, values
+# which you are expected to set up once and rarely edit after that. If you find
+# yourself editing this file very often, consider using Jekyll's data files
+# feature for the data you need to update frequently.
+#
+# For technical reasons, this file is *NOT* reloaded automatically when you use
+# 'bundle exec jekyll serve'. If you change this file, please restart the server process.
+#
+# If you need help with YAML syntax, here are some quick references for you:
+# https://learn-the-web.algonquindesign.ca/topics/markdown-yaml-cheat-sheet/#yaml
+# https://learnxinyminutes.com/docs/yaml/
+#
+# Site settings
+# These are used to personalize your new site. If you look in the HTML files,
+# you will see them accessed via {{ site.title }}, {{ site.email }}, and so on.
+# You can create any custom variable you would like, and they will be accessible
+# in the templates via {{ site.myvariable }}.
+
+title: "ASL interpreter and compiler"
+description: >- # this means to ignore newlines until "baseurl:"
+  A tool for writing clear, precise ISA specifications using ASL
+baseurl: "" # the subpath of your site, e.g. /blog
+url: "" # the base hostname & protocol for your site, e.g. http://example.com
+
+# Build settings
+theme: minima
+plugins:
+  - jekyll-feed
+
+permalink: /:categories/:year/:month/:day/:title:output_ext
+
+author: Intel Labs
+
+header_pages:
+  - asl_reading.markdown
+  - asl_writing.markdown
+  - index.markdown
+  - about.markdown
+
+# Exclude from processing.
+# The following items will not be processed, by default.
+# Any item listed under the `exclude:` key here will be automatically added to
+# the internal "default list".
+#
+# Excluded items can be processed by explicitly listing the directories or
+# their entries' file path in the `include:` list.
+#
+# exclude:
+#   - .sass-cache/
+#   - .jekyll-cache/
+#   - gemfiles/
+#   - Gemfile
+#   - Gemfile.lock
+#   - node_modules/
+#   - vendor/bundle/
+#   - vendor/cache/
+#   - vendor/gems/
+#   - vendor/ruby/

_posts/2024-12-19-demo.markdown

@@ -0,0 +1,143 @@
+---
+layout: post
+title: Using ASLi to simulate an ISA
+---
+
+To demonstrate how ASLi can be used to model an ISA, we wrote a *trivial* ISA
+with just two instructions: Increment and Halt.
+
+- `INC r3` increments register 3 (there are 4 registers)
+- `HALT` halts the processor
+
+The demo directory contains an ASL specification of this ISA and consists of the following files.
+
+- Makefile: Rules for building and running demos/tests.
+- demo.asl: An ASL specification of the demo architecture.
+- assembly.s: GNU as extension to support the demo instruction set.
+- test.S: A simple test program: increments two registers and halts.
+- test.prj: A file of ASLi commands for running a test interactively.
+- simulator.c: A C simulator harness for creating compiled simulators.
+- exports.json: A list of functions required by the C simulator harness.
+
+The ASL specification defines the registers, memory, instruction fetch and
+instruction execute.  It also implements a simulator API that enable ASLi to
+use the specification as a simulator.
+
+## Building a test program
+
+Before running the simulator, we first need to assemble and link a test program.
+Given the limited instruction set, we can't write anything much more
+complicated than the following
+
+```
+#include "assembly.s"
+
+        .global _start
+
+        .text
+_start:
+        INC R1
+        INC R3
+        HALT
+```
+
+The instruction and register mnemonics are defined in the file `assembly.s` using
+macros.
+
+We can convert the test program `test.S` to an ELF binary using 'make test.elf'.
+
+    $ cd demo
+    $ make test.elf
+    clang-16 -std=c2x -E  test.S > test.s
+    as test.s -o test.o
+    ld test.o -o test.elf
+    nm test.elf
+    0000000000402000 T __bss_start
+    0000000000402000 T _edata
+    0000000000402000 T _end
+    0000000000401000 T _start
+
+## Running the demo specification in an interpreter
+
+To simulate execution of the test program using ASLi, load `demo.asl` into
+ASLi, load the ELF file `test.elf` and use `:step` to step through the program
+and the `PrintState` function (defined in `demo.asl`) to observe the processor
+state at each step.
+
+    $ ASL_PATH=.:.. ../_build/default/bin/asli.exe demo.asl
+    ASLi> :elf test.elf
+    Loading ELF file test.elf.
+    Entry point = 0x401000
+    ASLi> PrintState();
+    RUNNING PC=64'x401000 R=[ 64'x0 64'x0 64'x0 64'x0 ]
+    ASLi> :step
+    ASLi> PrintState();
+    RUNNING PC=64'x401001 R=[ 64'x0 64'x1 64'x0 64'x0 ]
+    ASLi> :step
+    ASLi> PrintState();
+    RUNNING PC=64'x401002 R=[ 64'x0 64'x1 64'x0 64'x1 ]
+    ASLi> :step
+    ASLi> PrintState();
+    HALTED PC=64'x401003 R=[ 64'x0 64'x1 64'x0 64'x1 ]
+    ASLi> :quit
+
+From the output of `PrintState` you can see that the program counter `PC` is
+incremented after every instruction, that the first instruction incremented
+`R[1]`, that the second instruction incremented `R[3]` and that the third
+instruction halted the processor.
+This is just about the most exciting program we can run using such a limited instruction set.
+
+ASLi can also accept commands from a "project file". For example, we could put
+all of the `:step` and `PrintState();` commands in a file `test.prj` and run
+the same test like this.
+
+    ASL_PATH=.:.. ../_build/default/bin/asli.exe demo.asl --project=test.prj
+
+We often use this with the LLVM project
+[FileCheck](https://llvm.org/docs/CommandGuide/FileCheck.html) tool in our
+integration tests.
+
+## Compiling the demo specification
+
+For larger architecture specifications, it can be more effective to compile the specification instead. To compile the specification, we first build a project file containing a sequence of ASLi commands to compile the specification to C code. There are multiple options for doing this, the "fallback" backend is the most portable.
+
+    ../_build/default/bin/asl2c.py --basename=sim --backend=fallback > sim.prj
+
+We then load the demo specification into ASLi and run the project file to generate C code. The configuration file `exports.json` is used to specify which ASL functions are called by hand-written C code.
+
+    ASL_PATH=.:.. ../_build/default/bin/asli.exe --project=sim.prj --configuration=exports.json demo.asl
+
+The generated code is in C files that start with the basename `sim` such as `sim_funs.c`.
+
+To compile and link the C code, we need to use some compiler and linker flags. We can use the `asl2c.py` script to get the right flags for each backend.
+
+    ASL2C=../_build/default/bin/asl2c.py
+    CFLAGS=`$ASL2C --backend=fallback --print-c-flags`
+    LDFLAGS=`$ASL2C --backend=fallback --print-ld-flags`
+
+We can now compile and link the `simulator.c` harness. To keep things simple, this file `#includes` the C files generated from the specification. For some choices of backend, you will need to use clang version 16 or later.
+
+    cc $CFLAGS simulator.c -o simulator $LDFLAGS
+
+And, finally, we can run the simulator. In this case, we run it for up to 20 steps or until the processor halts.
+
+    $ ./simulator test.elf --steps=20
+    Loading ELF file test.elf.
+    Entry point = 0x401000
+    Setting PC to 401000
+    RUNNING PC=64'x401000 R=[ 64'x0 64'x0 64'x0 64'x0 ]
+    RUNNING PC=64'x401001 R=[ 64'x0 64'x1 64'x0 64'x0 ]
+    RUNNING PC=64'x401002 R=[ 64'x0 64'x1 64'x0 64'x1 ]
+    HALTED PC=64'x401003 R=[ 64'x0 64'x1 64'x0 64'x1 ]
+
+## Making the demo ISA more realistic
+
+We kept the demo ISA to the bare minimum to make it easier to understand what all the pieces do. To make it more realistic, we invite you to add features such as the following. (For inspiration, you might look at the design of classic 8-bit microprocessors or at RISC processors.)
+
+- A decrement instruction
+- Add and subtract instructions
+- Load and store instructions
+- Conditional branch instructions
+- Add a stack and instructions to call a function and return from a function.
+- Add an interrupt mechanism
+

_posts/2024-12-20-using-interpreter.markdown

@@ -0,0 +1,34 @@
+---
+layout: post
+title: Using the ASL interpreter
+---
+
+The ASL interpreter reads ASL files specified on the command line and
+provides an interactive environment for executing ASL
+statements and expressions.
+
+```
+    $ asli
+                _____  _       _
+        /\     / ____|| |     (_)   ASL interpreter
+       /  \   | (___  | |      _    Copyright Arm Limited (c) 2017-2019
+      / /\ \   \___ \ | |     | |   Copyright (C) 2022-2024 Intel Corporation
+     / ____ \  ____) || |____ | |
+    /_/    \_\|_____/ |______||_|   ASLi 1.0.0
+
+    Type :? for help
+    ASLi> 1+1
+    2
+    ASLi> ZeroExtend('11', 32)
+    32'x3
+    ASLi> let x : bits(32) = ZeroExtend('11', 32);
+    ASLi> x
+    32'x3
+    ASLi> :quit
+```
+
+The ASL interpreter needs `prelude.asl` which is part of this repository. You
+either run the ASL interpreter from a directory containing `prelude.asl` or run
+the ASL interpreter from anywhere by setting `ASL_PATH` to point to a
+directory containing `prelude.asl`.
+

about.markdown

@@ -0,0 +1,28 @@
+---
+layout: page
+title: About
+permalink: /about/
+---
+
+Architecture Specification Language (ASL) is an executable language for writing
+clear, precise specifications of Instruction Set Architectures (ISAs).
+
+The ASL interpreter (ASLi) is an implementation of ASL that can execute ASL
+specifications either in an interpreter or by compiling via C code.  We include
+a small demonstration of how to use ASLi to build simulators for a toy
+architecture specification.
+
+This tool is based on Arm's open source
+[asl-interpreter](https://github.com/ARM-software/asl-interpreter) release with
+extensive modifications to
+
+* Change ASLi to support most of ASL version 1.0 requiring significant
+  changes to the AST, lexer, parser and typechecker.
+* Cleanup the "CPU" API that ASLi expects an ISA to implement.
+* Add support for compiling ASL specifications to C by adding
+  many transformations and multiple runtimes.
+* Add a demo ISA to illustrate how to generate simulators from
+  an ASL specification.
+* Split libASL out from ASLi to make it easier to reuse
+  parts of ASLi in other tools.
+* Add support for loading ELF files and executing binaries.