From b570e037a5bb8abf780b75e896a8dee336c2dd74 Mon Sep 17 00:00:00 2001 From: Sitsofe Wheeler Date: Tue, 27 Mar 2018 17:28:27 +0100 Subject: [PATCH] doc: add Windows processor group behaviour and Windows target option - Add information on targeting the build against different versions of Windows to the README - Stop listing -i686 packages in the 64 bit section of the README and add a note to about them to the 32 bit build section - Rejig cpus_allowed to be before cpumask in the documentation to make people more likely to read that section first - Make it clear that CPUs specified in the cpus_allowed section are indexed from 0 (and not 1) - Add information about how processor group awareness when setting CPUs is only available when using a build targeted at Windows 7 (because only then do we have the processor group APIs available to us) and how selecting a CPU sets the processor group too (because we concatanate the CPUs from all the processor groups together) Signed-off-by: Sitsofe Wheeler --- HOWTO | 44 +++++++++++++++++++++++++++++--------------- README | 11 +++++++---- fio.1 | 44 ++++++++++++++++++++++++++++++-------------- 3 files changed, 66 insertions(+), 33 deletions(-) diff --git a/HOWTO b/HOWTO index dbbbfaa1..e4d3198e 100644 --- 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 diff --git a/README b/README index fba5f102..38022bbb 100644 --- a/README +++ b/README @@ -172,15 +172,18 @@ directory. How to compile fio on 64-bit Windows: 1. Install Cygwin (http://www.cygwin.com/). Install **make** and all - packages starting with **mingw64-i686** and **mingw64-x86_64**. Ensure - **mingw64-i686-zlib** and **mingw64-x86_64-zlib** are installed if you wish + packages starting with **mingw64-x86_64**. Ensure + **mingw64-x86_64-zlib** are installed if you wish to enable fio's log compression functionality. 2. Open the Cygwin Terminal. 3. Go to the fio directory (source files). 4. Run ``make clean && make -j``. -To build fio on 32-bit Windows, run ``./configure --build-32bit-win`` before -``make``. +To build fio for 32-bit Windows, ensure the -i686 versions of the previously +mentioned -x86_64 packages are installed and run ``./configure +--build-32bit-win`` before ``make``. To build an fio that supports versions of +Windows below Windows 7/Windows Server 2008 R2 also add ``--target-win-ver=xp`` +to the end of the configure line that you run before doing ``make``. It's recommended that once built or installed, fio be run in a Command Prompt or other 'native' console such as console2, since there are known to be display and diff --git a/fio.1 b/fio.1 index 5ca57ce4..81dbc5f7 100644 --- a/fio.1 +++ b/fio.1 @@ -2091,22 +2091,28 @@ systems since meaning of priority may differ. .BI prioclass \fR=\fPint Set the I/O priority class. See man \fBionice\fR\|(1). .TP -.BI cpumask \fR=\fPint -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 -\fBsched_setaffinity\fR\|(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 -\fBcpus_allowed\fR. -.TP .BI cpus_allowed \fR=\fPstr Controls the same options as \fBcpumask\fR, 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'. +.RS +.P +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. +.RE .TP .BI cpus_allowed_policy \fR=\fPstr Set the policy of how fio distributes the CPUs specified by @@ -2127,6 +2133,16 @@ enough CPUs are given for the jobs listed, then fio will roundrobin the CPUs in the set. .RE .TP +.BI cpumask \fR=\fPint +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 +\fBsched_setaffinity\fR\|(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 +\fBcpus_allowed\fR. +.TP .BI numa_cpu_nodes \fR=\fPstr Set this job running on specified NUMA nodes' CPUs. The arguments allow comma delimited list of cpu numbers, A\-B ranges, or `all'. Note, to enable -- 2.25.1