What is KUnit?¶

“K” is short for “kernel” so “KUnit” is the “(Linux) Kernel Unit TestingFramework.” KUnit is intended first and foremost for writing unit tests; it isgeneral enough that it can be used to write integration tests; however, this isa secondary goal. KUnit has no ambition of being the only testing framework forthe kernel; for example, it does not intend to be an end-to-end testingframework.

What is Unit Testing?¶

Aunit test is a test thattests code at the smallest possible scope, aunit of code. In the Cprogramming language that’s a function.

Unit tests should be written for all the publicly exposed functions in acompilation unit; so that is all the functions that are exported in either aclass (defined below) or all functions which arenot static.

Writing Tests¶

voidexample_test_success(structkunit*test){}voidexample_test_failure(structkunit*test){KUNIT_FAIL(test,"This test never passes.");}

voidadd_test_basic(structkunit*test){KUNIT_EXPECT_EQ(test,1,add(1,0));KUNIT_EXPECT_EQ(test,2,add(1,1));}

voidadd_test_basic(structkunit*test){KUNIT_EXPECT_EQ(test,1,add(1,0));KUNIT_EXPECT_EQ(test,2,add(1,1));}voidadd_test_negative(structkunit*test){KUNIT_EXPECT_EQ(test,0,add(-1,1));}voidadd_test_max(structkunit*test){KUNIT_EXPECT_EQ(test,INT_MAX,add(0,INT_MAX));KUNIT_EXPECT_EQ(test,-1,add(INT_MAX,INT_MIN));}voidadd_test_overflow(structkunit*test){KUNIT_EXPECT_EQ(test,INT_MIN,add(INT_MAX,1));}

staticvoidmock_test_do_expect_default_return(structkunit*test){structmock_test_context*ctx=test->priv;structmock*mock=ctx->mock;intparam0=5,param1=-5;constchar*two_param_types[]={"int","int"};constvoid*two_params[]={&param0,&param1};constvoid*ret;ret=mock->do_expect(mock,"test_printk",test_printk,two_param_types,two_params,ARRAY_SIZE(two_params));KUNIT_ASSERT_NOT_ERR_OR_NULL(test,ret);KUNIT_EXPECT_EQ(test,-4,*((int*)ret));}

staticstructkunit_caseexample_test_cases[]={KUNIT_CASE(example_test_foo),KUNIT_CASE(example_test_bar),KUNIT_CASE(example_test_baz),{}};staticstructkunit_suiteexample_test_suite={.name="example",.init=example_test_init,.exit=example_test_exit,.test_cases=example_test_cases,};kunit_test_suite(example_test_suite);

Classes¶

Classes are not a construct that is built into the C programming language;however, it is an easily derived concept. Accordingly, pretty much every projectthat does not use a standardized object oriented library (like GNOME’s GObject)has their own slightly different way of doing object oriented programming; theLinux kernel is no exception.

The central concept in kernel object oriented programming is the class. In thekernel, aclass is a struct that contains function pointers. This creates acontract betweenimplementers andusers since it forces them to use thesame function signature without having to call the function directly. In orderfor it to truly be a class, the function pointers must specify that a pointerto the class, known as aclass handle, be one of the parameters; this makesit possible for the member functions (also known asmethods) to have accessto member variables (more commonly known asfields) allowing the sameimplementation to have multipleinstances.

Typically a class can beoverridden bychild classes by embedding theparent class in the child class. Then when a method provided by the childclass is called, the child implementation knows that the pointer passed to it isof a parent contained within the child; because of this, the child can computethe pointer to itself because the pointer to the parent is always a fixed offsetfrom the pointer to the child; this offset is the offset of the parent containedin the child struct. For example:

structshape{int(*area)(structshape*this);};structrectangle{structshapeparent;intlength;intwidth;};intrectangle_area(structshape*this){structrectangle*self=container_of(this,structshape,parent);returnself->length*self->width;};voidrectangle_new(structrectangle*self,intlength,intwidth){self->parent.area=rectangle_area;self->length=length;self->width=width;}

In this example (as in most kernel code) the operation of computing the pointerto the child from the pointer to the parent is done bycontainer_of.

structeeprom{ssize_t(*read)(structeeprom*this,size_toffset,char*buffer,size_tcount);ssize_t(*write)(structeeprom*this,size_toffset,constchar*buffer,size_tcount);};

