docs: Update built-in function docstrings

The docs are now asciidoc with examples,
ready to be included into the manual.

tuned/profiles/functions/function_assertion.py

@@ -8,9 +8,17 @@ log = tuned.logs.get()
 
 class assertion(base.Function):
 	"""
-	Assertion: compares argument 2 with argument 3. If they don't match
-	it logs text from argument 1 and  throws InvalidProfileException. This
-	exception will abort profile loading.
+	Compares the second argument and the third argument.
+	If they _do not match_, the function logs the text from
+	the first argument as an error and aborts profile loading.
+
+	====
+	The following will log the error message `fatal error`
+	and abort profile loading:
+	----
+	${f:assertion:fatal error:3:5}
+	----
+	====
 	"""
 	def __init__(self):
 		# 3 arguments

tuned/profiles/functions/function_assertion_non_equal.py

@@ -8,9 +8,16 @@ log = tuned.logs.get()
 
 class assertion_non_equal(base.Function):
 	"""
-	Assertion non equal: compares argument 2 with argument 3. If they match
-	it logs text from argument 1 and  throws InvalidProfileException. This
-	exception will abort profile loading.
+	Compares the second argument and the third argument.
+	If they _match_, the function logs the text from
+	the first argument as an error and aborts profile loading.
+
+	====
+	The following will pass without errors:
+	----
+	${f:assertion_non_equal:fatal error:3:5}
+	----
+	====
 	"""
 	def __init__(self):
 		# 3 arguments

tuned/profiles/functions/function_calc_isolated_cores.py

@@ -10,9 +10,16 @@ cmd = commands()
 
 class calc_isolated_cores(base.Function):
 	"""
-	Calculates and returns isolated cores. The argument specifies how many
-	cores per socket reserve for housekeeping. If not specified, 1 core
-	per socket is reserved for housekeeping and the rest is isolated.
+	Calculates and returns a list of isolated cores. The argument
+	specifies how many cores per socket should be reserved for housekeeping.
+	If not specified, a single core is reserved per socket and the rest is isolated.
+
+	====
+	Reserve two cores per socket for housekeeping and return the list of remaining cores:
+	----
+	${f:calc_isolated_cores:2}
+	----
+	====
 	"""
 	def __init__(self):
 		# max 1 argument

tuned/profiles/functions/function_check_net_queue_count.py

@@ -5,8 +5,8 @@ log = tuned.logs.get()
 
 class check_net_queue_count(base.Function):
 	"""
-	Checks whether the user has specified a queue count for net devices. If
-        not, return the number of housekeeping CPUs.
+	Checks whether the first argument is a valid queue count for net devices.
+	If yes, returns it, otherwise returns the number of housekeeping CPUs.
 	"""
 	def __init__(self):
 		# 1 argument

tuned/profiles/functions/function_cpuinfo_check.py

@@ -6,13 +6,17 @@ log = tuned.logs.get()
 
 class cpuinfo_check(base.Function):
 	"""
-	Checks regexes against /proc/cpuinfo. Accepts arguments in the
-	following form: REGEX1, STR1, REGEX2, STR2, ...[, STR_FALLBACK]
-	If REGEX1 matches something in /proc/cpuinfo it expands to STR1,
-	if REGEX2 matches it expands to STR2. It stops on the first match,
-	i.e. if REGEX1 matches, no more regexes are processed. If none
-	regex matches it expands to STR_FALLBACK. If there is no fallback,
-	it expands to empty string.
+	Checks regexes against the content of `/proc/cpuinfo`.
+
+	Accepts arguments in the form `REGEX1, STR1, REGEX2, STR2, ...[, STR_FALLBACK]`.
+
+	If `REGEX1` has a match in `/proc/cpuinfo`, it returns `STR1`.
+
+	If `REGEX2` has a match, it returns `STR2`.
+
+	The function stops on the first match, i.e., if `REGEX1` has a match,
+	no more regexes are processed. If no regex has a match, `STR_FALLBACK`
+	is returned. If there is no fallback value, it returns an empty string.
 	"""
 	def __init__(self):
 		# unlimited number of arguments, min 2 arguments

tuned/profiles/functions/function_cpulist2devs.py

