Source Code Artisan

Understanding Git (Part III): Workflows

2022-11-17T10:21:09+00:00

Git is an extremely flexible and versatile tool to effectively and reliably version control files. However, there are a million ways to organize projects with Git, so it is important to agree on general usage guidelines. For example, good guidelines tell us where is the latest stable version of the code, how to propose changes or new features, etc. People sometimes call those guidelines a workflow.

A Git workflow is much like the “coding style” rules from a software project. Git does not enforce the guidelines, just as programming languages like C or Java do not enforce coding styles, although everyone contributing to the project is strongly encouraged to follow them to ensure that Git is used in a coherent, consistent and productive fashion.

In the remainder of this post, I will briefly describe two Git workflows. I had to use either of these workflows in virtually all the private and open-source projects that I contributed to. I assume that you read parts I and II of this series, so you know your branches, merges, remotes, etc.

NOTE: These are the post in the Understanding Git series:

Feature Branch Workflow

The idea is that main is a long-lived branch that is always kept in working order. As a user, you can always be sure that the latest main will compile and is broadly expected to work. It is also common to run regressions, such as nightly tests, in a Continuous Integration (CI) system to sanity check and ensure quality.

Contributors are required to propose changes via branches. A contributor’s workflow is typically like this:

Update your local copy of the repository with git fetch origin. Assume that origin is the remote’s name.
Create a branch off the latest commit in main and switch to that branch with git checkout origin/main -b my-feature-branch.
Make your changes.
Create commits in the branch my-feature-branch.
Push your feature branch to the remote when you are happy with the changes: git push origin my-feature-branch.

Other contributors are able to see your feature branch with the proposed changes at this point. Ideally, the changes will be reviewed giving rise to discussions. Websites, like GitHub, BitBucket and GitLab, have a great feature to assist with the review process: Pull Requests (PR) (GitLab calls them Merge Requests (MR)!). In this context, a PR is simply a “formal” request to merge your feature branch into another branch (typically main). Contributors will be able to review your changes, add comments and request amendments. You can upload those changes by creating more commits in my-feature-branch and then pushing with git push origin my-feature-branch as usual.

PRs are merged after the changes are reviewed and discussed – and hopefully agreed! – by clicking a button on the web UI. When that happens, the feature branch is merged by automatically creating a merge commit in main (think git merge from here!).

As discussed before, a branch is simply a pointer to a commit and we can create (and throw-away!) as many branches as we like. There is no need to keep maintaining and updating feature branches – hence why I never use git pull! –, so it is desirable to delete feature branches, like my-feature-branch, after the PR is merged to avoid having lots of unused branches cluttering the repository. In fact, this is so common that web UIs normally have an option to automatically delete the feature branch after a PR is merged. Alternatively, you can manually delete a branch like this:

# Delete branch locally
$ git branch -D my-feature-branch
# Delete remote branch
$ git push origin --delete my-feature-branch

Using Pull Requests (PR) and Merge Requests (MR)

First of all, PRs and MRs are basically the same thing: GitHub and BitBucket call them PRs and GitLab calls them MRs. You will be glad to know that these are created and used through the graphical web UI which is fairly intuitive. However, each website works in a slightly different way, so you need to look at their specific documentation to see how to create and merge PRs, make comments, approve, etc.

The key benefit of PRs is to create good spaces for reviewing and discussing the proposed changes before these are integrated into main. However, reviews can be lenghty and it is likely that your feature branch diverges from main by the time everything is agreed and ready to merge. If that is the case, you may need to incorporate the latest changes from origin/main into your feature branch by either rebasing or merging.

Forking Workflow

The feature branch workflow is great with a single remote repository and a few contributors. However, a couple of problems pop up as the number of contributors grows or when projects are open-source. First, each contributor will work on at least one feature branch, and usually many more, so the number of active branches tends to grow very quickly cluttering the repository. And second, and perhaps most importantly in open-source projects, you do not want every contributor to have permissions to directly modify the project’s official remote repository – what if someone deletes main?!

The forking workflow neatly addresses both problems. The idea is that only a small, select, trusted (!) group of core contributors has permissions to manage and modify the project’s remote repository – including merging PRs! Everyone else has either no permission (if it is a private project) or read-only permissions. Contributors with read-only permissions are able to clone the repository (with git clone) and fork it.

A fork is simply a copy in another remote of the project’s original remote repository. For example, lets say that I would like to contribute to the Mbed TLS project which is hosted in GitHub here, so I clone their repository in my local computer and origin is the only remote:

$ git clone https://github.com/Mbed-TLS/mbedtls.git
$ git remote -v
origin  https://github.com/Mbed-TLS/mbedtls.git (fetch)
origin  https://github.com/Mbed-TLS/mbedtls.git (push)

I wanted to propose changes to Mbed TLS. I had read-only access to their repository, so I forked Mbed TLS using the “fork” button in GitHub’s web UI. This creates my own copy of Mbed TLS in another remote here. I then configure a second remote in my local copy of Mbed TLS like this (notice the different URL!):

$ git remote add andresag https://github.com/andresag01/mbedtls.git
$ git fetch andresag

So my local repository is now aware of two remotes:

$ git remote -v
andresag        https://github.com/andresag01/mbedtls.git (fetch)
andresag        https://github.com/andresag01/mbedtls.git (push)
origin  https://github.com/Mbed-TLS/mbedtls.git (fetch)
origin  https://github.com/Mbed-TLS/mbedtls.git (push)

The remote origin is Mbed TLS’s official repository that I can only read while andresag is my fork which I have permission to both read and write. But both remotes are entirely different, so commits pushed into origin will not affect andresag and viceversa!

Back to the original task: how do we propose a change using the fork? We first create the change commits and push them to the fork. Then we use PRs! I like using the feature branch workflow in my forks, so the steps would be like this in the Mbed TLS example:

Update local repository: git fetch origin
Create feature branch: git checkout origin/main -b my-feature-branch
Make your changes.
Create commits in the branch my-feature-branch
Push feature branch to my for: git push andresag my-feature-branch
Create PR using the GitHub web UI as described here. Here is an example of a PR I created a long time ago for Mbed TLS from my fork.

The PR is then merged as usual after the review and discussion process.

Closing Thoughts on Workflows

The general workflows described above recommend, very broadly, how to use Git. However, using Git in a project has many more practical considerations. Here are a few things to look out for when contributing to, creating your own or simply using a project versioned with Git:

Projects regularly produce official releases. The release is taken from a commit that is usually tracked by either a Git branch or a tag. Ideally, you want to take an officially released, presumably stable, version of the project if you are a user.
The main branch is usually called main, master or primary. The latest commit in this branch is normally a stable version of the project as discussed above. Projects sometimes have a development or dev branch too where PRs and new features are merged using the feature branch workflow. In this case, the development branch may be unstable and it is only merged into main when an official release is produced.
CIs normally executes long-running tests in the main or dev branch (or both). Sometimes the CI also runs shorter sanity checks in feature branches after a PR is created. Ideally, the PR is only merged if the CI tests pass.

Conclusion

I described two workflows to help us use Git in a consistent and productive way. As mentioned along the way, I had to use either of these two approaches virtually everywhere I worked with Git. Also, I tend to use the feature branch workflow for my own forks to keep things organized. However, I only scratched the surface! There are many other approaches to using Git with their own advantages and disadvantages, so have a look at the way others use Git and learn from it!

This is the last post in this Git series (after parts I and II). Hopefully, these articles are helpful if you are getting started with Git or even if you have been using it for some time but perhaps it had not fully clicked. Happy times using Git!

Understanding Git (Part II): Working with Remotes

2022-11-11T10:21:09+00:00

In this post, I explained the very basics of Git. There was only one repository in your local machine and only one person making changes. That is well and good, but in practice many programmers contribute to a project: each needs a copy of the repository and many changes are made simultaneously. Version controlling these distributed projects is a big problem that Git solves brilliantly!

In this post, I will explain how this works and how you can use Git remote repositories without shooting-yourself-in-the-foot. I only assume that you are already familiar with the very basics of Git like commits and branches.

NOTE: These are the post in the Understanding Git series:

Remotes

