1 <html devsite> 2 <head> 3 <title>Kernel Networking Unit Tests</title> 4 <meta name="project_path" value="/_project.yaml" /> 5 <meta name="book_path" value="/_book.yaml" /> 6 </head> 7 <body> 8 <!-- 9 Copyright 2017 The Android Open Source Project 10 11 Licensed under the Apache License, Version 2.0 (the "License"); 12 you may not use this file except in compliance with the License. 13 You may obtain a copy of the License at 14 15 http://www.apache.org/licenses/LICENSE-2.0 16 17 Unless required by applicable law or agreed to in writing, software 18 distributed under the License is distributed on an "AS IS" BASIS, 19 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 20 See the License for the specific language governing permissions and 21 limitations under the License. 22 --> 23 24 25 <p>Since Android 5.0, proper operation of the Android networking stack on Linux 26 kernels requires a number of commits that were upstreamed relatively recently 27 or have not yet made it upstream. It is not easy to manually verify the 28 required kernel functionality or track the missing commits, so the Android team 29 is sharing the tests it uses to ensure the kernel behaves as expected.</p> 30 31 <h2 id=purpose>Why run the tests?</h2> <p>These tests exist for three main 32 reasons:</p> <ol> <li>The exact version of the Linux kernel used on a device is 33 typically device-specific, and it is difficult to know whether any kernel will 34 work properly without running the tests.</li> <li>Forward-porting and 35 back-porting the kernel patches to different kernel versions or different 36 device trees may introduce subtle issues that can be impossible to spot without 37 running the tests. For example, during development the initial versions of 38 certain devices had UID routing patches forward-ported from android-3.4 instead 39 of cherry-picked from android-3.10, and did not behave correctly.</li> <li>New 40 networking features may require new kernel functionality or kernel bug 41 fixes.</li> </ol> <p>If the tests do not pass, the device's network stack will 42 behave incorrectly, causing user-visible connectivity bugs such as falling off 43 Wi-Fi networks. The device will likely also fail Android Compatibility Test 44 Suite (CTS) tests.</p> 45 46 <h2 id=using>Using the tests</h2> <p>The tests use <a 47 href="http://user-mode-linux.sourceforge.net/">User-Mode Linux</a> to boot the 48 kernel as a process on a Linux host machine. See <a 49 href="https://source.android.com/source/initializing.html">Establishing a Build 50 Environment</a> for suitable operating system versions. The unit test framework 51 boots the kernel with an appropriate disk image and runs the tests from the 52 host file system. The tests are written in Python 2.x and use TAP interfaces to 53 exercise kernel behaviour and the socket API.</p> 54 55 <h3 id=compiling>Compiling the kernel for ARCH=um</h3> <p>For the tests to run, 56 the kernel must compile for <code>ARCH=um SUBARCH=x86_64</code>. This is a 57 supported architecture upstream and in the common Android kernel trees (e.g., 58 <code>android-3.10</code>, <code>android-3.18</code>). But sometimes device 59 kernels do not compile in this mode because device trees contain 60 device-specific or hardware-specific code in common files (e.g., 61 <code>sys/exit.c</code>).</p> <p>In many cases, it's sufficient to ensure that 62 hardware-specific code is behind an <code>#ifdef</code>. Typically this should 63 be an <code>#ifdef</code> on a configuration option that controls the specific 64 feature relevant to the code. If there is no such configuration option, put 65 hardware-specific code inside <code>#ifndef CONFIG_UML</code> blocks.</p> <p>In 66 general, fixing this should be the responsibility of the kernel tree provider 67 (e.g., chipset or SoC vendor). We're working with OEMs and vendors to ensure 68 that current and future kernels will compile for <code>ARCH=um 69 SUBARCH=x86_64</code> without requiring any changes.</p> 70 71 <h3 id=running>Running the tests</h3> <p>The tests are at <a 72 href="https://android.googlesource.com/kernel/tests/+/master/net/test"><code>kernel/tests/net/test</code></a>. 73 It is recommended that the tests <b>be run from AOSP master</b> because they 74 are the most up-to-date; in some cases, kernel features that are necessary for 75 proper operation in a given Android release do not yet have full test coverage 76 in the given release. For information on how to run the tests, see the <a 77 href="https://android.googlesource.com/kernel/tests/+/master/net/test/README">kernel 78 network test README file</a>. Basically, from the top of your kernel tree, run:</p> 79 80 <pre class="devsite-click-to-copy"> 81 <var>ANDROID_TREE</var>/kernel/tests/net/test/run_net_test.sh all_tests.sh 82 </pre> 83 84 <h3 id=passing>Passing the tests</h3> <p>The kernel network test Python 85 source files contain comments that specify kernel commits that are known to be 86 required to pass the tests. The tests should pass in the common kernel trees - 87 at least the <code>android-3.10</code> and <code>android-3.18</code> branches 88 in the <a 89 href="https://android-review.googlesource.com/#/q/project:kernel/common"><code>kernel/common</code></a> 90 project in AOSP. Therefore, passing the tests on a kernel tree that's derived 91 from 3.10 or 3.18 should mostly be a matter of cherry-picking the patches from 92 these trees.</p> 93 94 <h2 id=contributing>Contributing</h2> 95 96 <h3 id=reporting>Reporting issues</h3> <p>Please report any issues with 97 the kernel network tests in the <a 98 href="https://code.google.com/p/android/issues/entry?template=Developer%20bug%20report">Android 99 issue tracker</a> with the <a 100 href="https://code.google.com/p/android/issues/list?q=label%3AComponent-Networking">Component-Networking</a> 101 label.</p> 102 103 <h3 id=documenting>Documenting commits and adding tests</h3> <p>Please report 104 issues as described above, and if possible upload a change to fix the issue, 105 if:</p> <ul> <li>The tests do not pass on the common kernel trees</li> <li>You 106 find a necessary commit that is not mentioned in the source comments,</li> 107 <li>Getting the tests to pass on upstream kernels requires major changes</li> 108 <li>You believe that the tests are overspecified, or the test fail on future 109 kernels</li> <li>You'd like to add more tests or more coverage to existing 110 tests.</li> 111 </ul> 112 113 </body> 114 </html> 115