@@ -5,7 +5,14 @@ log = tuned.logs.get()
 
 class cpulist2devs(base.Function):
 	"""
-	Conversion function: converts CPU list to device strings
+	Converts a CPU list into a comma-separated list of device names.
+
+	====
+	The following will return `cpu1,cpu2,cpu3,cpu5`:
+	----
+	${f:cpulist2devs:1-3,5}
+	----
+	====
 	"""
 	def __init__(self):
 		# arbitrary number of arguments

tuned/profiles/functions/function_cpulist2hex.py

@@ -7,7 +7,14 @@ log = tuned.logs.get()
 
 class cpulist2hex(base.Function):
 	"""
-	Conversion function: converts CPU list to hexadecimal CPU mask
+	Converts a CPU list into a hexadecimal CPU mask.
+
+	====
+	The following will return `00000007`.
+	----
+	${f:cpulist2hex:0-3}
+	----
+	====
 	"""
 	def __init__(self):
 		# arbitrary number of arguments

tuned/profiles/functions/function_cpulist2hex_invert.py

@@ -7,7 +7,15 @@ log = tuned.logs.get()
 
 class cpulist2hex_invert(base.Function):
 	"""
-	Converts CPU list to hexadecimal CPU mask and inverts it
+	Converts a CPU list into a hexadecimal CPU mask and inverts it.
+
+	====
+	On a system with 4 CPUs numbered from 0 to 3, the following will
+	return `00000002`, because only CPU1 is in the complement.
+	----
+	${f:cpulist2hex_invert:0,2,3}
+	----
+	====
 	"""
 	def __init__(self):
 		# arbitrary number of arguments

tuned/profiles/functions/function_cpulist_invert.py

@@ -7,10 +7,15 @@ log = tuned.logs.get()
 
 class cpulist_invert(base.Function):
 	"""
-	Inverts list of CPUs (makes its complement). For the complement it
-	gets number of online CPUs from the /sys/devices/system/cpu/online,
-	e.g. system with 4 CPUs (0-3), the inversion of list "0,2,3" will be
-	"1"
+	Inverts a CPU list, i.e., returns its complement. The complement is
+	computed from the list of online CPUs in `/sys/devices/system/cpu/online`.
+
+	====
+	On a system with 4 CPUs numbered from 0 to 3, the following will return `1`.
+	----
+	${f:cpulist_invert:0,2,3}
+	----
+	====
 	"""
 	def __init__(self):
 		# arbitrary number of arguments

tuned/profiles/functions/function_cpulist_online.py

@@ -7,8 +7,15 @@ log = tuned.logs.get()
 
 class cpulist_online(base.Function):
 	"""
-	Checks whether CPUs from list are online, returns list containing
-	only online CPUs
+	Returns a CPU list containing the online CPUs from the given CPU list.
+
+	====
+	On a system with 8 CPUs where the first 4 CPUs (0 to 3) are offline,
+	the following returns `4-6`:
+	----
+	${f:cpulist_online:0-6}
+	----
+	====
 	"""
 	def __init__(self):
 		# arbitrary number of arguments

tuned/profiles/functions/function_cpulist_pack.py

@@ -7,9 +7,14 @@ log = tuned.logs.get()
 
 class cpulist_pack(base.Function):
 	"""
-	Conversion function: packs CPU list in form 1,2,3,5 to 1-3,5.
-	The cpulist_unpack is used as a preprocessor, so it always returns
-	optimal results. For details about input syntax see cpulist_unpack.
+	Packs a CPU list into the most succint form.
+
+	====
+	The following returns `1-3,5`:
+	----
+	${f:cpulist_pack:1,2,3,5}
+	----
+	====
 	"""
 	def __init__(self):
 		# arbitrary number of arguments

tuned/profiles/functions/function_cpulist_present.py

@@ -7,8 +7,8 @@ log = tuned.logs.get()
 
 class cpulist_present(base.Function):
 	"""
-	Checks whether CPUs from list are present, returns list containing
-	only present CPUs
+	Checks whether the CPUs from a given CPU list are present on the system.
+	Returns a CPU list containing only the present CPUs from the given list.
 	"""
 	def __init__(self):
 		# arbitrary number of arguments

tuned/profiles/functions/function_cpulist_unpack.py

@@ -7,7 +7,14 @@ log = tuned.logs.get()
 
 class cpulist_unpack(base.Function):
 	"""
-	Conversion function: unpacks CPU list in form 1-3,4 to 1,2,3,4
+	Unpacks a CPU list into a form with no ranges.
+
+	====
+	The following returns `1,2,3,5`:
+	----
+	${f:cpulist_unpack:1-3,5}
+	----
+	====
 	"""
 	def __init__(self):
 		# arbitrary number of arguments

