Contributing to EAS for Android

Goals

The aim of the new ‘EAS for Android’ release process is to:

  • Have product-quality EAS available as early as possible in new Android kernels
  • Align closely with mainline Linux, and minimize the patchset delta
  • Minimize further EAS updates during lifetime of kernel version (to allow SoC vendors to easily apply catch-up updates)

Background

Recently, the definitive version of EAS has been developed entirely in the open against the current Android Common Kernel branch - for example, we have had an android-4.9-eas-dev branch which is periodically merged into the android-4.9 common branch.

Work has also been ongoing to split EAS into chunks of functionality that are suitable for mainline Linux, and this upstreaming is progressing well during 2018. We expect that there will continue to be small parts of a product EAS solution which cannot be integrated upstream, so there will be a small number of product patches remaining but these are far fewer than previously.

With the new mainline focus on EAS, we propose to make the following improvements to the way we develop EAS and collaborate with partners.

Upstream EAS Development

At any given time, we are pushing 2-5 patch sets upstream which each contain parts of the EAS solution. As of the time of writing, we are pushing 2 sets with more to come (having merged a few so far this year).

Misfit task migration

Simplified Energy Model

All patch sets which are not yet merged are made available to the wider world though our EAS-mainline-integration branch, which is published biweekly on linux-arm.org. Each patch set is maintained as a topic branch on the same repository. Every biweekly release is tested on a collection of 32-bit and 64-bit ARM platforms.

This is important for our ‘EAS for Android’ product as it forms the basis of what we intend to provide. It also contains all the parts of the EAS solution we intend to upstream.

Proposed Development Process

An Independent Android preview for each Kernel Version

We will publish (on AOSP experimental/eas-dev) one version of the current best expression of ‘EAS for Android’ for each Linux Kernel release. This will begin to be assembled at rc6 of the kernel, and will be based upon the upstream EAS development branch with the addition of the android-specific parts. With the new upstream EAS focus, the amount of Android-only changes will be reduced from what can be currently seen in android-4.9 or android-4.14.

The experimental/eas-dev branch will act as an upstream topic branch for the existing android-mainline-tracking branch which is maintained by Amit Pundir.

Amit will be taking the patches we add to the Linux Kernel release to produce the ‘EAS for Android’ patch set he uses in his android-mainline-tracking kernel until the next update is pushed to experimental/eas-dev.

In order to avoid complicated histories, each preview release is force-pushed which allows the commit log for product EAS to evolve cleanly and descriptively as development progresses.

Accepting Contributions and Reviews

As the current expression will be built from a number of topic branches and history is rewritten at each kernel release, we do not intend to directly merge patches pushed to gerrit for preview releases.

We do want to see patches - if you have changes you would like to see, please continue to push a patch with the code you want to change. All contributions to EAS for Android should be posted on the AOSP gerrit, against the experimental/eas-dev branch. If instead you have comments or questions about the EAS patch set, that can be discussed on the eas-dev mailing list.

Where a patch makes sense to incorporate as a patch on top of the existing code, it will be added to the topic branch and will appear in the next release. We expect that some patches will make more sense if integrated into other patches or will influence refactoring of other patches - where this happens, credit will be maintained in the commit logs.

Quality Requirements

Since the intended target hardware for this ‘EAS for Android’ version will not be available until 6+ months after final release, it is not possible to have ‘product quality’ Android testing in the same way we could previously perform.

Patches should however still be tested using the android-mainline-tracking branch. As the hardware which this branch supports is quite limited in terms of exercising EAS features, it may not be possible to draw significant conclusions from test results produced with the LISA tools/wltest scheduler test framework. However it is highly desirable to run those tests and check for regressions.

In addition, Arm publishes a set of tests in LISA which can help ensure that the basic EAS functionalities are present and working across a range of devices which are not running Android.

Changes should be tested such that they:

  1. Pass checkpatch.pl
  2. Do not fail 0-day build testing
  3. Do not cause regression in LTP testing
  4. Do not cause regression in lisa tests
  5. Have the appropriate level of testing for the patch

Proposed Release Process

One Independent Android Release per Kernel LTS

Android kernels are based upon an LTS release of the Linux Kernel. The android-mainline-tracking branch performs the job of forward-porting the set of Android patches over the course of the year in between LTS branch releases. Arm will refresh the ‘EAS for Android’ patch set on the LTS branch ahead of android branch construction.

Support Commitment

The EAS parts of each android-X.XX branch will be supported by Arm for 3 years. Each version of EAS for Android will have a nominated maintainer at Arm. Since these kernels act as upstream sources for many device kernels, all of which make changes to cpufreq and scheduler, we will try to minimise changes after initial release.

There will be a 6-month stabilization period immediately after release where more minor features might be added and bugs can be fixed, however after that bugs must be reported and their associated patches must be triaged. The timing of this switch and the identity of the Arm maintainer will be communicated in advance through the eas-dev mailing list.

The goal of this process is to minimize further changes in the android-X.XX common kernel however in some cases there may need to be updates.

Patches intended to be merged in the common kernel (as opposed to patches intended to provoke discussion and act similarly to an RFC) should be annotated with the ‘eas-dev’ hashtag in Gerrit, to make it as simple as possible for observers to see in-progress updates for testing. For example, this link should allow you to see all eas-dev tagged patches which are not yet merged (in any branch).

https://android-review.googlesource.com/q/hashtag:%2522eas-dev%2522+(status:open)

Quality Requirements

Just like for the preview kernel releases, the hardware which this branch is intended to enable might not be available until many months after branch release. Arm will endeavour to provide feature coverage for all upcoming architectural and topological requirements which we are aware of. Arm is unable to guarantee optimal energy or performance on any specific target. Patches should continue to be tested as described above.

Documentation

A description of the features and how they should be used will be provided through Arm Developer Energy Aware Scheduling shortly after LTS patch assembly.

Illustration of code flows

In this diagram, the provision of a patch set for the android-mainline-tracking branch is shown along with the construction of the LTS android kernel (assumed to be 4.19 as an example in this diagram due to expected release dates - if 4.19 is not the LTS release, the steps here will apply to whatever release that is).

Definitions:

‘Mainline’ - The mainline Linux Kernel release branch.

‘Arm Mainline Integration’ - A branch containing all the EAS code which is currently targeted at upstream Linux plus any other parts necessary to use it on our test platforms (energy models etc.). This branch is published bi-weekly by Arm, and is based upon the tip/sched-core branch, except at rc4 time where we publish one based upon the in-progress release of mainline Linux. This is treated like a topic branch, previous versions are tagged and the branch is force-pushed to the latest version.

‘experimental/eas-dev’ - The branch published on Google’s Common Kernel repo which forms the current ‘EAS for Android’ patch set. This is also treated like a topic branch. This branch can be used for testing using Linux userspaces.

‘experimental/android-mainline-tracking’ - A branch tracking mainline Linux Kernel releases with the complete set of ‘Android’ out of tree patches rebased on top. This is the kernel branch to use for testing with Android.