---

THIS SOFTWARE IS PROVIDED "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FREEBSD
PROJECT OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT
OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY
OF SUCH DAMAGE.

---

This patch contains modifications to the FreeBSD 7.2 kernel that allow idle
cycle injection as described in "Dimetrodon: Processor-level Preventive Thermal
Management via Idle Cycle Injection" by Peter Bailis, Vijay Janapa Reddi, Sanjay
Gandhi, David Brooks, and Margo Seltzer, appearing at the 48th Design Automation
Conference (DAC 2011).

Feel free to ping me with any questions, but please read through this sparse
documentation first.  The code isn't pretty (or anywhere near good), however I
am a firm believer in releasing and sharing research code.  The code should
compile and run on the 7.2 kernel, and, in the interest of scientific inquiry,
is the exact kernel code I ran in order to obtain the results in our
publication.  Note that I am not actively maintaining this code.

dimetrodon.patch can be applied to the FreeBSD 7.2 source tree in the "bsd"
directory under trunk, and contains some simple compliation shell scripts as
well and a sample configuration file.  You probably won't use all of the
scripts, but they're maybe nice if you're doing a lot of recompiling.  As
described in the paper, these modifications only apply to the FreeBSD SCHED_4BSD
scheduler, and this must be changed in the kernel configuration file (already
done in the sample configuration file--KERNCONF=DIMETRODON):

-options	SCHED_ULE
+options	SCHED_4BSD

There are a number of system calls that can control the injection.  The current
implementation uses a system-wide idling probability and, by default, all
processes opt-in to idling.  This can easily be changed by modifying the process
struct, but works well enough in practice; this is completely an engineering
decision.

The patch is pretty long, but is mostly due to autogenerated system call
handlers (makesyscalls.sh).  To get a sense of what's going on, look at
do_schedule_now().  Note that there is support for setting a minimum quanta
length for process preemption.  This allows short-running processes to run
without getting preempted for a long time.  This is quite useful for interacting
with the machine while still running idle cycles (e.g., interacting with the
shell).  Of course, an alternative is to simply anoint the interactive process.

Descriptions of several of the most salient calls follow.  Note that some of the
calls in the patch may be deprecated/nops.

489: sets the system-wide probability of idling (0 == always idle, 100 == never idle)
according to the paper terminology, the argument here can be calculated as (1-100*p)

490: sets the system-wide length of idle quanta (argument is in ms)
this is equivalent to L in the paper

497: exempt a process from idling (argument is PID)
this is equivalent to p-priority zero

506: anoint a process (argument is PID)
this is equivalent to p-priority -1

Here's some sample source for a program to set the constant value.  Tweak the
define to change the system call </obvious>.

#include <sys/syscall.h>
#include <stdio.h>

#define SYS_SINGLE_ARG_CALL 489

int main(int argc, char **argv)
{
        if(argc != 2)
        {
                printf("Requires one argument only!\n");
                return 1;
        }

        int ret = syscall(SYS_SINGLE_ARG_CALL, atoi(argv[1]));

        printf("%d\n", ret);

        return 0;
}