structeeprom_buffer{ssize_t(*write)(structeeprom_buffer*this,constchar*buffer,size_tcount);intflush(structeeprom_buffer*this);size_tflush_count;/* Flushes when buffer exceeds flush_count. */};structeeprom_buffer*new_eeprom_buffer(structeeprom*eeprom);voiddestroy_eeprom_buffer(structeeprom*eeprom);

structfake_eeprom{structeepromparent;charcontents[FAKE_EEPROM_CONTENTS_SIZE];};ssize_tfake_eeprom_read(structeeprom*parent,size_toffset,char*buffer,size_tcount){structfake_eeprom*this=container_of(parent,structfake_eeprom,parent);count=min(count,FAKE_EEPROM_CONTENTS_SIZE-offset);memcpy(buffer,this->contents+offset,count);returncount;}ssize_tfake_eeprom_write(structeeprom*parent,size_toffset,constchar*buffer,size_tcount){structfake_eeprom*this=container_of(parent,structfake_eeprom,parent);count=min(count,FAKE_EEPROM_CONTENTS_SIZE-offset);memcpy(this->contents+offset,buffer,count);returncount;}voidfake_eeprom_init(structfake_eeprom*this){this->parent.read=fake_eeprom_read;this->parent.write=fake_eeprom_write;memset(this->contents,0,FAKE_EEPROM_CONTENTS_SIZE);}

structeeprom_buffer_test{structfake_eeprom*fake_eeprom;structeeprom_buffer*eeprom_buffer;};staticvoideeprom_buffer_test_does_not_write_until_flush(structkunit*test){structeeprom_buffer_test*ctx=test->priv;structeeprom_buffer*eeprom_buffer=ctx->eeprom_buffer;structfake_eeprom*fake_eeprom=ctx->fake_eeprom;charbuffer[]={0xff};eeprom_buffer->flush_count=SIZE_MAX;eeprom_buffer->write(eeprom_buffer,buffer,1);KUNIT_EXPECT_EQ(test,fake_eeprom->contents[0],0);eeprom_buffer->write(eeprom_buffer,buffer,1);KUNIT_EXPECT_EQ(test,fake_eeprom->contents[1],0);eeprom_buffer->flush(eeprom_buffer);KUNIT_EXPECT_EQ(test,fake_eeprom->contents[0],0xff);KUNIT_EXPECT_EQ(test,fake_eeprom->contents[1],0xff);}staticvoideeprom_buffer_test_flushes_after_flush_count_met(structkunit*test){structeeprom_buffer_test*ctx=test->priv;structeeprom_buffer*eeprom_buffer=ctx->eeprom_buffer;structfake_eeprom*fake_eeprom=ctx->fake_eeprom;charbuffer[]={0xff};eeprom_buffer->flush_count=2;eeprom_buffer->write(eeprom_buffer,buffer,1);KUNIT_EXPECT_EQ(test,fake_eeprom->contents[0],0);eeprom_buffer->write(eeprom_buffer,buffer,1);KUNIT_EXPECT_EQ(test,fake_eeprom->contents[0],0xff);KUNIT_EXPECT_EQ(test,fake_eeprom->contents[1],0xff);}staticvoideeprom_buffer_test_flushes_increments_of_flush_count(structkunit*test){structeeprom_buffer_test*ctx=test->priv;structeeprom_buffer*eeprom_buffer=ctx->eeprom_buffer;structfake_eeprom*fake_eeprom=ctx->fake_eeprom;charbuffer[]={0xff,0xff};eeprom_buffer->flush_count=2;eeprom_buffer->write(eeprom_buffer,buffer,1);KUNIT_EXPECT_EQ(test,fake_eeprom->contents[0],0);eeprom_buffer->write(eeprom_buffer,buffer,2);KUNIT_EXPECT_EQ(test,fake_eeprom->contents[0],0xff);KUNIT_EXPECT_EQ(test,fake_eeprom->contents[1],0xff);/* Should have only flushed the first two bytes. */KUNIT_EXPECT_EQ(test,fake_eeprom->contents[2],0);}staticinteeprom_buffer_test_init(structkunit*test){structeeprom_buffer_test*ctx;ctx=kunit_kzalloc(test,sizeof(*ctx),GFP_KERNEL);KUNIT_ASSERT_NOT_ERR_OR_NULL(test,ctx);ctx->fake_eeprom=kunit_kzalloc(test,sizeof(*ctx->fake_eeprom),GFP_KERNEL);KUNIT_ASSERT_NOT_ERR_OR_NULL(test,ctx->fake_eeprom);fake_eeprom_init(ctx->fake_eeprom);ctx->eeprom_buffer=new_eeprom_buffer(&ctx->fake_eeprom->parent);KUNIT_ASSERT_NOT_ERR_OR_NULL(test,ctx->eeprom_buffer);test->priv=ctx;return0;}staticvoideeprom_buffer_test_exit(structkunit*test){structeeprom_buffer_test*ctx=test->priv;destroy_eeprom_buffer(ctx->eeprom_buffer);}