Git relies on servers to version control a distributed project. The server manages the order in which changes are versioned and provides a consistent view of the files in the repository. The Git server also allows programmers to download local copies of the repository using the git clone <address> command.

Nowadays, it is popular to host Git repositories on the internet using websites like GitHub, GitLab or BitBucket. The website acts as the Git server for a project. For example, I can make a local copy of RISC-V’s Spike’s simulator, which is hosted in GitHub, like this:

git clone https://github.com/riscv-software-src/riscv-isa-sim.git

On success, Git will download, a.k.a clone, the repository and store it in my computer at a directory called riscv-isa-sim. As discussed before, Git repositories have a main branch which is called master in Spike’s case, so Git will checkout that branch right after cloning. You can check that with git branch.

From Git’s point of view, your clone is just a local copy of the repository which tracks Spike’s remote repository in GitHub. You can check this with git remote that outputs the following for my Spike clone:

$ git remote -v
origin  https://github.com/riscv-software-src/riscv-isa-sim.git (fetch)
origin  https://github.com/riscv-software-src/riscv-isa-sim.git (push)

After cloning, you will contact the repository for either of two reasons. You can upload, a.k.a push, new commits, i.e. changes, that you made or you can download, a.k.a fetch, commits that others have pushed to the remote since the last time you fetched. git remote is telling us that Git will contact the server at that HTTPS URL for either pushing or fetching. Git helpfully calls the remote origin so we do not have to keep typing that long URL!

Branches and Remotes

Recall that a branch is simply a pointer to a commit and that you can create an arbitrary number of branches with git branch. Newly created branches are only local to your repository until you push them to the Git server. In fact, there are two sets of branches in my Spike clone repository: your local branches and the remote’s branches! You can see all branches with:

$ git branch -a
* master
  remotes/origin/HEAD -> origin/master
  remotes/origin/confprec
  remotes/origin/cs250
...

The first line of output says that there is a local branch called master that is currently checked out, hence the *. If I were to create a new commit at this point, master would point to the new commit. The following lines start with remotes/origin/ meaning that these branches belong to the remote called origin i.e. the GitHub remote repository. Line 2 is special for two reasons:

origin/master is the server’s master branch.
remotes/origin/HEAD indicates the remote branch checked out when cloning.

When we said that Git “checked out” master after cloning, what happened is that Git saw that remotes/origin/HEAD pointed to origin/master, so it created a local branch, i.e. a pointer, called master which points to the same commit that origin/master references.

You can create local copies of other remote branches with git checkout. For example, git checkout confprec will create a local branch confprec pointing to the same commit that origin/confprec does. You can also checkout the commit that origin/confprec points to with git checkout origin/confprec. However, you cannot directly make a remote branch point to another commit (e.g. by using git commit) because git checkout origin/confprec will actually set the repository into detached state like this:

$ git checkout origin/confprec
Note: switching to 'origin/confprec'.

You are in 'detached HEAD' state. You can look around, make experimental
changes and commit them, and you can discard any commits you make in this
state without impacting any branches by switching back to a branch.
...
$ git branch
* (HEAD detached at origin/confprec)
  master

Multiple Remotes

You can configure an arbitrary number of remotes in your local repository. Each remote will have its own set of remote branches. For example, there would be three sets of branches if I had two remotes: one set of local branches and two sets of remote branches. Again, recall that remote branch names are prefixed with the remote’s name so that <remote_name>/master is a remote branch while master is a local branch.

I will discuss why having multiple remotes helps and how to use them in a future post.

Pushing to Remotes

As we discussed, we cannot directly modify the remote’s branches in our local repository, so how do we create new commits and push them to the server? The process is actually very simple:

Checkout a local branch, for example, git checkout master
Make your changes
Create a new commit in master with the changes using git add and git commit, and perhaps git merge too!
Run git push <remote_name> <branch_name>, so git push origin master in this case.

After running git push, Git automatically understands that your local master branch is tracking the remote’s origin/master branch, so Git will upload any new commits to the server and set origin/master to point to the same commit as master as shown below. In the case that you are pushing commits in a new branch my-new-branch that the server does not know about, Git will upload the new commits and create a origin/my-new-branch branch. Once you pushed, anyone will be able to see your new commits, and potentially a new branch, in the Git server.

Before and after pushing new commits in the local master branch to the Git server at origin.

git push will throw an error if you try to push commits to a remote branch that cannot be fast-forwarded. For example, this occurs when another programmer pushes a commit to origin/master before you push your own changes in the local master branch; in other words, origin/master and master diverged as shown below. If this happens, simply fetch from the remote (see below!), update your local branch with the latest changes (using, e.g., git merge or git rebase) from the remote branch that it is tracking and try to push again.

git push fails because origin/master and master branches diverged.

Fetching From Remotes

We obviously want to regularly download the latest changes that others have pushed to the server. We can do that with git fetch, for example, git fetch origin in the case of my local Spike repository. Git will download the latest commits from the server and update the remote branches i.e. the branches prefixed with origin/.

After git fetch, the remote branches in my local copy of the repository are synchronized with the server, but my local branches will be left untouched as shown below.

Git history before and after git fetch origin. New commits and branches are downloaded from origin while local branches are unchanged.

You can update your local branches to point to the latest commit if you wish to with git merge or git rebase just as discussed in this previous post. For example, the figure below shows the history of a repository before and after fetching and merging with:

git fetch origin
git checkout main
# Fast-forward main to reference the same commit as origin/main
git merge origin/main

Git history after fetching from origin and fast-forwarding master to reference new commits in origin/master.

Pulling: Fetching + Merging

git pull is a convenience command that combines the fetching and merging/rebasing functions into one (see documentation here). I seldom use it because I rarely ever update my local branches! I will explain why in a future post. I also think that git pull does a lot behind the scenes and this tends to trip new users, so I would recommend that you avoid it if you are new to Git.

Visualizing Git History

It can sometimes be helpful to visualize your Git history as the project grows with many commits, branches and remotes. Of course, you can use the venerable git log (see documentation here), but there are also many tools to assist you with this, such as gitk, GitKraken or Sourcetree. My favorite visualizer is tig, which stands for Text-mode Interface for Git, because it is light-weight, easy-to-use and works directly in the terminal. Here is a great blog post about tig if you are interested!

Conclusion

You should now be familiar with how Git tracks remote repositories using branches if you made it this far. We also covered how you can clone repositories from a server as well as fetch the latest changes and push your new commits to the server. In the next post, I will describe the workflow that many Git open-source projects use.

Understanding Git (Part I): The VERY Basics!

2022-11-09T07:43:09+00:00

Git is an awesome tool to version control your coding project. It tracks changes in your project files and helps coordinate how changes from many developers are put together. However, Git comes across as an over-complicated and difficult-to-use tool for newcomers. It appears to have a million ways of doing things and a two million ways to shoot-yourself-in-the-foot. The good news is that we can skip all the Git-pain! But we need to have a basic understanding of how Git works…

In this post, I will explain those basic ideas that I wished someone had explained to me 10 years ago when I started using Git. In a later posts, I will introduce other Git features and describe the Git workflow that many open-source projects hosted in (e.g.) GitHub or GitLab normally use.

Note that this is not a step-by-step tutorial on how to use individual Git commands – you can find that from plenty of sources! The goal of my posts is to describe, at a high-level, how Git works and take a tour of some of its key features. My hope is that after reading these posts you will understand enough of Git to know which feature works best for which situation in everyday usage without wrecking your repository!

NOTE: These are the post in the Understanding Git series:

Versions, Commits and Graphs

Coding takes a lot of effort! So hardware and software projects are developed incrementally over many (many!) years. Versions of the project will be released from time to time for users to, well…, use. A new version of the project may include new features, bug fixes, etc when compared to the previous version. Since coding projects are basically file repositories, a new version of the project makes changes to the files from the older version. Git tracks these changes in something called commits.

Lets consider an example. Imagine that I have a Git repository called crash that has a single file: the venerable main.c. Lets say that so far I only released version 1.0. I then develop a new feature and end up making some changes to main.c and create a new file foo.c. I am happy with my changes and would like Git to know about them, so I create commits tracking them. The new commits are part of version 2.0 of my project.

I create more commits as I continue to change and release crash. The project starts to have a Git history that we can visualise in a graph as shown below.