tuned/profiles/functions/function_exec.py

@@ -5,7 +5,14 @@ from tuned.utils.commands import commands
 
 class execute(base.Function):
 	"""
-	Executes process and substitutes its output.
+	Executes a process and returns its output.
+
+	====
+	The following executes `cat /etc/tuned/active_profile`:
+	----
+	${f:exec:cat:/etc/tuned/active_profile}
+	----
+	====
 	"""
 	def __init__(self):
 		# unlimited number of arguments, min 1 argument (the name of executable)

tuned/profiles/functions/function_hex2cpulist.py

@@ -7,7 +7,14 @@ log = tuned.logs.get()
 
 class hex2cpulist(base.Function):
 	"""
-	Conversion function: converts hexadecimal CPU mask to CPU list
+	Converts a hexadecimal CPU mask into a CPU list.
+
+	====
+	The following will return `0,1,2,3`:
+	----
+	${f:hex2cpulist:00000007}
+	----
+	====
 	"""
 	def __init__(self):
 		# 1 argument

tuned/profiles/functions/function_intel_recommended_pstate.py

@@ -12,18 +12,15 @@ DISABLE = "disable"
 
 class intel_recommended_pstate(base.Function):
     """
-    Checks the processor code name and return the recommended
-    intel_pstate CPUFreq driver mode. Active is returned for the
-    newer generation of processors not in the PROCESSOR_NAME list.
+    Returns the recommended intel_pstate CPUFreq driver mode
+    based on the CPU generation.
 
-    Intel recommends to use the intel_pstate CPUFreq driver
-    in active mode with HWP enabled on Ice Lake and later 
-    generations processors. This function allows dynamically 
-    setting intel_pstate based on the processor's model.
-    For pre-IceLake processors setting pstate to active
-    can introduce jitters which were historically seen around
-    and tested with RHEL-7.4. From IceLake generation, intel 
-    has fixed these issues. 
+    NOTE: Intel recommends to use the P-State driver
+    in active mode with HWP enabled starting from the Ice Lake
+    CPU generations. In older CPU generations, setting
+    P-State to `active` can introduce jitters which were historically
+    seen around and tested with RHEL-7.4. Beginning with the Ice Lake
+    generation, Intel has fixed these issues.
     """
     def __init__(self):
         super(intel_recommended_pstate, self).__init__("intel_recommended_pstate", 0)
@@ -35,4 +32,4 @@ class intel_recommended_pstate(base.Function):
         current_processor_name = self._cmd.read_file(PMU_PATH).strip()
         if current_processor_name == "" or current_processor_name in PROCESSOR_NAME:
             return DISABLE
-        return ACTIVE
+        return ACTIVE

tuned/profiles/functions/function_kb2s.py

@@ -5,7 +5,7 @@ from tuned.utils.commands import commands
 
 class kb2s(base.Function):
 	"""
-	Conversion function: kbytes to sectors
+	Converts kilobytes to disk sectors.
 	"""
 	def __init__(self):
 		# 1 argument

tuned/profiles/functions/function_log.py

@@ -5,7 +5,18 @@ log = tuned.logs.get()
 
 class execute(base.Function):
 	"""
-	Expands to concatenation of arguments and logs the result, useful for debugging.
+	Returns the concatenation of its arguments and also logs the return value,
+	which is useful for debugging.
+
+	.Using `log` to debug intermediate values
+	====
+	Since the arguments of `log` "fall through" the function, it
+	can be used as below for debugging intermediate values:
+	----
+	[variables]
+	isolated_cores_hex = ${f:cpulist2hex:${f:log:${f:calc_isolated_cores}}}
+	----
+	====
 	"""
 	def __init__(self):
 		# unlimited number of arguments, min 1 argument (the value to log)

tuned/profiles/functions/function_lscpu_check.py

