= How to Create a Custom Scheduler Plugin in LITMUS-RT =

A brief guide to creating a new scheduling plugin in LITMUS^RT^. This tutorial should work with the most recent stable LITMUS^RT^ release (2014.2 at the time of writing); complain to the [[Mailinglist|mailinglist]] if it doesn't.

== Prerequisites ==

 * A testing environment (e.g., KVM/Qemu or Bochs). This tutorial assumes KVM.
 * Strong C programming skills.
 * Ideally, some exposure to OS kernel development.

== General Guidelines ==

Work in a checked-out git repository. Do not use the tarball from the web page. This will make keeping track of your edits and incorporating upstream changes much easier.

Test incrementally to catch errors early. Compile test after each edit. Test-boot as often as possible. The earlier you catch an error, the easier it is to debug.

Commit early, commit often. Make many small commits a you go along. You can clean them up later using `git rebase`.

Do not commit to the master branch. This will make incorporating upstream changes much easier.

Follow the kernel coding standard defined in [[http://lxr.linux.no/linux/Documentation/CodingStyle|Documentation/CodingStyle]], even when writing “throw away” code.


== Steps ==

The tutorial is structured in a series of steps, which are intended to be completed sequentially. When working through these, you should reproduce the instructions on your own local machine. If something seems unclear, please feel free to ask on the [[Mailinglist|mailinglist]] for clarification.

In the first eight steps, the tutorial re-creates a ''partitioned EDF'' (P-EDF) scheduler. In contrast to the PSN-EDF plugin shipping with LITMUS^RT^, the demo implementation does not support locking and non-preemptive sections to keep it simple.

 * [[/Step0|Step 0: checkout and compile the kernel]]
 * [[/Step1|Step 1: add a source file to the build system]]
 * [[/Step2|Step 2: register a dummy plugin]]
 * [[/Step3|Step 3: log debug message with TRACE()]]
 * [[/Step4|Step 4: define P-EDF per-processor state]]
 * [[/Step5|Step 5: add P-EDF scheduling function]]
 * [[/Step6|Step 6: add support for task state changes]]
 * [[/Step7|Step 7: implement preemptive P-EDF]]
 * [[/Step8|Step 8: admit real-time tasks]]
 * [[/Step9|Step 9: export plugin topology information in /proc]]

''To be continued... please contribute.''

== Reference Implementation ==

A branch containing commits corresponding to each of the above steps is available at [[https://github.com/LITMUS-RT/litmus-rt/commits/wiki-tutorial]].