git: 5fcfe4717ad0 - releng/13.1 - LinuxKPI: Add comment describing proper use of the on_each_cpu() function.

The branch releng/13.1 has been updated by hselasky:

URL: https://cgit.FreeBSD.org/src/commit/?id=5fcfe4717ad053f8984afb47fb6aacb822faf6cb

commit 5fcfe4717ad053f8984afb47fb6aacb822faf6cb
Author:     Hans Petter Selasky <hselasky@FreeBSD.org>
AuthorDate: 2022-03-16 14:40:09 +0000
Commit:     Hans Petter Selasky <hselasky@FreeBSD.org>
CommitDate: 2022-03-17 12:26:31 +0000

    LinuxKPI: Add comment describing proper use of the on_each_cpu() function.
    
    Sponsored by:   NVIDIA Networking
    Approved by:    re (gjb)
    
    (cherry picked from commit c6cf874c7de3bcc092a58a932c732221b2933043)
    (cherry picked from commit d17c5a4f62157c665ecc187e676d52c07e841923)
---
 sys/compat/linuxkpi/common/include/linux/smp.h | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/sys/compat/linuxkpi/common/include/linux/smp.h b/sys/compat/linuxkpi/common/include/linux/smp.h
index 290b91469b12..c6d011fceb5f 100644
--- a/sys/compat/linuxkpi/common/include/linux/smp.h
+++ b/sys/compat/linuxkpi/common/include/linux/smp.h
@@ -29,6 +29,18 @@
 #ifndef _LINUXKPI_LINUX_SMP_H_
 #define	_LINUXKPI_LINUX_SMP_H_
 
+/*
+ * Important note about the use of the function provided below:
+ *
+ * The callback function passed to on_each_cpu() is called from a
+ * so-called critical section, and if you need a mutex you will have
+ * to rewrite the code to use native FreeBSD mtx spinlocks instead of
+ * the spinlocks provided by the LinuxKPI! Be very careful to not call
+ * any LinuxKPI functions inside the on_each_cpu()'s callback
+ * function, because they may sleep, unlike in native Linux.
+ *
+ * Enabling witness(4) when testing, can catch such issues.
+ */
 #define	on_each_cpu(cb, data, wait) ({				\
 	CTASSERT(wait);						\
 	linux_on_each_cpu(cb, data);				\