mirror of
https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git
synced 2024-08-27 19:29:37 +00:00
![Mark Rutland](/assets/img/avatar_default.png)
Currently the atomics are documented in Documentation/atomic_t.txt, and have no kerneldoc comments. There are a sufficient number of gotchas (e.g. semantics, noinstr-safety) that it would be nice to have comments to call these out, and it would be nice to have kerneldoc comments such that these can be collated. While it's possible to derive the semantics from the code, this can be painful given the amount of indirection we currently have (e.g. fallback paths), and it's easy to be mislead by naming, e.g. * The unconditional void-returning ops *only* have relaxed variants without a _relaxed suffix, and can easily be mistaken for being fully ordered. It would be nice to give these a _relaxed() suffix, but this would result in significant churn throughout the kernel. * Our naming of conditional and unconditional+test ops is rather inconsistent, and it can be difficult to derive the name of an operation, or to identify where an op is conditional or unconditional+test. Some ops are clearly conditional: - dec_if_positive - add_unless - dec_unless_positive - inc_unless_negative Some ops are clearly unconditional+test: - sub_and_test - dec_and_test - inc_and_test However, what exactly those test is not obvious. A _test_zero suffix might be clearer. Others could be read ambiguously: - inc_not_zero // conditional - add_negative // unconditional+test It would probably be worth renaming these, e.g. to inc_unless_zero and add_test_negative. As a step towards making this more consistent and easier to understand, this patch adds kerneldoc comments for all generated *atomic*_*() functions. These are generated from templates, with some common text shared, making it easy to extend these in future if necessary. I've tried to make these as consistent and clear as possible, and I've deliberately ensured: * All ops have their ordering explicitly mentioned in the short and long description. * All test ops have "test" in their short description. * All ops are described as an expression using their usual C operator. For example: andnot: "Atomically updates @v to (@v & ~@i)" inc: "Atomically updates @v to (@v + 1)" Which may be clearer to non-naative English speakers, and allows all the operations to be described in the same style. * All conditional ops have their condition described as an expression using the usual C operators. For example: add_unless: "If (@v != @u), atomically updates @v to (@v + @i)" cmpxchg: "If (@v == @old), atomically updates @v to @new" Which may be clearer to non-naative English speakers, and allows all the operations to be described in the same style. * All bitwise ops (and,andnot,or,xor) explicitly mention that they are bitwise in their short description, so that they are not mistaken for performing their logical equivalents. * The noinstr safety of each op is explicitly described, with a description of whether or not to use the raw_ form of the op. There should be no functional change as a result of this patch. Reported-by: Paul E. McKenney <paulmck@kernel.org> Signed-off-by: Mark Rutland <mark.rutland@arm.com> Signed-off-by: Peter Zijlstra (Intel) <peterz@infradead.org> Reviewed-by: Kees Cook <keescook@chromium.org> Link: https://lore.kernel.org/r/20230605070124.3741859-26-mark.rutland@arm.com
290 lines
5.6 KiB
Bash
Executable file
290 lines
5.6 KiB
Bash
Executable file
#!/bin/sh
|
|
# SPDX-License-Identifier: GPL-2.0
|
|
# helpers for dealing with atomics.tbl
|
|
|
|
#meta_in(meta, match)
|
|
meta_in()
|
|
{
|
|
case "$1" in
|
|
[$2]) return 0;;
|
|
esac
|
|
|
|
return 1
|
|
}
|
|
|
|
#meta_has_ret(meta)
|
|
meta_has_ret()
|
|
{
|
|
meta_in "$1" "bBiIfFlR"
|
|
}
|
|
|
|
#meta_has_acquire(meta)
|
|
meta_has_acquire()
|
|
{
|
|
meta_in "$1" "BFIlR"
|
|
}
|
|
|
|
#meta_has_release(meta)
|
|
meta_has_release()
|
|
{
|
|
meta_in "$1" "BFIRs"
|
|
}
|
|
|
|
#meta_has_relaxed(meta)
|
|
meta_has_relaxed()
|
|
{
|
|
meta_in "$1" "BFIR"
|
|
}
|
|
|
|
#meta_is_implicitly_relaxed(meta)
|
|
meta_is_implicitly_relaxed()
|
|
{
|
|
meta_in "$1" "vls"
|
|
}
|
|
|
|
#find_template(tmpltype, pfx, name, sfx, order)
|
|
find_template()
|
|
{
|
|
local tmpltype="$1"; shift
|
|
local pfx="$1"; shift
|
|
local name="$1"; shift
|
|
local sfx="$1"; shift
|
|
local order="$1"; shift
|
|
|
|
local base=""
|
|
local file=""
|
|
|
|
# We may have fallbacks for a specific case (e.g. read_acquire()), or
|
|
# an entire class, e.g. *inc*().
|
|
#
|
|
# Start at the most specific, and fall back to the most general. Once
|
|
# we find a specific fallback, don't bother looking for more.
|
|
for base in "${pfx}${name}${sfx}${order}" "${pfx}${name}${sfx}" "${name}"; do
|
|
file="${ATOMICDIR}/${tmpltype}/${base}"
|
|
|
|
if [ -f "${file}" ]; then
|
|
printf "${file}"
|
|
break
|
|
fi
|
|
done
|
|
}
|
|
|
|
#find_fallback_template(pfx, name, sfx, order)
|
|
find_fallback_template()
|
|
{
|
|
find_template "fallbacks" "$@"
|
|
}
|
|
|
|
#find_kerneldoc_template(pfx, name, sfx, order)
|
|
find_kerneldoc_template()
|
|
{
|
|
find_template "kerneldoc" "$@"
|
|
}
|
|
|
|
#gen_ret_type(meta, int)
|
|
gen_ret_type() {
|
|
local meta="$1"; shift
|
|
local int="$1"; shift
|
|
|
|
case "${meta}" in
|
|
[sv]) printf "void";;
|
|
[bB]) printf "bool";;
|
|
[aiIfFlR]) printf "${int}";;
|
|
esac
|
|
}
|
|
|
|
#gen_ret_stmt(meta)
|
|
gen_ret_stmt()
|
|
{
|
|
if meta_has_ret "${meta}"; then
|
|
printf "return ";
|
|
fi
|
|
}
|
|
|
|
# gen_param_name(arg)
|
|
gen_param_name()
|
|
{
|
|
# strip off the leading 'c' for 'cv'
|
|
local name="${1#c}"
|
|
printf "${name#*:}"
|
|
}
|
|
|
|
# gen_param_type(arg, int, atomic)
|
|
gen_param_type()
|
|
{
|
|
local type="${1%%:*}"; shift
|
|
local int="$1"; shift
|
|
local atomic="$1"; shift
|
|
|
|
case "${type}" in
|
|
i) type="${int} ";;
|
|
p) type="${int} *";;
|
|
v) type="${atomic}_t *";;
|
|
cv) type="const ${atomic}_t *";;
|
|
esac
|
|
|
|
printf "${type}"
|
|
}
|
|
|
|
#gen_param(arg, int, atomic)
|
|
gen_param()
|
|
{
|
|
local arg="$1"; shift
|
|
local int="$1"; shift
|
|
local atomic="$1"; shift
|
|
local name="$(gen_param_name "${arg}")"
|
|
local type="$(gen_param_type "${arg}" "${int}" "${atomic}")"
|
|
|
|
printf "${type}${name}"
|
|
}
|
|
|
|
#gen_params(int, atomic, arg...)
|
|
gen_params()
|
|
{
|
|
local int="$1"; shift
|
|
local atomic="$1"; shift
|
|
|
|
while [ "$#" -gt 0 ]; do
|
|
gen_param "$1" "${int}" "${atomic}"
|
|
[ "$#" -gt 1 ] && printf ", "
|
|
shift;
|
|
done
|
|
}
|
|
|
|
#gen_args(arg...)
|
|
gen_args()
|
|
{
|
|
while [ "$#" -gt 0 ]; do
|
|
printf "$(gen_param_name "$1")"
|
|
[ "$#" -gt 1 ] && printf ", "
|
|
shift;
|
|
done
|
|
}
|
|
|
|
#gen_desc_return(meta)
|
|
gen_desc_return()
|
|
{
|
|
local meta="$1"; shift
|
|
|
|
case "${meta}" in
|
|
[v])
|
|
printf "Return: Nothing."
|
|
;;
|
|
[Ff])
|
|
printf "Return: The original value of @v."
|
|
;;
|
|
[R])
|
|
printf "Return: The updated value of @v."
|
|
;;
|
|
[l])
|
|
printf "Return: The value of @v."
|
|
;;
|
|
esac
|
|
}
|
|
|
|
#gen_template_kerneldoc(template, class, meta, pfx, name, sfx, order, atomic, int, args...)
|
|
gen_template_kerneldoc()
|
|
{
|
|
local template="$1"; shift
|
|
local class="$1"; shift
|
|
local meta="$1"; shift
|
|
local pfx="$1"; shift
|
|
local name="$1"; shift
|
|
local sfx="$1"; shift
|
|
local order="$1"; shift
|
|
local atomic="$1"; shift
|
|
local int="$1"; shift
|
|
|
|
local atomicname="${atomic}_${pfx}${name}${sfx}${order}"
|
|
|
|
local ret="$(gen_ret_type "${meta}" "${int}")"
|
|
local retstmt="$(gen_ret_stmt "${meta}")"
|
|
local params="$(gen_params "${int}" "${atomic}" "$@")"
|
|
local args="$(gen_args "$@")"
|
|
local desc_order=""
|
|
local desc_instrumentation=""
|
|
local desc_return=""
|
|
|
|
if [ ! -z "${order}" ]; then
|
|
desc_order="${order##_}"
|
|
elif meta_is_implicitly_relaxed "${meta}"; then
|
|
desc_order="relaxed"
|
|
else
|
|
desc_order="full"
|
|
fi
|
|
|
|
if [ -z "${class}" ]; then
|
|
desc_noinstr="Unsafe to use in noinstr code; use raw_${atomicname}() there."
|
|
else
|
|
desc_noinstr="Safe to use in noinstr code; prefer ${atomicname}() elsewhere."
|
|
fi
|
|
|
|
desc_return="$(gen_desc_return "${meta}")"
|
|
|
|
. ${template}
|
|
}
|
|
|
|
#gen_kerneldoc(class, meta, pfx, name, sfx, order, atomic, int, args...)
|
|
gen_kerneldoc()
|
|
{
|
|
local class="$1"; shift
|
|
local meta="$1"; shift
|
|
local pfx="$1"; shift
|
|
local name="$1"; shift
|
|
local sfx="$1"; shift
|
|
local order="$1"; shift
|
|
|
|
local atomicname="${atomic}_${pfx}${name}${sfx}${order}"
|
|
|
|
local tmpl="$(find_kerneldoc_template "${pfx}" "${name}" "${sfx}" "${order}")"
|
|
if [ -z "${tmpl}" ]; then
|
|
printf "/*\n"
|
|
printf " * No kerneldoc available for ${class}${atomicname}\n"
|
|
printf " */\n"
|
|
else
|
|
gen_template_kerneldoc "${tmpl}" "${class}" "${meta}" "${pfx}" "${name}" "${sfx}" "${order}" "$@"
|
|
fi
|
|
}
|
|
|
|
#gen_proto_order_variants(meta, pfx, name, sfx, ...)
|
|
gen_proto_order_variants()
|
|
{
|
|
local meta="$1"; shift
|
|
local pfx="$1"; shift
|
|
local name="$1"; shift
|
|
local sfx="$1"; shift
|
|
|
|
gen_proto_order_variant "${meta}" "${pfx}" "${name}" "${sfx}" "" "$@"
|
|
|
|
if meta_has_acquire "${meta}"; then
|
|
gen_proto_order_variant "${meta}" "${pfx}" "${name}" "${sfx}" "_acquire" "$@"
|
|
fi
|
|
if meta_has_release "${meta}"; then
|
|
gen_proto_order_variant "${meta}" "${pfx}" "${name}" "${sfx}" "_release" "$@"
|
|
fi
|
|
if meta_has_relaxed "${meta}"; then
|
|
gen_proto_order_variant "${meta}" "${pfx}" "${name}" "${sfx}" "_relaxed" "$@"
|
|
fi
|
|
}
|
|
|
|
#gen_proto_variants(meta, name, ...)
|
|
gen_proto_variants()
|
|
{
|
|
local meta="$1"; shift
|
|
local name="$1"; shift
|
|
local pfx=""
|
|
local sfx=""
|
|
|
|
meta_in "${meta}" "fF" && pfx="fetch_"
|
|
meta_in "${meta}" "R" && sfx="_return"
|
|
|
|
gen_proto_order_variants "${meta}" "${pfx}" "${name}" "${sfx}" "$@"
|
|
}
|
|
|
|
#gen_proto(meta, ...)
|
|
gen_proto() {
|
|
local meta="$1"; shift
|
|
for m in $(echo "${meta}" | grep -o .); do
|
|
gen_proto_variants "${m}" "$@"
|
|
done
|
|
}
|