Running existing KUnit tests on non-UML architectures¶

There are some special considerations when running existing KUnit tests onnon-UML architectures:

• Hardware may not be deterministic, so a test that always passes or failswhen run under UML may not always do so on real hardware.
• Hardware and VM environments may not be hermetic. KUnit tries its best toprovide a hermetic environment to run tests; however, it cannot manage statethat it doesn’t know about outside of the kernel. Consequently, tests thatmay be hermetic on UML may not be hermetic on other architectures.
• Some features and tooling may not be supported outside of UML.
• Hardware and VMs are slower than UML.

None of these are reasons not to run your KUnit tests on real hardware; they areonly things to be aware of when doing so.

The biggest impediment will likely be that certain KUnit features andinfrastructure may not support your target environment. For example, at thistime the KUnit Wrapper (tools/testing/kunit/kunit.py) does not work outsideof UML. Unfortunately, there is no way around this. Using UML (or even just aparticular architecture) allows us to make a lot of assumptions that make itpossible to do things which might otherwise be impossible.

Nevertheless, all core KUnit framework features are fully supported on allarchitectures, and using them is straightforward: all you need to do is to takeyour kunitconfig, your Kconfig options for the tests you would like to run, andmerge them into whatever config your are using for your platform. That’s it!

For example, let’s say you have the following kunitconfig:

CONFIG_KUNIT=yCONFIG_KUNIT_EXAMPLE_TEST=y

If you wanted to run this test on an x86 VM, you might add the following configoptions to your.config:

CONFIG_KUNIT=yCONFIG_KUNIT_EXAMPLE_TEST=yCONFIG_SERIAL_8250=yCONFIG_SERIAL_8250_CONSOLE=y

All these new options do is enable support for a common serial console neededfor logging.

Next, you could build a kernel with these tests as follows:

makeARCH=x86 olddefconfigmakeARCH=x86

Once you have built a kernel, you could run it on QEMU as follows:

qemu-system-x86_64 -enable-kvm\                   -m1024\                   -kernel arch/x86_64/boot/bzImage\                   -append'console=ttyS0'\                   --nographic

Interspersed in the kernel logs you might see the following:

TAP version 14        # Subtest: example        1..1        # example_simple_test: initializing        ok 1 - example_simple_testok 1 - example

Congratulations, you just ran a KUnit test on the x86 architecture!

In a similar manner, kunit and kunit tests can also be built as modules,so if you wanted to run tests in this way you might add the following configoptions to your.config:

CONFIG_KUNIT=mCONFIG_KUNIT_EXAMPLE_TEST=m

Once the kernel is built and installed, a simple

modprobe example-test

…will run the tests.

Writing new tests for other architectures¶

The first thing you must do is ask yourself whether it is necessary to write aKUnit test for a specific architecture, and then whether it is necessary towrite that test for a particular piece of hardware. In general, writing a testthat depends on having access to a particular piece of hardware or software (notincluded in the Linux source repo) should be avoided at all costs.

Even if you only ever plan on running your KUnit test on your hardwareconfiguration, other people may want to run your tests and may not have accessto your hardware. If you write your test to run on UML, then anyone can run yourtests without knowing anything about your particular setup, and you can stillrun your tests on your hardware setup just by compiling for your architecture.

Nevertheless, there are still valid reasons to write an architecture or hardwarespecific test: for example, you might want to test some code that really belongsinarch/some-arch/*. Even so, try your best to write the test so that itdoes not depend on physical hardware: if some of your test cases don’t need thehardware, only require the hardware for tests that actually need it.

Now that you have narrowed down exactly what bits are hardware specific, theactual procedure for writing and running the tests is pretty much the same aswriting normal KUnit tests. One special caveat is that you have to resethardware state in between test cases; if this is not possible, you may only beable to run one test case per invocation.