Skip to content

Creating a Pass

This document provides some minimal suggestion on how to build a new LiveHD pass.

Most LiveHD passes reside inside inou or pass. The only difference is that inou focuses on translation from some external tool to/from LiveHD while pass works on transformations from LiveHD to LiveHD.

Create a pass

Check the pass/sample directory for how to create a trivial pass.

  • Create pass/XXX directory

The typical is to have these files:

  • pass/XXX/pass_XXX.[cpp|hpp]: C++ and Header file to interface with lgshell
  • pass/XXX/XXX.[cpp|hpp]: C++ file to perform the pass over a Lgraph or LNAST API
  • pass/XXX/BUILD: the Bazel build configuration file
  • pass/XXX/tests/XXX_test.cpp: A google test checking the pass

Finally, add the new pass to main/BUILD

Pass Parameters and Common variables

One of the main goals is to have a uniform set of passes in lgshell. lgshell should use this common variable names when possible

    name:foo        lgraph name
    path:lgdb       lgraph database path (lgdb)
    files:foo,var   comma separated list of files used for INPUT
    odir:.          output directory to generate files like verilog/pyrope...

Some hints/comments useful for developers

Using clang when building

The regression system builds for both gcc and clang. To force a clang build, set the following environment variables before building:

CXX=clang++ CC=clang bazel build -c dbg //...

Perf in lgbench

Use lgbench to gather statistics in your code block. It also allows to run perf record for the code section (from lgbench construction to destruction). To enable perf record set LGBENCH_PERF environment variable

export LGBENCH_PERF=1

GDB/LLDB usage

For most tests, you can debug with

gdb ./bazel-bin/main/lgshell

or

lldb ./bazel-bin/main/lgshell

Note that breakpoint locations may not resolve until lgshell is started and the relevant LGraph libraries are loaded.

Address Sanitizer

LiveHD has the option to run it with address sanitizer to detect memory leaks.

bazel build -c dbg --config asan //...

Thread Sanitizer

To debug with concurrent data race.

bazel build -c dbg --config tsan //...

Debugging a broken Docker image

The travis/azure regressions run several docker images. To debug the issue, run the same as the failing docker image. c++ OPT with archlinux-masc image

  1. Create some directory to share data in/out the docker run (to avoid mistakes/issues, I would not share home directory unless you have done it several times before)
mkdir $HOME/docker
  1. Run the docker image (in some masc docker images you can change the user to not being root)
docker run --rm --cap-add SYS_ADMIN -it  -e LOCAL_USER_ID=$(id -u $USER) -v ${HOME}/docker:/home/user mascucsc/archlinux-masc

# Once inside docker image. Create local "user" at /home/user with your userid
/usr/local/bin/entrypoint.sh
  1. If the docker image did not have the livehd repo, clone it
git clone https://github.com/masc-ucsc/livehd.git
  1. Build with the failing options and debug
CXX=g++ CC=gcc bazel build -c opt //...

A docker distro that specially fails (address randomizing and muslc vs libc) is alpine. The command line to debug it:

docker run --rm --cap-add SYS_ADMIN -it -e LOCAL_USER_ID=$(id -u $USER) -v $HOME:/home/user -v/local/scrap:/local/scrap mascucsc/alpine-masc