doc: add Windows processor group behaviour and Windows target option

[fio.git] / HOWTO

diff --git a/HOWTO b/HOWTO
index dbbbfaa1d839e2d0bd73d91ceb83956c69f8e2c2..e4d3198e49559e0e085cd04e8adc2fa8495a424e 100644 (file)
--- a/HOWTO
+++ b/HOWTO
@@ -2377,24 +2377,27 @@ Threads, processes and job synchronization
 
        Set the I/O priority class. See man :manpage:`ionice(1)`.
 
-.. option:: cpumask=int
-
-       Set the CPU affinity of this job. The parameter given is a bit mask of
-       allowed CPUs the job may run on. So if you want the allowed CPUs to be 1
-       and 5, you would pass the decimal value of (1 << 1 | 1 << 5), or 34. See man
-       :manpage:`sched_setaffinity(2)`. This may not work on all supported
-       operating systems or kernel versions. This option doesn't work well for a
-       higher CPU count than what you can store in an integer mask, so it can only
-       control cpus 1-32. For boxes with larger CPU counts, use
-       :option:`cpus_allowed`.
-
 .. option:: cpus_allowed=str
 
        Controls the same options as :option:`cpumask`, but accepts a textual
-       specification of the permitted CPUs instead. So to use CPUs 1 and 5 you
-       would specify ``cpus_allowed=1,5``. This option also allows a range of CPUs
-       to be specified -- say you wanted a binding to CPUs 1, 5, and 8 to 15, you
-       would set ``cpus_allowed=1,5,8-15``.
+       specification of the permitted CPUs instead and CPUs are indexed from 0. So
+       to use CPUs 0 and 5 you would specify ``cpus_allowed=0,5``. This option also
+       allows a range of CPUs to be specified -- say you wanted a binding to CPUs
+       0, 5, and 8 to 15, you would set ``cpus_allowed=0,5,8-15``.
+
+       On Windows, when ``cpus_allowed`` is unset only CPUs from fio's current
+       processor group will be used and affinity settings are inherited from the
+       system. An fio build configured to target Windows 7 makes options that set
+       CPUs processor group aware and values will set both the processor group
+       and a CPU from within that group. For example, on a system where processor
+       group 0 has 40 CPUs and processor group 1 has 32 CPUs, ``cpus_allowed``
+       values between 0 and 39 will bind CPUs from processor group 0 and
+       ``cpus_allowed`` values between 40 and 71 will bind CPUs from processor
+       group 1. When using ``cpus_allowed_policy=shared`` all CPUs specified by a
+       single ``cpus_allowed`` option must be from the same processor group. For
+       Windows fio builds not built for Windows 7, CPUs will only be selected from
+       (and be relative to) whatever processor group fio happens to be running in
+       and CPUs from other processor groups cannot be used.
 
 .. option:: cpus_allowed_policy=str
 
@@ -2411,6 +2414,17 @@ Threads, processes and job synchronization
        enough CPUs are given for the jobs listed, then fio will roundrobin the CPUs
        in the set.
 
+.. option:: cpumask=int
+
+       Set the CPU affinity of this job. The parameter given is a bit mask of
+       allowed CPUs the job may run on. So if you want the allowed CPUs to be 1
+       and 5, you would pass the decimal value of (1 << 1 | 1 << 5), or 34. See man
+       :manpage:`sched_setaffinity(2)`. This may not work on all supported
+       operating systems or kernel versions. This option doesn't work well for a
+       higher CPU count than what you can store in an integer mask, so it can only
+       control cpus 1-32. For boxes with larger CPU counts, use
+       :option:`cpus_allowed`.
+
 .. option:: numa_cpu_nodes=str
 
        Set this job running on specified NUMA nodes' CPUs. The arguments allow