[PATCH] Document how to setup/use huge pages
[fio.git] / HOWTO
diff --git a/HOWTO b/HOWTO
index 1176d2287f815439c680a38249a104682fcae64a..996da23a1ce998665d1f9af7d65faaf064eced64 100644 (file)
--- a/HOWTO
+++ b/HOWTO
@@ -264,6 +264,10 @@ ioengine=str       Defines how the job issues io to the file. The following
                                we use read(2) and write(2) for asynchronous
                                io.
 
+                       null    Doesn't transfer any data, just pretends
+                               to. This is mainly used to exercise fio
+                               itself and for debugging/testing purposes.
+
 iodepth=int    This defines how many io units to keep in flight against
                the file. The default is 1 for each file defined in this
                job, can be overridden with a larger value for higher
@@ -353,11 +357,32 @@ mem=str           Fio can use various types of memory as the io unit buffer.
                        shm     Use shared memory as the buffers. Allocated
                                through shmget(2).
 
+                       shmhuge Same as shm, but use huge pages as backing.
+
                        mmap    Use anonymous memory maps as the buffers.
                                Allocated through mmap(2).
 
+                       mmaphuge Use a memory mapped huge file as the buffer
+                               backing. Append filename after mmaphuge, ala
+                               mem=mmaphuge:/hugetlbfs/file
+
                The area allocated is a function of the maximum allowed
-               bs size for the job, multiplied by the io depth given.
+               bs size for the job, multiplied by the io depth given. Note
+               that for shmhuge and mmaphuge to work, the system must have
+               free huge pages allocated. This can normally be checked
+               and set by reading/writing /proc/sys/vm/nr_hugepages on a
+               Linux system. Fio assumes a huge page is 4MiB in size. So
+               to calculate the number of huge pages you need for a given
+               job file, add up the io depth of all jobs (normally one unless
+               iodepth= is used) and multiply by the maximum bs set. Then
+               divide that number by the huge page size. You can see the
+               size of the huge pages in /proc/meminfo. If no huge pages
+               are allocated by having a non-zero number in nr_hugepages,
+               using mmaphuge or shmhuge will fail.
+
+               mmaphuge also needs to have hugetlbfs mounted and the file
+               location should point there. So if it's mounted in /huge,
+               you would use mem=mmaphuge:/huge/somefile.
 
 exitall                When one job finishes, terminate the rest. The default is
                to wait for each job to finish, sometimes that is not the