@@ -6,13 +6,17 @@ log = tuned.logs.get()
 
 class lscpu_check(base.Function):
 	"""
-	Checks regexes against the output of lscpu. Accepts arguments in the
-	following form: REGEX1, STR1, REGEX2, STR2, ...[, STR_FALLBACK]
-	If REGEX1 matches something in the output it expands to STR1,
-	if REGEX2 matches it expands to STR2. It stops on the first match,
-	i.e. if REGEX1 matches, no more regexes are processed. If none
-	regex matches it expands to STR_FALLBACK. If there is no fallback,
-	it expands to empty string.
+	Checks regexes against the output of `lscpu`.
+
+	Accepts arguments in the form `REGEX1, STR1, REGEX2, STR2, ...[, STR_FALLBACK]`.
+
+	If `REGEX1` has a match in the output of `lscpu`, it returns `STR1`.
+	
+	If `REGEX2` has a match, it returns `STR2`.
+
+	The function stops on the first match, i.e., if `REGEX1` has a match,
+	no more regexes are processed. If no regex has a match, `STR_FALLBACK`
+	is returned. If there is no fallback value, returns an empty string.
 	"""
 	def __init__(self):
 		# unlimited number of arguments, min 2 arguments

tuned/profiles/functions/function_package2cpus.py

@@ -12,7 +12,16 @@ SYSFS_DIR = "/sys/devices/system/cpu/"
 
 class package2cpus(base.Function):
 	"""
-	Provides cpu device list for a package (socket)
+	Returns a comma-separated list of CPU devices for a package (socket).
+	Multiple socket numbers can be specified in separate arguments.
+
+	====
+	On a system with two CPU sockets, both with 4 cores, the
+	following will return `cpu0,cpu1,cpu2,cpu3,cpu4,cpu5,cpu6,cpu7`:
+	----
+	${f:package2cpus:0:1}
+	----
+	====
 	"""
 
 	def __init__(self):

tuned/profiles/functions/function_package2uncores.py

@@ -12,7 +12,16 @@ SYSFS_DIR = "/sys/devices/system/cpu/intel_uncore_frequency/"
 
 class package2uncores(base.Function):
 	"""
-	Provides uncore device list for a package (socket)
+	Returns a comma-separated list of uncore devices for a package (socket).
+	Multiple socket numbers can be specified in separate arguments.
+
+	====
+	On a system with a single socket and a single die,
+	the following will return `package_00_die_00`:
+	----
+	${f:package2uncores:0}
+	----
+	====
 	"""
 
 	def __init__(self):

tuned/profiles/functions/function_regex_search_ternary.py

@@ -3,10 +3,12 @@ from . import base
 
 class regex_search_ternary(base.Function):
 	"""
-	Ternary regex operator, it takes arguments in the following form
-	STR1, REGEX, STR2, STR3
-	If REGEX matches STR1 (re.search is used), STR2 is returned,
-	otherwise STR3 is returned
+	Ternary regex operator.
+
+	It takes arguments in the following form:
+	`STR1, REGEX, STR2, STR3`
+
+	If `REGEX` is matched within `STR1`, returns `STR2`, otherwise returns `STR3`.
 	"""
 	def __init__(self):
 		# 4 arguments

tuned/profiles/functions/function_s2kb.py

@@ -5,7 +5,7 @@ from tuned.utils.commands import commands
 
 class s2kb(base.Function):
 	"""
-	Conversion function: sectors to kbytes
+	Converts disk sectors to kilobytes.
 	"""
 	def __init__(self):
 		# 1 argument

tuned/profiles/functions/function_strip.py

@@ -5,7 +5,16 @@ from tuned.utils.commands import commands
 
 class strip(base.Function):
 	"""
-	Makes string from all arguments and strip it
+	Creates a string by concatenating all arguments,
+	stripping any leading or trailing whitespace from
+	the result.
+
+	====
+	The following returns `foo bar`:
+	----
+	${f:strip:  foo :bar  }
+	----
+	====
 	"""
 	def __init__(self):
 		# unlimited number of arguments, min 1 argument

tuned/profiles/functions/function_virt_check.py

@@ -5,9 +5,17 @@ from tuned.utils.commands import commands
 
 class virt_check(base.Function):
 	"""
-	Checks whether running inside virtual machine (VM) or on bare metal.
-	If running inside VM expands to argument 1, otherwise expands to
-	argument 2 (even on error).
+	Checks whether *TuneD* is running inside a virtual machine (VM) or on bare metal.
+
+	Inside a VM, it returns the first argument.
+	Otherwise returns the second argument (even on error).
+
+	====
+	The following returns `VM` when running in a virtual machine:
+	----
+	${f:virt_check:VM:Bare}
+	----
+	====
 	"""
 	def __init__(self):
 		# 2 arguments