@@ -22,7 +22,18 @@
#include <media/v4l2-ctrls.h>
#include <media/v4l2-ioctl.h>
-/* Use the same argument order as copy_in_user */
+/**
+ * assign_in_user() - Copy from one __user var to another one
+ *
+ * @to: __user var where data will be stored
+ * @from: __user var were data will be retrieved.
+ *
+ * As this code very often needs to allocate userspace memory, it is easier
+ * to have a macro that will do both get_user() and put_user() at once.
+ *
+ * This function complements the macros defined at asm-generic/uaccess.h.
+ * It uses the same argument order as copy_in_user()
+ */
#define assign_in_user(to, from) \
({ \
typeof(*from) __assign_tmp; \
@@ -30,16 +41,57 @@
get_user(__assign_tmp, from) || put_user(__assign_tmp, to); \
})
+/**
+ * get_user_cast() - Stores at a kernelspace local var the contents from a
+ * pointer with userspace data that is not tagged with __user.
+ *
+ * @__x: var where data will be stored
+ * @ptr: var were data will be retrieved.
+ *
+ * Sometimes, we need to declare a pointer without __user, because it
+ * comes from a pointer struct field that will be retrieved from userspace
+ * by the 64-bit native ioctl handler. This function ensures that the
+ * @ptr will be casted to __user before calling get_user(), in order to
+ * avoid warnings with static code analyzers like smatch.
+ */
#define get_user_cast(__x, __ptr) \
({ \
get_user(__x, (typeof(*__ptr) __user *)(__ptr)); \
})
+/**
+ * put_user_force() - Stores at the contents of a kernelspace local var
+ * into an userspace pointer, removing any __user cast.
+ *
+ * @__x: var where data will be stored
+ * @ptr: var were data will be retrieved.
+ *
+ * As the compat32 code now handles with 32-bits and 64-bits __user
+ * structs, sometimes we need to remove the __user atributes from some data,
+ * by passing __force macro. This function ensures that the
+ * @ptr will be casted with __force before calling put_user(), in order to
+ * avoid warnings with static code analyzers like smatch.
+ */
#define put_user_force(__x, __ptr) \
({ \
put_user((typeof(*__x) __force *)(__x), __ptr); \
})
+/**
+ * assign_in_user_cast() - Copy from one __user var to another one
+ *
+ * @to: __user var where data will be stored
+ * @from: var were data will be retrieved that needs to be cast to __user.
+ *
+ * As this code very often needs to allocate userspace memory, it is easier
+ * to have a macro that will do both get_user_cast() and put_user() at once.
+ *
+ * This function should be used instead of assign_in_user() when the @from
+ * variable was not declared as __user. See get_user_cast() for more details.
+ *
+ * This function complements the macros defined at asm-generic/uaccess.h.
+ * It uses the same argument order as copy_in_user()
+ */
#define assign_in_user_cast(to, from) \
({ \
typeof(*from) __assign_tmp; \