Git history of a project with four commits.

Creating Commits

Creating a commit is dead-easy! Run git add from the command line to let Git know which changes you would like to add to your commit; this is called staging. You can check which files are changed or staged with git status. Then create the commit using git commit. Git will open your favorite text editor where you can type a message describing what changes you are introducing. For example, you can commit changes in foo.c and all files in a directory bar/ like this:

git add foo.c ./bar
git commit

The commit message should be helpful, so do not just type ‘changes’ or ‘version 1’! Here are some guidelines on how to write good commit messages.

Anatomy of a Git Commit

The code below shows the contents of an old commit that I created while working on an open-source project (see here). The commit has four components:

The first line is an ID unique to each commit. Git generates this number by taking a SHA-1 hash of the repository contents.
The second and third lines state the author and when the commit was created.
The commit message is the text after the date line and before the line with diff. The message is usually shown indented and may be multiple lines long.
The remaining of the file shows the changes that this commit makes. Each file is shown in a separate diff block. Among other things, the diff states the lines that change between @@, added lines preceded by + and removed lines preceded by -.

You can view commit information using git show <commit_id>.

commit a685d4f28dce5ad6aeba3308514b8a5b6008ca0b
Author: Andres Amaya Garcia <andres.amayagarcia@arm.com>
Date:   Sun Dec 9 19:13:01 2018 +0000

    Add MBEDTLS_ERR_SHA1_BAD_INPUT_DATA to error.{h,c}

diff --git a/include/mbedtls/error.h b/include/mbedtls/error.h
index 0c3888987..57bbfeb6e 100644
--- a/include/mbedtls/error.h
+++ b/include/mbedtls/error.h
@@ -74,7 +74,7 @@
  * MD4       1                  0x002D-0x002D
  * MD5       1                  0x002F-0x002F
  * RIPEMD160 1                  0x0031-0x0031
- * SHA1      1                  0x0035-0x0035
+ * SHA1      1                  0x0035-0x0035 0x0073-0x0073
  * SHA256    1                  0x0037-0x0037
  * SHA512    1                  0x0039-0x0039
  * CHACHA20  3                  0x0051-0x0055
diff --git a/library/error.c b/library/error.c
index eabee9e21..564490e58 100644
--- a/library/error.c
+++ b/library/error.c
@@ -855,6 +855,8 @@ void mbedtls_strerror( int ret, char *buf, size_t buflen )
 #if defined(MBEDTLS_SHA1_C)
     if( use_ret == -(MBEDTLS_ERR_SHA1_HW_ACCEL_FAILED) )
         mbedtls_snprintf( buf, buflen, "SHA1 - SHA-1 hardware accelerator failed" );
+    if( use_ret == -(MBEDTLS_ERR_SHA1_BAD_INPUT_DATA) )
+        mbedtls_snprintf( buf, buflen, "SHA1 - Invalid input data" );
 #endif /* MBEDTLS_SHA1_C */

 #if defined(MBEDTLS_SHA256_C)

Branching and Merging

Imagine that a crash user finds a bug in version 3.0 after I started working in version 4.0 as shown below. Its a security issue and I need to work fast to release version 3.1 – i.e. version 3.0 plus the fix minus all version 4.0 changes. How do I keep track of my partial version 4.0 changes while I develop version 3.1?

Git has a great feature to get around this conundrum: branches. In a nutshell, a branch is a pointer to a commit in the Git history. Developers can create any number of branches, but by default, all repositories have an aptly called main branch (a.k.a primary or master) where most of the development changes occur. So I can create a version-3.1-fix branch from the commit with all version 3.0 changes. After developing my fix and releasing crash 3.1 my Git history looks like this:

Branch version-3.1-fix created off Commit #4.

Yay! I fixed the security bug via branch version-3.1-fix. However, a future version 4.0 would not include the security fix because the changes from branch version-3.1-fix are not in main! We can sort this out by merging version-3.1-fix into main: this creates a new commit in main that tracks all the changes from main and version-3.1-fix as shown below.

Before and after merging branch version-3.1-fix into main.

Checking Out, Creating and Merging Branches

Running git branch will show a list of branches and * next to the branch you are currently at. You can create a new branch at the current commit with git branch <branch_name> and you can checkout, i.e. change to another branch, using git checkout <branch_name>.

To merge a branch, ensure that you checkout the branch that will contain the merge commit, then run git merge. For example, I can merge branch version-3.1-fix into main like this:

git checkout main
git merge version-3.1-fix

NOTE: Sometimes merging gives raise to conflicts if the branches being merged both include commits changing the same files. Here is a good tutorial on how to resolve merge conflicts.

Rebasing

Later on, while developing crash 4.0, I had a shift in priorities. I started developing a super-crash feature that I later had to abandon due to time constraints in my release cycle. I did not want to throw this work away, so I put the partial super-crash changes on its own branch and continued creating commits in master. My history now looks like this:

