Idle Page Tracking
==================

This is a toolbox for idle page tracking.  It can be used to know real working
set size of a process, rather than vsz or rss.


Limitations
===========

The tools use idle page tracking feature of the Linux kernel internally.  It
means that the tools work on Linux systems that idle page tracking feature is
turned on.  You can check whether your system has turned on or off the feature
by simply running the command below:
```
$ if [ -d /sys/kernel/mm/page_idle ]; \
	then echo "ON"; else echo "OFF"; fi
```

It also shares limitation of idle page tracking feature of the Linux kernel.
It tracks only userspace pages on LRU list of the kernel.


Tools
=====

This section gives brief description and usage of core tools in the box.


userprog
--------

`userprog` is a sample synthetic workload for test of other tools.  It creates
a memory pool of given size and interactively accesses specified pages in the
allocated pages.  It receives number of pages to be used for the memory pool by
command line argument.  After the program starts, it will repeatedly ask how
many pages in the memory pool you want to do access.


pfnofmap.py
-----------

`pfnofmap.py` receives pid and virtual address mapping path name as argument
and giving page frame number for the mapped virtual address range.  Internally,
it uses /proc/pid/maps and /proc/pid/pagemap.  Because of security, you should
have root access.  For example, you may use the tool in below way:
```
$ sudo ./pfnofmap.py `pidof userprog` [stack]
98758566
96560353
```


gen_pfns_bin.sh
---------------

`pfnofmap.py` is useful, but parsing every pfns from string could be relatively
slow.  gen_pfns_bin.sh does similar thing but it generates a file and write the
extracted pfns in binary format to the file.  Usage is similar with
`pfnofmap.py` but it receives a path to the file that you want to generate as
second argument.  Simple use of the tool will be like below:
```
$ sudo ./gen_pfns_bin.sh `pidof userprog` pfns.bin [heap]
```


pageidle
--------

`pageidle` is a program to set / get idleness of physical pages.  It receives
two arguments.  First argument should be a string of command, `set` or `get`.
Second argument is a path to a file that containing page frame number(s) of
physical page(s) that you want to set or get their idleness.  The file for page
frame number(s) should be in binary format that `gen_pfns_bin.sh` uses.

For example:
```
$ sudo ./gen_pfns_bin.sh `pidof userprog` pfns.bin [heap]
$ sudo ./pageidle set pfns.bin
$ sudo ./pageidle get pfns.bin
1 1 1 1 1 1 1 1 1 1 1
```

After you access few pages using `userprog`, the output of `get` becomes
different.
```
/* From userprog */
How many pages you want to access? 3
will access 3 pages
How many pages you want to access?

/* From other terminal */
$ sudo ./pageidle get pfns.bin
0 0 0 1 1 1 1 1 1 1 1
```


wspages.sh
----------

Now you can calculate working set size of a process using the tools described
above.  To simplify the life even more, `wspages.sh` helps the complicated
works.  It requires pid, time interval, and target memory mapped regions as
arguments.  The third argument can be ignored, though.  In the case, it uses
heap, stack, and anonymous pages as target memory region by default.  If you
give the arguments as well, this tool will prints out number of pages accessed
between the time interval.  Simple example of usage and output is as below:
```
$ sudo ./wspages.sh `pidof userprog` 1 [heap]
3
```

The output says that `userprog` process has accessed 3 pages in heap during
one second after you started `wspages.sh`.


wspgstat.sh
-----------

Like `*stat` programs (such as vmstat, iostat, ...), wspgstat.sh monitors and
print out number of pages in working set of specific process repeatedly.  It
requires pid of target program, delay between idleness check, and target memory
mapped regions as arguments.  The third argument is optional and has default
value as same as wspages.sh's same argument.  Simple example usage is as below:
```
$ ./wspgstat.sh `pidof mysqld` 5
1 17448
9 21536
18 21659
```


License
=======

GPL v3


Author
======

SeongJae Park <sj38.park@gmail.com>