Crosvm on ChromeOS

A copy of crosvm is included in the ChromeOS source tree at chromiumos/platform/crosvm, which is referred to as downstream crosvm.

All crosvm development is happening upstream at crosvm/crosvm. Changes from upstream crosvm are regularly merged with ChromeOS's downstream crosvm.

The merge process.

A crosvm bot will regularly generate automated commits that merge upstream crosvm into downstream. These commits can be found in gerrit.

The crosvm team is submitting these merges through the ChromeOS CQ regularly, which happens roughly once per week, but time can vary depending on CQ health.

Googlers can find more information on the merge process at go/crosvm-uprev-playbook.

Building crosvm for ChromeOS

crosvm on ChromeOS is usually built with Portage, so it follows the same general workflow as any cros_workon package. The full package name is chromeos-base/crosvm.

The developer guide section on Make your Changes applies to crosvm as well. You can specify the development version to be built with cros_workon, and build with cros build-packages. Consecutive builds without changes to dependency can be done with emerge.

(chroot)$ cros_workon --board=${BOARD} start chromeos-base/crosvm
(chroot or host)$ cros build-packages --board=${BOARD} chromeos-base/crosvm
(chroot)$ emerge-${BOARD} chromeos-base/crosvm -j 10

Deploy it via cros deploy:

(chroot)$ cros deploy ${IP} crosvm

Iterative test runs can be done as well:

(chroot)$ FEATURES=test emerge-${BOARD} chromeos-base/crosvm -j 10

Warning: Using cros_workon_make is possible but patches the local Cargo.toml file and some configuration files. Please do not submit these changes. Also something makes it rebuild a lot of the files.

Rebuilding all crosvm dependencies

Crosvm has a lot of rust dependencies that are installed into a registry inside cros_sdk. After a repo sync these can be out of date, causing compilation issues. To make sure all dependencies are up to date, run:

(chroot or host)$ cros build-packages --board=${BOARD} chromeos-base/crosvm

Building crosvm for Linux

emerge and cros_workon_make workflows can be quite slow to work with, hence a lot of developers prefer to use standard cargo workflows used upstream.

Just make sure to initialize git submodules (git submodules update --init), which is not done by repo. After that, you can use the workflows as outlined in Building Crosvm outside of cros_sdk.

Note: You can not build or test ChromeOS specific features this way.

Submitting Changes

All changes to crosvm are made upstream, using the same process outlined in Contributing. It is recommended to use the Building crosvm for Linux setup above to run upstream presubmit checks / formatting tools / etc when submitting changes.

Code submitted upstream is tested on linux, but not on ChromeOS devices. Changes will only be tested on the ChromeOS CQ when they go through the merge process.

Has my change landed in ChromeOS (Googlers only)?

You can use the crosland tool to check in which ChromeOS version your changes have been merged into the chromiumos/platform/crosvm repository.

The merge will also contain all BUG= references that will notify your bugs about when the change is submitted.

For more details on the process, please see go/crosvm-uprev-playbook (Googlers only).

Cq-Depend

We cannot support Cq-Depend to sychronize changes with other ChromeOS repositories. Please try to make changes in a backwards compatible way to allow them to be submitted independently.

If it cannot be avoided at all, please follow this process:

Upload your change to upstream crosvm and get it reviewed. Do not submit it yet.
Upload the change to chromiumos/platform/crosvm as well.
Use Cq-Depend on the ChromeOS changes and submit it via the CQ.
After the changes landed in ChromeOS, land them upstream as well.

Cherry-picking

Cherry-picking without the usual merge process

If you need your changes faster than the usual merge frequency, please follow this process:

Upload and submit your change to upstream crosvm.
Upload the change to chromiumos/platform/crosvm as well.
Submit as usual through the CQ.

Never submit code just to ChromeOS, as it will cause upstream to diverge and result in merge conflicts down the road.

Cherry-picking to release branch

Your change need to be merged into chromiumos/platform/crosvm to cherry-pick it to a release branch. You should follow ChromiumOS Merge Workflow to cherry-pick your changes. Since changes are merged from crosvm/crosvm to chromiumos/platform/crosvm through the merge process, you can't use gerrit to cherry-pick your changes but need to use git command locally.

$ cd chromiumos/src/platform/crosvm
$ git branch -a | grep remotes/cros/release-R120
  remotes/cros/release-R120-15662.B
$ git checkout -b my-cherry-pick cros/release-R120-15662.B
$ git cherry-pick -x $COMMIT
$ git push cros HEAD:refs/for/release-R120-15662.B

$COMMIT is the commit hash of the original change you want to cherry-pick not the merge commit. Note that you push to special gerrit refs/for/, not pushing directly to the release branch.

Also note that release branch cherry picks don't get CQ tested at all - they are submitted directly once you CQ+2 - so it is very important to test locally first.

Running a Tryjob

For googlers, see go/cdg-site

Book of crosvm