Branch super-crash diverted from main, i.e. there are commits (Commit #7) in main that are not in super-crash.

However, it turns out that version 4.0 must include super-crash because my troublesome users really want that feature (perhaps they threatened to stop using crash if I refused!). Merging branch super-crash into main is not a great option because it would create yet another merge commit which I really want to avoid – it makes it harder to navigate my Git history. Thankfully, Git has another great feature to deal with this problem: rebasing.

We can say that Merge commit is the base commit of super-crash if I created that branch off commit Merge commit. Rebasing simply changes the base of the branch making it look like I started working on super-crash off another commit in main – in this case Commit #7 as shown below.

Before and after rebasing branch super-crash on top of main.

I can then fast-forward main such that both super-crash and main branches point to exactly the same commit like this:

Before and after fast-forwarding main.

Rebasing and Fast-Forwarding

Make sure you are currently on the branch whose base is going to change. Then run git rebase <new_base>. For example, we can rebase super-crash on top of main like this:

git checkout super-crash
git rebase main

We can then fast-forward main to match super-crash like this:

git checkout main
git merge super-crash

Git will fast-forward, instead of creating a merge commit, because super-crash contains all commits in main plus a few new ones.

NOTE: Sometimes rebasing gives raise to conflicts because the new base commit includes changes to the same files that the branch being rebased also changes. Here is a good tutorial on how to resolve rebase conflicts – the idea is generally the same as resolving merge conflicts.

Navigating Git History

As we discussed, Git allows you to view, a.k.a checkout, the files in the repository at one commit only. For example, git checkout main will checkout the files at the latest commit that the branch main references. But it is often necessary to navigate the Git history and checkout arbitrary commits, for example, while debugging. You can view a summary of the Git history of the current commit with git log. Here is some example output:

commit a685d4f28dce5ad6aeba3308514b8a5b6008ca0b (HEAD)
Author: Andres Amaya Garcia <andres.amayagarcia@arm.com>
Date:   Sun Dec 9 19:13:01 2018 +0000

    Add MBEDTLS_ERR_SHA1_BAD_INPUT_DATA to error.{h,c}

commit f7c43b3145b2952a0bc0e5fe4584df4bf47fe67e
Author: Andres Amaya Garcia <andres.amayagarcia@arm.com>
Date:   Sun Dec 9 19:12:19 2018 +0000

    Add parameter validation to SHA-1

This is showing that I currently checked out commit a685d4f28..., hence why (HEAD) is next to the ID, and an earlier commit f7c43b31.... You can checkout an arbitrary commit using git checkout <commit_id>.

Again, we can only view the repository files at one commit. So it is sometimes helpful to view the differences between two arbitrary commits in the Git history using git diff. For example, git diff main..super-crash will show you the differences in the repository, in diff format, between the latest commit in branch main references and the latest commit in branch super-crash.

Conclusion

We discussed the VERY basics of Git in this post. You should now have a rough idea about commits, branches, merging and rebasing. In the following posts, we will build on this knowledge to understand how Git helps versioning when a project is developed concurrently by many programmers. We will also discuss the workflow that many Git open-source projects use.

What’s So Good About RISC V?

2022-08-14T10:21:09+00:00

I was fresh out of university when I first heard about RISC V. The RISC V Foundation just set up shop and the big guys, like Google and IBM,¹ were throwing their weight behind it. There was suddenly renewed interest on open-source processors, like BOOM, and many IP businesses started emerging alongside RISC V. But “open” hardware or Instruction Set Architectures (ISA) are clearly not novel ideas,² ³ ⁴ and most certainly, neither are Reduced Instruction Set Computers (RISC). So what is so good about RISC V?

I pondered this question for some time and I will humbly provide my perspective. I first worked with computer architectures while pursuing a PhD. I then joined ARM as a CPU Architect for about a year before joining Codasip where I currently work. ARM is an established IP business that owns its well-known ISA while Codasip, among other things, provides RISC V IP and is a founding member of the RISC V Foundation. In short, I worked with both ARM, the incumbent, and RISC V, the challenger, as an engineer, so hopefully my perspective provides a slightly different insight.

I would like to stress that the opinions expressed in this post are solely my own and do not express the views or opinions of my employer. My opinion is of course that RISC V is a great project and here are three reasons why…

1. It’s Free!

And again, it’s FREE! Well, actually RISC V is sort of free. The ISA is free and “open” in the sense that anyone can download the manuals and use them however they like. For example, an enterprising group of engineers can develop and commercialize RISC V processors without paying a penny in licenses or royalties for the ISA. Anyone can configure or customize RISC V however they see fit and use it for research, business or any other purpose. Even better, anyone can choose to ignore RISC V compliance and modify it however they see fit to make a new ISA based on RISC V – we could call it RISC VI or RISC V++!

But there is a (tiny) catch! You need to be a member of the RISC V International Association to really be part of RISC V. RISC V International oversees and fosters the RISC V community including its strategy, technical committees and workgroups, technical deliveries, etc. You must be a member if you want to participate in discussions, simply ask a technical question or have any kind of influence or voice in RISC V.⁵ Of course, becoming a member of RISC V International costs $$$!

Therefore, RISC V is more of an open standard, like Bluetooth⁶ or DDR⁷, as opposed to a regular open-source project. The ISA specifications are available online and you can submit patches via GitHub,⁸ but anything significant, like a new instruction, will probably be dismissed if you are not a member and the ideas were not previously discussed in members-only forums.

NOTE: The RISC V International Association is a non-profit organization incorporated in Switzerland back in 2020 to “manage strategic risk for [the] community investing in RISC V for the next 50+ years”.⁹ Feel free to read that in whatever geopolitical context you like!

The good news is that RISC V International memberships are relatively cheap, that is, when compared to buying an architecture license. Also, you do not have to ask anyone’s permission to use RISC V. You just need to get on with the work! In contrast, you cannot touch proprietary IP with a ten-foot pole for ages while your organization negotiates the purchase of an architecture license with, say, ARM. And most importantly, RISC V gives you the freedom to configure, customize or modify the ISA however you want without having to ask anyone for permission, and this brings us to the second point…

2. Innovation

Imagine that you are designing a new processor optimized for machine learning applications, so you decide that it needs a matrix coprocessor. Your new processor will implement a proprietary ISA, but there is a problem! Your legal department is saying, after the requisite few weeks of delays, that you are forbidden from extending the proprietary ISA with custom instructions to easily interface with your matrix coprocessor even though you purchased an architecture license. Perhaps the restriction is in the license agreement! What do you do?

Situations like this happened before. Apple wanted a matrix coprocessor, known as Apple Matrix coprocessor (AMX), in their M1 chip which implements the (proprietary) ARMv8-A ISA.¹⁰ However, ARM “has long resisted adding custom instructions to their ISA” as Erik Engheim pointed out.¹¹ Apple did not end up extending the ISA in the usual way; AMX instructions are posted to the coprocessor via the processor’s store unit instead.¹⁰ Also, Apple did not document AMX and we are only aware of it thanks to Dougall Johnson’s reverse engineering efforts!¹⁰ The idea of matrix coprocessors caught on and ARM eventually introduced a proper Scalable Matrix Extension (SME) for their ARMv9-A ISA although this took years and the M1 was in production by then.¹²

The point of this story is that closed, proprietary ISAs restrict innovation. You cannot do whatever you want with those ISAs without asking permission, and permission may not always be granted!¹³ This is not a problem with an open ISA like RISC V. You do not have to ask permission to extend the ISA if the current specification does not suit your needs. Extending RISC V is even encouraged and the designers helpfully point out free opcodes for custom instructions in the ISA specification!¹⁴ There is also a huge amount of freedom to tune the core components of the ISA in an implementation, like the memory model.

The freedom to extend the ISA allows engineers to create innovative and unique RISC V processors. For example, you can be sure that two processors implementing, say, the proprietary ARMv8-M ISA only differ in their microarchitecture (e.g. slightly different pipeline, perhaps a coprocessor, etc). In contrast, two RISC V processors could have a different microarchitecture and implement different (custom) ISA extensions such that one processor is great for machine learning while the other is great for real-time applications. The freedom to innovate creating these domain-specific ISA extensions, not just the microarchitecture, is specially important as we reach the end of Moore’s law and Denard scaling.

Extending the ISA is so appealing that a few years ago ARM opened up the possibility for licensees to build custom instructions.¹⁵

Additionally, the freedom to innovate with RISC V enables businesses to come up with products that have clear differentiator features, like custom instructions and coprocessors, and even entirely novel products or services. RISC V also opens up great opportunities for research. And this brings us to my final point…

3. Community

An ISA would not be complete if it does not have a great community around it. RISC V absolutely nailed this point! A great open-source, research and business community sprung up to create a rich software (compilers, operating systems, tools, etc) and hardware (processors, coprocessors, etc) ecosystem and offer IP or services around the ISA.

My employer, Codasip, is a great example of a business in the RISC V community.¹⁶ Codasip’s flagship product, Codasip Studio, is an innovative EDA toolset that allows engineers to quickly design and customize processors and ISAs. Of course, you can use Studio to customize any ISA, but it would be a hard sell if an open ISA, like RISC V, was not available and customers could only rely on proprietary ISAs that restrict innovation. Similar to Codasip, there are many other businesses and projects who depend on an open ISA, like RISC V, to exist.¹⁶

Conclusion

So what’s so good about RISC V? It is free, enables innovation and has a great community around it! Those are, in my opinion, the three key points that make RISC V a compelling ISA today. Personally, this is also why I decided to join the RISC V community!

References

Here is a list of members in the RISC V Foundation. ↩
OpenRISC ↩
OpenPOWER ↩
OpenSPARC ↩
RISC V Technical Forums ↩
Bluetooth SIG develops and maintains the Bluetooth standards ↩
JEDEC develops and maintains the DDR (and many other) standards ↩
RISC V’s GitHub ↩
RISC V history ↩
The Apple Matrix coprocessor (AMX) is largely undocumented. Developer Dougall Johnson has reversed engineered a lot of it. See here ↩ ↩² ↩³
Erik Engheim, The Secret Apple M1 Coprocessor, see here ↩
ARM, Introducing the Scalable Matrix Extension for the Armv9-A Architecture, see here ↩
There certainly are advantages for tightly controlled ISAs. For example, the ISA does not “fragment” in the sense that processors implement the same core set of instructions, so it is easier to have software that is written once and runs everywhere. I personally still favor innovation! Solutions to mitigate problems like fragmentation exist anyway. ↩
See Chapter 26 (Extending RISC V) from The RISC V Instruction Set Manual Volume I: Unprivileged ISA. ↩
Kevin Krewell, Arm Responds to RISC V, and More, see here ↩
Many of these businesses are also RISC V members. See here ↩ ↩²

Analyzing Real-Time Systems

2022-01-26T10:21:09+00:00

In a previous post (here) we discussed what are and the types of real-time systems. We also gave some examples to highlight their importance and clarify some of the confusion regarding the real-time and run-time performance tradeoff. In this post, we will focus exclusively on “hard” real-time systems and how they are statically analyzed (i.e. before the program is run) to guarantee that deadlines are never missed.

NOTE: You can find a great survey of hard real-time analysis methods and tools (both commercial and open-source) here. I will only discuss one method in this post, but there are alternatives.

Overview

Our goal is to ensure that the hard real-time system never misses a deadline. To achieve that, we are going to count how many clock cycles the processor will take to run our given hard real-time program through any possible execution path. Then we will select the code path that takes the longest to run and declare that our Worst-Case Execution Time (WCET). The hard real-time system will meet all its deadlines if the WCET is smaller than the deadline, otherwise the system needs to be re-designed so that it does meet its deadlines. For example, the WCET to draw a frame must be less than 16 ms if we would like the Chrome browser to operate at 60 fps although that is not a hard real-time application!

NOTE: I do mean counting how many clock cycles it takes to execute each add, sub, ld, st, etc instruction. For this reason, I have sometimes heard people call this method cycle-counting analysis.

The worst-case idea is actually very important and perhaps the most troublesome in this analysis. For example, the WCET of an if-statement is given by the branch with the longest run-time. And this is regardless of how often that particularly long-running branch of the if-statement is executed because in practice it is hard to know how many times this branch is run. So our estimated program run-time can add up in unrealistic ways when the code has widely different best-case and worst-case execution times!

Lets consider the simple pseudo-code example below to nail down this idea. The for-loop executes the if-statement N times and the run-times of statements A and B are 2 ms and 10 ms respectively. So the WCET for this code is 10 * 10 ms = 100 ms because we assume that the program is invariably going to execute the worst-case branch B from the if-statement. However, it might be the case that B is only executed 50% of the time on average, so a more realistic run-time for this code would be 5 * 2 ms + 5 * 10 ms = 60 ms. Even in this simple example we are over-estimating the WCET by about 40%! But we cannot improve our WCET with the information provided because we have no idea how frequently x(i) evaluates to true or false. If we heavy-handedly assumed that x(i) is true say 50% of the time, but its actually 60% or 70% in practice, we are at risk of missing deadlines.

for (i = 0; i < N; ++i)
    if x(i)
        A
    else
        B

It is for these reasons that we can often hear engineers saying that caching and other hardware optimization features are incompatible with hard real-time analysis. The idea of caching is to use smaller and faster memories close to the processor to reduce the time it takes to load or store data. However, caching makes the run-time of load and store instructions difficult to estimate because we cannot tell whether a memory access will result in a cache hit, so it has short run-time, or a miss so we need to check slower memories which takes longer. Therefore, the real-time analysis must often assume that the caches will miss, since this is the worst-case, and the overall WCET estimate will be far detached from the real run-time.

NOTE: As far as I know, hard real-time systems often rely on small processors, like the ARM Cortex-M0, or processors with relatively simple pipelines and caches because these are easier to analyze. For example, you can see this list of targets supported by a commercial real-time analysis tool. There is also extensive research to try to account for more complex processors, but I have not looked much into it.

In summary, we would like to make WCET analysis easier for ourselves to check whether the system will meet its deadlines. We can do so by ensuring that the program’s worst-case and best-case run-times are not outrageously different. We can also use simpler processors that do not have complicated features, like caching, that introduce unpredictability in the run-time of instructions. And without further ado, lets analyze a simple program to see how WCET works. We will perform the analysis in two steps:

Control Flow Graph (CFG) construction
Implicit Path Enumeration (IPET)

Control Flow Graph

We will analyze the following C program that implements bubblesort to sort 10 integers. I took this code from the BEEBS benchmarks mostly because it is relatively straight-forward to analyze.

#define FALSE 0
#define TRUE 1
#define NUMELEMS 10

void BubbleSort(int Array[]) {
    int Sorted = FALSE;
    int Temp, Index, i;

    for (i = 0; i < NUMELEMS; i++) {
        Sorted = TRUE;
        for (Index = 0; Index < NUMELEMS; Index++) {
            if (Index >= NUMELEMS - i) {
                break;
            }
            if (Array[Index] > Array[Index + 1]) {
                Temp = Array[Index];
                Array[Index] = Array[Index + 1];
                Array[Index + 1] = Temp;
                Sorted = FALSE;
            }
        }

        if (Sorted) {
            break;
        }
    }
}

The C code above is there mostly for illustration purposes because we are actually interested in the disassembly of that program’s binary. Analysing the disassembly, as opposed to the C code, takes into account any optimizations and transformations introduced by the compiler, so we eliminate potential errors in our estimation. In this case, it looks like the compiler inlined the BubbleSort function into another function called benchmark to produce the code shown below. The program was compiled with LLVM 10 for the ARMv6-M architecture.

00000074 <benchmark>:
  74:	b5f0      	push	{r4, r5, r6, r7, lr}
  76:	2000      	movs	r0, #0
  78:	2164      	movs	r1, #100	; 0x64
  7a:	4a0d      	ldr	r2, [pc, #52]	; (b0 <benchmark+0x3c>)
  7c:	6813      	ldr	r3, [r2, #0]
  7e:	2601      	movs	r6, #1
  80:	460c      	mov	r4, r1
  82:	4615      	mov	r5, r2
  84:	e006      	b.n	94 <benchmark+0x20>
  86:	602f      	str	r7, [r5, #0]
  88:	606b      	str	r3, [r5, #4]
  8a:	2600      	movs	r6, #0
  8c:	1e64      	subs	r4, r4, #1
  8e:	1d2d      	adds	r5, r5, #4
  90:	2c00      	cmp	r4, #0
  92:	d004      	beq.n	9e <benchmark+0x2a>
  94:	686f      	ldr	r7, [r5, #4]
  96:	42bb      	cmp	r3, r7
  98:	dcf5      	bgt.n	86 <benchmark+0x12>
  9a:	463b      	mov	r3, r7
  9c:	e7f6      	b.n	8c <benchmark+0x18>
  9e:	2e00      	cmp	r6, #0
  a0:	d103      	bne.n	aa <benchmark+0x36>
  a2:	1e49      	subs	r1, r1, #1
  a4:	1c40      	adds	r0, r0, #1
  a6:	2864      	cmp	r0, #100	; 0x64
  a8:	d1e8      	bne.n	7c <benchmark+0x8>
  aa:	2000      	movs	r0, #0
  ac:	bdf0      	pop	{r4, r5, r6, r7, pc}
  ae:	46c0      	nop			; (mov r8, r8)
  b0:	00000164 	.word	0x00000164

The first step in the analysis is to construct a Control Flow Graph (CFG) out of this disassembly. The CFG is a directed graph representation that captures the control-flow information, i.e. branches, conditionals, loops, etc, from the program. The nodes of a CFG represent blocks of code without branches or branch destinations, while the edges are branches as shown in the figure below. Each node and edge is given an identifier (e.g. block0 or b0 for short, e0, b1, etc) for convenience and a cost coefficient.

The cost coefficient represents the worst-case cost, in clock cycles, of executing the sequence of instructions in a node’s block of code. And this is where the choice of processor is very important! A cost model of the chosen processor is used to estimate the time that the microarchitecture takes to execute each instructions. From this, we calculate each node and edge’s cost coefficient. If the processor has unpredictable features like complex caching then its hard to approximate the worst-case run-time of instructions, and as a result, the cost cofficients could be way off-board.

In our case, the cost model is very simple because hard real-time analysis targets a processor similar to an ARM Cortex-M0 which has a very simple microarchitecture with the very predictable execution times listed here. For example, node b6 has a compare (cmp) instruction followed by a conditional branch (bne) with 1 and 3 clock cycles of run-time respectively, so the cost coefficient for b6 is 1 + 3 = 4.

NOTE: I generated this CFG using a tool I jointly developed with a colleague during my PhD. It takes an ARMv6-M program binary as an input along with a configuration file to produce the WCET estimate (among other things like the CFG!). The tool is open-source and is available here.

NOTE: CFG’s are not unique to real-time analysis. They are used in many other applications like compilers.

Control Flow Graph for the bubblesort program. block0 is the start of the function. block10 is a placeholder exit node to ensure that the CFG has a single exit point. The exit node has no "cost" because it does not include any real instructions.

Integer Linear Programming

The second part of the analysis uses Implict Path Enumeration (IPET) to calculate the WCET. IPET derives an Integer Linear Programming (ILP) problem by combining the flow information and coefficients encoded in the CFG. It consists of an objective function, that encodes the run-time of the code when solved, and a set of constraints over the variables in that function.

The ILP problem for our bubblesort CFG is shown below. It tells us that the run-time of the code will be 11 clock cycles (i.e. b0’s cost coefficient) multiplied by the number of times that node b0 in the CFG is executed plus 9 clock cycles multiplied by the number of times that node b1 is executed and so on. But the ILP also gives us a few restrictions or contraints when calculating a solution for the variables b0, b1, e4, e6, etc. For example, there is an input constraint b0 = 1 meaning that the code at node b0 can only be executed once on entry to the function which makes sense because that code is not within a loop. There is also an output constraint b0 = e0 restricting edge e0 to be “executed” as many times as the code at b0 is executed.

The ILP formulation is constructed from a simple graph traversal of the CFG. Each node and edge has a cost coefficient (or 0) and a unique identifier; the objective function is a summation of these terms. The majority of the constraints relate the number of times that the edges are followed with how often the node is executed. Loop bounds are the only constraints that are difficult to construct as the information is not readily available in the CFG, so these bounds are either input manually or estimated automatically using a tool like SWEET.

/* Objective function */
max: 11 b0 + 9 b1 + 5 b2 + 6 b3 + 7 b4 + 4 b5 + 4 b6 + 6 b7 + 11 b8 + 0 b10
     - 2 e4 - 2 e6 - 2 e9 - 2 e11;

/* Output constraints */
b0 = e0;
b1 = e1;
b2 = e2;
b3 = e3 + e4;
b4 = e5 + e6;
b5 = e7;
b6 = e8 + e9;
b7 = e10 + e11;
b8 = e12;
b10 = 1;

/* Input constraints */
b0 = 1;
b1 = e0 + e10;
b2 = e5;
b3 = e2 + e7;
b4 = e1 + e4;
b5 = e6;
b6 = e3;
b7 = e9;
b8 = e8 + e11;
b10 = e12;

/* Loop constraints */
10 b0 <= b1;
b1 <= 10 b0;
10 b1 <= b4;
b4 <= 10 b1;

Finally, we need to solve the ILP problem by maximizing the objective function as we would like to calculate the worst-case execution time. We can do just that with a nice tool called lp_solve that you probably have installed in your Linux computer without realizing. The lp_solve output for our bubblesort ILP is shown below, so the WCET estimate for this code is 1810 clock cycles!

Value of objective function: 1810.00000000

Actual values of the variables:
b0                              1
b1                             10
b2                            100
b3                            100
b4                            100
b5                              0
b6                             10
b7                             10
b8                              1
b10                             1
e4                             90
e6                              0
e9                             10
e11                             1
e0                              1
e1                             10
e2                            100
e3                             10
e5                            100
e7                              0
e8                              0
e10                             9
e12                             1

Conclusion

And that is it! We statically analyzed a hard real-time implementation of bubblesort and estimated a WCET. It is worth pointing out that this is frustratingly difficult in practice as the complexity of the problem increases very quickly when programs are larger or the processor has more features. Also, there is a lot of manual labour involved in getting the right parameters, like look bounds, and constantly re-designing bits of your system to try to fulfil the real-time constraints. But hopefully this was a helpful introduction to hard real-time systems!

What are Real-Time Systems?

2022-01-25T08:21:09+00:00

Explaining research ideas clearly was perhaps my most difficult undertaking while pursuing a PhD. More often than not, my explanations were frankly incomprehenible and that is entirely my own fault. But sometimes my audience had inaccurate ideas and misplaced expectations about the subject matter. I found real-time systems to be one of those misunderstood topics. In the remaining of this post, I will attempt to clear up some of the confusion and explain what real-time systems are.

NOTE: This is the first post of a two-part series about real-time systems. The following post will mostly talk about hard real-time analysis.

What are Real-Time Systems?

Every applications imposes a set of constrains that computer engineers are constantly battling to meet. Of course, a constraint is (almost!) always that the program should produce the correct result. But it is also common to want a system to perform a task as fast as possible, these are run-time constraints, or to ensure that a device’s battery life lasts longer, as in a constraint on power consumption. A real-time system is simply a system that has timing constraints in addition to correctness and (potentially) run-time or power requirements. In a real-time system, the time when a result is produced (i.e. before a deadline) is as important as ensuring that the result is correct.

Lets consider a couple of use-cases. Classic examples of real-time applications are safety-critical systems such as cardiac pacemakers, engine control systems and avionics. Clearly, these systems must always operate correctly and deliver results on time (i.e. before a deadline) otherwise patients may die, your car engine might explote or a plane could crash. Interactive systems are also good examples of real-time systems, although not quite as critical, such as mobile phones or desktop PCs. For example, we like responsive PCs that keep the mouse pointer moving smoothly, windows switching quickly and videos or music playing clearly. These are all real-time tasks and the deadline usually is “before the user gets annoyed”. Unresponsive PCs make unhappy and frustrated users, and I have been known to angrily strike the keyboard once or twice when this happens!

NOTE: A coincidentally pedantic note on the use of the words run-time and runtime. Lots of people (myself included!) often use these words interchangeable, but I was very fortunate to have been corrected by someone peer reviewing my journal submission. So nowadays I use the word run-time to mean the length of time that something takes to run. I also refer to a program’s status of being running as run-time, e.g. as in variables are resolved at run-time. In contrast, I use runtime to mean the environment in which a program is running, e.g. as in a runtime library. These definitions are by no means perfect, but I strive to be consistent!

Real-Time Systems are NOT…

Fast, power-efficient, secure, small, etc. Or rather, real-time systems are not necessarily fast, power-efficient, secure, small, etc. These are individual constraints that a system could be required to meet, but neither of them implies the other. Many people are particularly puzzled to hear that a fast system, i.e. the run-time of a task is very short, does not mean that it is real-time. In fact, real-time are systems often slower than their non-real-time counterparts due to the overheads inherent to concurrent operation, such as context switching, synchronization, etc.

Garbage collection is an example that neatly illustrates this real-time and run-time performance tradeoff. The collector is a component of the runtime environment responsible for automatically reclaiming unused memory and repurposing it to fulfil future dynamic memory allocation requests. Its work is critical to both the real-time and run-time performance of many programming languages like Python, JavaScript, Java, etc.

Stop-the-world garbage collectors. Each bar represents the execution in a single core. White regions are the execution of the user's program threads and shaded regions correspond to the collector's execution.

The simplest and fastest collectors are stop-the-world: the user’s program is stopped while the collector does its job and then the program is restarted as shown above. The run-time performance of these collectors is great because there is little interaction with the user’s program. In fact, it is straight-forward to run these collectors in a single-core or in parallel across multiple cores to reclaim memory faster. But the real-time performance of the system is atrocious either way because the user’s program is stopped (i.e. paused, does not run) while the collector runs, so any task that the program is supposed to do is delayed. Concurrent collectors mitigate this real-time problem by either running collection operations interleaved or in parallel with the program as shown below.

Concurrent garbage collectors.

However, concurrent collectors require a lot of synchronization to make sure the system works properly. Sadly, the extra synchronization often incurs high run-time overheads although this is unavoidable for the system to operate in real-time.

You can clearly see this tradeoff for yourself in this presentation about the JavaScript V8 Engine which is used in Chrome. Ideally, the web browser runs at 60 fps to avoid jank, so each frame must be generated in about 16 ms. But using a stop-the-world garbage collector caused earlier Chrome versions to often miss these deadlines. More recent Chrome versions use a mostly concurrent collector. The video below compares the very visible effects of both collectors.

Types of Real-Time Systems

You might have noticed that not all real-time systems are the same. It is important to consider the kind and strictness of timing requirements when engineering such systems. So it is common to clasify real-time systems as:

Soft Real-Time: There are many systems, like phones, tablets, etc, where it is desirable to meet deadlines, but there is no harm if deadlines are missed occasionally. For example, we said that ideally Chrome runs at 60 fps although nobody will die if sometimes it does 55, 58, 56 fps! In other words, it is desirable for the real-time system to meet all its deadlines, but in practice, its acceptable if some deadlines are missed because the worst consequece is perhaps an annoyed user.
Hard Real-Time: The system must always meet deadlines if hard real-time operation is required. Failure to meet a deadline is equivalent to an incorrect calculation and can result in catastrophic consequences such as the death of a patient or an airplane crashing. Cardiac pacemakers and avionics are good examples of hard real-time systems.

Naturally, the approach for engineering and testing soft real-time systems is a lot more informal. The system is developed and empirical experiments are run in various settings to ensure that most deadlines are met i.e. that the frequency of missed deadlines is below a threshold. I have even heard of engineers testing soft real-time systems with slow processors and then switching to faster ones (or cranking up the clock!) just to make extra sure that the final product does meet most deadlines. In contrast, there are formal static analysis methods to evaluate hard real-time systems and guarantee that no deadlines are missed under any circumstance. I will describe one such method in the next blog post.

Conclusion

In conclusion, real-time systems are simply systems that have timing contraints. That is, the device must perform a task before a deadline. Broadly speaking, real-time devices are either soft or hard real-time depending on how strict we need to be about meeting deadlines. In the following post, we will focus almost exclusively on how to statically analyze hard real-time programs to guarantee that timing requirements are always met.

Integrated Hardware Garbage Collection for Real-Time Embedded Systems

2021-09-30T10:21:09+00:00

I recently completed my thesis while pursuing a PhD in Computer Science at the University of Bristol. The thesis, titled Integrated Hardware Garbage Collection for Real-Time Embedded Systems, is shared below under the Creative Commons Attribution-NonCommercial 4.0 International license.

The thesis is related to garbage collection, computer architecture, memory management, among other topics. I continue to be interested in the subject, so please feel free to reach out with questions, comments, ideas, thoughts, etc. My contact details are here and at the bottom of this page.

NOTE: A lot of the articles in this blog are about findings or ideas that I came across while working on my PhD thesis!

Abstract

Modern programming languages, like Python and C#, provide productivity and trust benefits that are key in managing the growing complexity of computer systems. However, modern language implementations rely on software garbage collection which imposes high overheads and unpredictable pauses. This is tolerable in large computer systems, like desktops and servers, but impractical for real-time embedded systems. Hence modern languages are rarely used to program embedded devices.

This thesis investigates a shift in architecture towards hardware garbage collection to better support modern languages in embedded devices while meeting their unique performance and real-time requirements. We present an Integrated Hardware Garbage Collector (IHGC) that demonstrates this approach: a collector that is tightly coupled with the processor and runs continuously in the background. Our design allocates a memory cycle to the collector when the processor is not using the memory. The IHGC achieves this by careful subdivision of collection work into single-memory-access steps that are interleaved with the processor’s memory accesses. We also introduce a static analysis technique to guarantee that real-time programs are never paused by the IHGC. As a result, our collector eliminates run-time overheads and is suitable for real-time embedded systems.

The IHGC is evaluated through simulation based on a hardware implementation model using modern fabrication technologies. Our experiments indicate that the IHGC offers 1.5-7 times better performance compared to a conventional processor running a software garbage collector. In addition, our static, real-time analysis technique was evaluated through practical use cases showing that an IHGC system meets specific timing constraints. This thesis concludes that the IHGC delivers in real-time the benefits of garbage collected languages without the complexity and overheads inherent in software collectors.

Download

You can download the thesis from here.

The following publications are related to the contents of the thesis:

A. Amaya García, D. May and E. Nutting, Garbage Collection for Edge Computing, in 2020 IEEE/ACM Symposium on Edge Computing (SEC), 2020, pp. 319-319. Accessible here.
A. Amaya García, D. May and E. Nutting, Integrated Hardware Garbage Collection, ACM Transactions on Embedded Computer Systems (TECS), 2021. Accessible here.

Dynamic Linking to a Different libc

2021-05-08T10:21:09+00:00

Sometimes it is necessary to run a dynamically linked program using an alternative libc from the system’s. In the remaining of this post, we will take a look at a few ways of doing that in Linux.

NOTE: The contents of this post were put together from several StackOverflow answers that were helpful to me when dealing with this problem (see here and here).

Finding Dynamic Library dependencies

Lets start from the beginning: How do you find the dynamic library dependencies of an existing executable? There are two easy ways to do this:

ldd: This command is perhaps the most straight-forward method. Here is an example.
```
$ ldd $(which ls)
     linux-vdso.so.1 (0x00007ffe867fa000)
     libcap.so.2 => /usr/lib/libcap.so.2 (0x00007f6faa5bd000)
     libc.so.6 => /usr/lib/libc.so.6 (0x00007f6faa3f0000)
     /lib64/ld-linux-x86-64.so.2 => /usr/lib64/ld-linux-x86-64.so.2 (0x00007f6faa607000)
```
The output is mostly self-explanatory: The first line is Linux’s vDSO (Virtual Dynamic Shared Object) which is a small shared object that we do not have to care about. libcap and libc in the second and third lines of output are library dependencies while the last line is the dynamic linker/loader (this runs implicitly whenever you execute a dynamically linked program).

readelf: This is the classic utility to display information about ELF files (see here). Run it like this to display the contents of the ELF’s dynamic section:

$ readelf -d $(which ls)
Dynamic section at offset 0x21a58 contains 28 entries:
  Tag        Type                         Name/Value
 0x0000000000000001 (NEEDED)             Shared library: [libcap.so.2]
 0x0000000000000001 (NEEDED)             Shared library: [libc.so.6]
 0x000000000000000c (INIT)               0x4000

Again, the content is mostly self-explanatory.

NOTE: These commands can be useful to track down which libraries you are missing!

NOTE: ldd and readelf do not show information about libraries loaded at run-time using dlopen. Use other utilities for that!

NOTE: The advantage of readelf over ldd is that the it shows you the ELF’s rpath (if any). Read on for more information about the rpath.

Linking Against a Specific libc

By default, ELF files are linked against the system’s libc (usually found at /usr/lib/). We will explore three ways to link against another libc.

NOTE: The libc consists of many shared objects. The versions of these files must match since they contain some hard-coded information (e.g. file paths), so do not attempt to link against shared objects from different libcs.

Method 1: `LD_LIBRARY_PATH`

This is perhaps the easiest way if you have an already built ELF executable. The LD_LIBRARY_PATH is an environment variable with a colon-separated list of paths telling the linker where to look for libraries. Here is a usage example:

$ export LD_LIBRARY_PATH=/home/andres/Repos/glibc-2.33/install/lib
$ ldd $(which ls)
        linux-vdso.so.1 (0x00007fff889ec000)
        libcap.so.2 => /usr/lib/libcap.so.2 (0x00007f61144fa000)
        libc.so.6 => /home/andres/Repos/glibc-2.33/install/lib/libc.so.6 (0x00007f6114337000)
        /lib64/ld-linux-x86-64.so.2 => /usr/lib64/ld-linux-x86-64.so.2 (0x00007f6114544000)

Notice that ldd resolved the libc.so.6 to the alternative libc indicated in the LD_LIBRARY_PATH. However, my alternative libc does not contain libcap.so.2, so this shared object was resolved using the system’s libraries at /usr/lib.

Changing the LD_LIBRARY_PATH works well in most cases, but it cannot overwrite the run-time search path (rpath) hard-coded into an ELF executable. We will look at one way to change the rpath later in this post.

Method 2: Using the Dynamic Linker/Loader

The dynamic linker/loader is run implicitly when you run a dynamically linked executable. It looks like a shared object file, but can be run explicitly to configure dynamic linking options. Perhaps its most useful command line option is --library-path which allows you to indicate a colon-separated list of locations to resolve the dynamic libraries. Here is an example of running ls with an alternative libc that I downloaded and compiled from source:

/home/andres/Repos/glibc-2.33/install/lib/ld-linux-x86-64.so.2        \
    --library-path /home/andres/Repos/glibc-2.33/install/lib:/usr/lib \
    $(which ls)

NOTE: Take a look at the dynamic linker/loader command line options by running it with --help. For example, /lib64/ld-linux-x86-64.so.2 --help in my system.

NOTE: The dynamic linker/loader is a little bit temperamental, so only pass absolute paths to it. Avoid using relative paths like ...

Method 3: Set the rpath at Link-Time

The idea is to set the ELF’s rpath at link-time by passing compiler flags. This is obviously inconvenient if you already have an executable and do not want (or cannot) link it once again, but is still an effective mechanism.

--rpath and --dynamic-linker are the linker options to configure the rpath and the dynamic linker/loader. Here is a usage example:

cc -o test -lm                                                                          \
    -Wl,--rpath=/home/andres/Repos/glibc-2.33/install/lib                               \
    -Wl,--dynamic-linker=/home/andres/Repos/glibc-2.33/install/lib/ld-linux-x86-64.so.2 \
    test.c

The readelf and ldd outputs confirm that the rpath for my test executable is set to the desired location, so the dynamic linker/loader will use the alternative shared objects for libc and libm.

$ readelf -d test

Dynamic section at offset 0x2dd8 contains 28 entries:
  Tag        Type                         Name/Value
 0x0000000000000001 (NEEDED)             Shared library: [libm.so.6]
 0x0000000000000001 (NEEDED)             Shared library: [libc.so.6]
 0x000000000000000f (RPATH)              Library rpath: [/home/andres/Repos/glibc-2.33/install/lib]
...

$ ldd test
        linux-vdso.so.1 (0x00007ffcfea8f000)
        libm.so.6 => /home/andres/Repos/glibc-2.33/install/lib/libm.so.6 (0x00007f7564e67000)
        libc.so.6 => /home/andres/Repos/glibc-2.33/install/lib/libc.so.6 (0x00007f7564ca4000)
        /home/andres/Repos/glibc-2.33/install/lib/ld-linux-x86-64.so.2 => /usr/lib64/ld-linux-x86-64.so.2 (0x00007f7564faf000)

NOTE: According to this post, it is also possible to change the rpath of an existing ELF with patchelf, but I have never tried this. The advange over Method 3 is that patchelf does not require you to link the program again.

C++11: Invalid Suffix on Literal Warning/Error

2021-03-06T10:21:09+00:00

I recently came across this unexpected error when compiling C++ code using Clang:

error: invalid suffix on literal; C++11 requires a space between literal and identifier

I got a similar message, although as a warning, when compiling the same code with GCC:

warning: invalid suffix on literal; C++11 requires a space between literal and string macro

The problem occurs when compiling code like this:

printf("Test %"PRIu32"\n", x);

Note that there is no space between the string Test % and PRIu32 which is apparently a requirement in C++11 (or newer). Fortunately, the fix is quite simple – just add spaces between the string and identifier. So the equivalent code below fixes the problem:

printf("Test %" PRIu32 "\n", x);

But what if you have a lot of legacy code that you cannot modify? There are a couple of flags that can disable the warnings/errors, but these are different for Clang and GCC.

NOTE: An obvious way to get rid of the problem in both Clang and GCC is to indicate a C++ standard version earlier than C++11. For example, invoking the compiler with the flag -std=c++03 fixes the problem, but of course, this is not an ideal solution.

Clang

In Clang, the invalid suffix literal message shows as an error by default. You can turn it into a warning message with the -Wno-error=reserved-user-defined-literal flag. Alternatively, you can completely eliminate the warning/error message with -Wno-reserved-user-defined-literal. For example,

clang++ -std=c++11 -Wno-error=reserved-user-defined-literal -c -o test.o test.cpp

NOTE: This page from the Clang documentation explains how the warning and error flags work.

GCC

In GCC, the invalid suffix literal message shows as a warning by default. You can eliminate the message with the Wno-literal-suffix flag. For example,

g++ -std=c++11 -Wno-literal-suffix -c -o test.o test.cpp

NOTE: This page from the GCC documentation explains how the warning and error flags work.

Managing Audio in i3 with PulseAudio

2020-12-03T10:21:09+00:00

I recently switched to i3 after using GNOME for a few years. Unlike many window managers, i3 is very bare-bones and its default installation does not include functionality to manage audio through a graphical interface like you would in GNOME. I fixed the problem by modifying my i3 configuration instead of installing a graphical application such as gnome-control-center. Here is how I did it using PulseAudio.

Lets look at the easy part first: mute audio and increase/decrease volume. With a bit of Googling, you can actually find a lot of suggestions for how to do this. I chose to do it through i3 by mapping the F10, F11 and F12 keys to PulseAudio commands that mute, decrease volume and increase volume respectively. I added the following lines to my i3 config file:

bindsym $mod+F10 exec pactl set-sink-mute @DEFAULT_SINK@ toggle # Mute
bindsym $mod+F11 exec pactl set-sink-volume @DEFAULT_SINK@ -5%  # Up
bindsym $mod+F12 exec pactl set-sink-volume @DEFAULT_SINK@ +5%  # Down

The volume is increased/decrease by 5% for each time that the commands are issued. A small matter with PulseAudio is that you can actuall set the volume above 100%!

A slightly harder problem I had was to changing the output device. For example, my computer has two output devices for audio: a speaker and the headphones. I wanted an easy and quick way to change the output audio device (or sink in PulseAudio terminology) with a keystroke (or two). So I mapped the F9 key to execute a bash script which does just that. Here is the relevant line in my i3 configuration:

bindsym $mod+F9  exec ~/.config/i3/toggle_sink.sh

The script relies on PulseAudio commands and is relatively simple. It does three things:

Query a list of possible output sinks.
Update the current DEFAULT_SINK to the next available output sink in the previously queried list.
Redirect all currently playing audio streams to the new DEFAULT_SINK.

The current DEFAULT_SINK is the sink that the mute and increase/decrease audio commands will affect. Also, simply changing the DEFAULT_SINK does not cause the currently playing audio to be automatically redirected to that sink.

Whenever the script is executed, all sound is redirected to the next sink in the list. So repeatedly pressing $Mod+F9 effectively lets me cycle through the audio output devices with a couple of keystrokes!

#! /usr/bin/env bash

set -eu

# Get the ID for the current DEFAULT_SINK
defaultSink=$(pactl info | grep "Default Sink: " | awk '{ print $3 }')

# Query the list of all available sinks
sinks=()
i=0
while read line; do
    index=$(echo $line | awk '{ print $1 }')
    sinks[${#sinks[@]}]=$index

    # Find the current DEFAULT_SINK
    if grep -q "$defaultSink" <<< "$line"; then
        defaultIndex=$index
        defaultPos=$i
    fi

    i=$(( $i + 1 ))
done <<< "$(pactl list sinks short)"

# Compute the ID of the new DEFAULT_SINK
newDefaultPos=$(( ($defaultPos + 1) % ${#sinks[@]} ))
newDefaultSink=${sinks[$newDefaultPos]}

# Update the DEFAULT_SINK
pacmd set-default-sink $newDefaultSink

# Move all current playing streams to the new DEFAULT_SINK
while read stream; do
    # Check whether there is a stream playing in the first place
    if [ -z "$stream" ]; then
        break
    fi

    streamId=$(echo $stream | awk '{ print $1 }')
    pactl move-sink-input $streamId @DEFAULT_SINK@
done <<< "$(pactl list short sink-inputs)"

Source Code Artisan

Understanding Git (Part III): Workflows

Feature Branch Workflow

Forking Workflow

Closing Thoughts on Workflows

Conclusion

Understanding Git (Part II): Working with Remotes

Remotes

Branches and Remotes

Pushing to Remotes

Fetching From Remotes

Visualizing Git History

Conclusion

Understanding Git (Part I): The VERY Basics!

Versions, Commits and Graphs

Anatomy of a Git Commit

Branching and Merging

Rebasing

Navigating Git History

Conclusion

What’s So Good About RISC V?

1. It’s Free!

2. Innovation

3. Community

Conclusion

References

Analyzing Real-Time Systems

Overview

Control Flow Graph

Integer Linear Programming

Conclusion

What are Real-Time Systems?

What are Real-Time Systems?

Real-Time Systems are NOT…

Types of Real-Time Systems

Conclusion

Integrated Hardware Garbage Collection for Real-Time Embedded Systems

Abstract

Download

Related Publications

Dynamic Linking to a Different libc

Finding Dynamic Library dependencies

Linking Against a Specific libc

Method 1: LD_LIBRARY_PATH

Method 2: Using the Dynamic Linker/Loader

Method 3: Set the rpath at Link-Time

C++11: Invalid Suffix on Literal Warning/Error

Clang

GCC

Managing Audio in i3 with PulseAudio

Method 1: `LD_LIBRARY_PATH`