gpiolib: cdev: improve documentation of get/set values

Add documentation of the algorithm used to perform scatter/gather
of the requested lines and values in linereq_get_values() and
linereq_set_values_unlocked() to improve maintainability.

Signed-off-by: Kent Gibson <warthog618@gmail.com>
Reviewed-by: Andy Shevchenko <andy@kernel.org>
Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

diff --git a/drivers/gpio/gpiolib-cdev.c b/drivers/gpio/gpiolib-cdev.c
index 84471b703402f07933edf5982b5249efa910bd15..e3fdf7b86d1053512f97fa9864c2d87d30176679 100644 (file)
--- a/drivers/gpio/gpiolib-cdev.c
+++ b/drivers/gpio/gpiolib-cdev.c
@@ -1394,9 +1394,18 @@ static long linereq_get_values(struct linereq *lr, void __user *ip)
        if (copy_from_user(&lv, ip, sizeof(lv)))
                return -EFAULT;
 
+       /*
+        * gpiod_get_array_value_complex() requires compacted desc and val
+        * arrays, rather than the sparse ones in lv.
+        * Calculation of num_get and construction of the desc array is
+        * optimized to avoid allocation for the desc array for the common
+        * num_get == 1 case.
+        */
+       /* scan requested lines to calculate the subset to get */
        for (num_get = 0, i = 0; i < lr->num_lines; i++) {
                if (lv.mask & BIT_ULL(i)) {
                        num_get++;
+                       /* capture desc for the num_get == 1 case */
                        descs = &lr->lines[i].desc;
                }
        }
@@ -1405,6 +1414,7 @@ static long linereq_get_values(struct linereq *lr, void __user *ip)
                return -EINVAL;
 
        if (num_get != 1) {
+               /* build compacted desc array */
                descs = kmalloc_array(num_get, sizeof(*descs), GFP_KERNEL);
                if (!descs)
                        return -ENOMEM;
@@ -1425,6 +1435,7 @@ static long linereq_get_values(struct linereq *lr, void __user *ip)
 
        lv.bits = 0;
        for (didx = 0, i = 0; i < lr->num_lines; i++) {
+               /* unpack compacted vals for the response */
                if (lv.mask & BIT_ULL(i)) {
                        if (lr->lines[i].sw_debounced)
                                val = debounced_value(&lr->lines[i]);
@@ -1450,14 +1461,25 @@ static long linereq_set_values_unlocked(struct linereq *lr,
        unsigned int i, didx, num_set;
        int ret;
 
+       /*
+        * gpiod_set_array_value_complex() requires compacted desc and val
+        * arrays, rather than the sparse ones in lv.
+        * Calculation of num_set and construction of the descs and vals arrays
+        * is optimized to minimize scanning the lv->mask, and to avoid
+        * allocation for the desc array for the common num_set == 1 case.
+        */
        bitmap_zero(vals, GPIO_V2_LINES_MAX);
+       /* scan requested lines to determine the subset to be set */
        for (num_set = 0, i = 0; i < lr->num_lines; i++) {
                if (lv->mask & BIT_ULL(i)) {
+                       /* setting inputs is not allowed */
                        if (!test_bit(FLAG_IS_OUT, &lr->lines[i].desc->flags))
                                return -EPERM;
+                       /* add to compacted values */
                        if (lv->bits & BIT_ULL(i))
                                __set_bit(num_set, vals);
                        num_set++;
+                       /* capture desc for the num_set == 1 case */
                        descs = &lr->lines[i].desc;
                }
        }
@@ -1465,7 +1487,7 @@ static long linereq_set_values_unlocked(struct linereq *lr,
                return -EINVAL;
 
        if (num_set != 1) {
-               /* build compacted desc array and values */
+               /* build compacted desc array */
                descs = kmalloc_array(num_set, sizeof(*descs), GFP_KERNEL);
                if (!descs)
                        return -ENOMEM;