Hamlet Tutorial

Hamlet Tutorial

What is Hamlet

Hamlet is the domain-specific language (DSL) for defining the capability type system in Barrelfish.

For example (capabilities/caps.hl):

cap Memory abstract {
    address genpaddr base;  /* Physical base address of Memory object */
    pasid pasid;            /* Physical Address Space ID */
    size gensize bytes;     /* Size of region in bytes */
};

Hamlet is written in Filet-of-Fish, which is...

An embedding of C into Haskell, used for writing C code generators for Haskell-based domain specific languages. Instead of using C syntax combinators (as used in Flounder and Mackerel) FoF-based DSLs (such as Fugu and Hamlet) use backend which are actually semantic specifications of behavior, from which FoF can generates C code which is guaranteed to implement the given semantics. (see glossary)

Glossary

Read page 4 of the cap management documentation for a good glossary of capabilities terminology. Pages 7-17 has API specs for all the capabilities in Barrelfish OS.

Diagrams

• capabilities/caps.png - diagram of capabilities in Barrelfish OS master HEAD
• doc/000-overview/cap_hierarchy.pdf
• doc/000-overview/cap_translation.pdf
• doc/013-capability-mgmt/cap_types.dot

Hamlet/capabilities documentation

• Capabilities management design doc/documentation
• Barrelfish Specification (see "capabilities", pg. 17)
• Capabilities documentation on Guppy wiki
• exotic DSL species found in the barrel of fish - Barrelfish DSL docs (by Eric)
• Mothy, "Re: Capabilities in Barrelfish" - Explanation on how to figure out how to hack with capabilities
• Mothy, "Capabilities in Barrelfish" - PPT presentation (outdated apparently)

Code Inventory

User-level

• lib/barrelfish/capabilities.c - user-level capability management stuff
• usr/monitor/capops, usr/monitor/capops/include, usr/tests/capops - C code for user-level capabilities operations

Kernel-level

• capabilities/caps.hl - capabilities definition file
• tools/create_static_cap_dot.py - generate a dependency/hierarchy graph from a Hamlet file
• kernel/cap_delete.c - Kernel capability delete code
• kernel/include/cap_predicates.h - capability pre-declares (?)
• include/barrelfish_kpi/capabilities.h - required capabilities definitions
• build/x86_64/capabilities/*.c - Hamlet capabilities output C
• include/arch/x86/barrelfish/iocap_arch.h - IO capabilities for multiple sizes for different architectures

Hamlet language source

• tools/hamlet/Main.lhs - Hamlet executable entry point
• tools/hamlet/Parser.lhs - Hamlet syntax specification
• tools/hamlet/HamletAst.lhs - Hamlet AST...
• tools/hamlet/HamletBackend.lhs - Hamlet Backend...

For a much longer list of files to read (run in root of Barrelfish repository)...

# long list 
$ find . -name "*cap*" | grep -v ".git" | grep -v "depend"

# shorter list
$ find . -name "*capabilities*" | grep -v ".git" | grep -v "depend"

How to write a Hamlet file and understand what it means

• Add your Hamlet code to capabilities/caps.hl (read the diagrams to see the syntax for how to specify dependency relations).
• If you want your capability to be required, add your struct header to include/barrelfish_kpi/capabilities.h.
• Add capabilities to your user programs.
  • For a good example, see usr/pci/pci.c
  • Read lib/barrelfish/capabilities.c and usr/monitor/capops to see how to use capabilities in your user code.

Compiling Hamlet (on it's own):

ghc -i../tools/hamlet/. -odir  ./tools/tools/hamlet/. -hidir  ./tools/tools/hamlet/. -rtsopts=all --make  ../tools/hamlet/Main.lhs -o  ./tools/bin/hamlet $(LDFLAGS) -i..//tools/fof 

Running it:

./tools/bin/hamlet ../capabilities/caps.hl ./x86_64/include/barrelfish_kpi/capbits.h ./x86_64/capabilities/cap_predicates.c ./x86_64/capabilities/user_cap_predicates.c 

//TODO: syntax quick-start

//TODO: example capability

//TODO: explain the code flow for build and inside kernel