change system file

hc

2024-10-09 244b2c5ca8b14627e4a17755e5922221e121c771

 kernel/Documentation/driver-api/gpio/consumer.rst
..
..
@@ -109,9 +109,11 @@
109
109
 					   enum gpiod_flags flags)
110
110
 
111
111
 This function returns a struct gpio_descs which contains an array of
112
-descriptors::
112
+descriptors.  It also contains a pointer to a gpiolib private structure which,
113
+if passed back to get/set array functions, may speed up I/O proocessing::
113
114
 
114
115
 	struct gpio_descs {
116
+		struct gpio_array *info;
115
117
 		unsigned int ndescs;
116
118
 		struct gpio_desc *desc[];
117
119
 	}
..
..
@@ -281,8 +283,6 @@
281
283
   gpiod_set_value(desc, 1);          default (active high)  high
282
284
   gpiod_set_value(desc, 0);          active low             high
283
285
   gpiod_set_value(desc, 1);          active low             low
284
-  gpiod_set_value(desc, 0);          default (active high)  low
285
-  gpiod_set_value(desc, 1);          default (active high)  high
286
286
   gpiod_set_value(desc, 0);          open drain             low
287
287
   gpiod_set_value(desc, 1);          open drain             high impedance
288
288
   gpiod_set_value(desc, 0);          open source            high impedance
..
..
@@ -323,29 +323,37 @@
323
323
 
324
324
 	int gpiod_get_array_value(unsigned int array_size,
325
325
 				  struct gpio_desc **desc_array,
326
-				  int *value_array);
326
+				  struct gpio_array *array_info,
327
+				  unsigned long *value_bitmap);
327
328
 	int gpiod_get_raw_array_value(unsigned int array_size,
328
329
 				      struct gpio_desc **desc_array,
329
-				      int *value_array);
330
+				      struct gpio_array *array_info,
331
+				      unsigned long *value_bitmap);
330
332
 	int gpiod_get_array_value_cansleep(unsigned int array_size,
331
333
 					   struct gpio_desc **desc_array,
332
-					   int *value_array);
334
+					   struct gpio_array *array_info,
335
+					   unsigned long *value_bitmap);
333
336
 	int gpiod_get_raw_array_value_cansleep(unsigned int array_size,
334
337
 					   struct gpio_desc **desc_array,
335
-					   int *value_array);
338
+					   struct gpio_array *array_info,
339
+					   unsigned long *value_bitmap);
336
340
 
337
-	void gpiod_set_array_value(unsigned int array_size,
338
-				   struct gpio_desc **desc_array,
339
-				   int *value_array)
340
-	void gpiod_set_raw_array_value(unsigned int array_size,
341
-				       struct gpio_desc **desc_array,
342
-				       int *value_array)
343
-	void gpiod_set_array_value_cansleep(unsigned int array_size,
344
-					    struct gpio_desc **desc_array,
345
-					    int *value_array)
346
-	void gpiod_set_raw_array_value_cansleep(unsigned int array_size,
347
-						struct gpio_desc **desc_array,
348
-						int *value_array)
341
+	int gpiod_set_array_value(unsigned int array_size,
342
+				  struct gpio_desc **desc_array,
343
+				  struct gpio_array *array_info,
344
+				  unsigned long *value_bitmap)
345
+	int gpiod_set_raw_array_value(unsigned int array_size,
346
+				      struct gpio_desc **desc_array,
347
+				      struct gpio_array *array_info,
348
+				      unsigned long *value_bitmap)
349
+	int gpiod_set_array_value_cansleep(unsigned int array_size,
350
+					   struct gpio_desc **desc_array,
351
+					   struct gpio_array *array_info,
352
+					   unsigned long *value_bitmap)
353
+	int gpiod_set_raw_array_value_cansleep(unsigned int array_size,
354
+					       struct gpio_desc **desc_array,
355
+					       struct gpio_array *array_info,
356
+					       unsigned long *value_bitmap)
349
357
 
350
358
 The array can be an arbitrary set of GPIOs. The functions will try to access
351
359
 GPIOs belonging to the same bank or chip simultaneously if supported by the
..
..
@@ -356,8 +364,9 @@
356
364
 The functions take three arguments:
357
365
 	* array_size	- the number of array elements
358
366
 	* desc_array	- an array of GPIO descriptors
359
-	* value_array	- an array to store the GPIOs' values (get) or
360
-			  an array of values to assign to the GPIOs (set)
367
+	* array_info	- optional information obtained from gpiod_get_array()
368
+	* value_bitmap	- a bitmap to store the GPIOs' values (get) or
369
+			  a bitmap of values to assign to the GPIOs (set)
361
370
 
362
371
 The descriptor array can be obtained using the gpiod_get_array() function
363
372
 or one of its variants. If the group of descriptors returned by that function
..
..
@@ -366,15 +375,24 @@
366
375
 
367
376
 	struct gpio_descs *my_gpio_descs = gpiod_get_array(...);
368
377
 	gpiod_set_array_value(my_gpio_descs->ndescs, my_gpio_descs->desc,
369
-			      my_gpio_values);
378
+			      my_gpio_descs->info, my_gpio_value_bitmap);
370
379
 
371
380
 It is also possible to access a completely arbitrary array of descriptors. The
372
381
 descriptors may be obtained using any combination of gpiod_get() and
373
382
 gpiod_get_array(). Afterwards the array of descriptors has to be setup
374
-manually before it can be passed to one of the above functions.
383
+manually before it can be passed to one of the above functions.  In that case,
384
+array_info should be set to NULL.
375
385
 
376
386
 Note that for optimal performance GPIOs belonging to the same chip should be
377
387
 contiguous within the array of descriptors.
388
+
389
+Still better performance may be achieved if array indexes of the descriptors
390
+match hardware pin numbers of a single chip.  If an array passed to a get/set
391
+array function matches the one obtained from gpiod_get_array() and array_info
392
+associated with the array is also passed, the function may take a fast bitmap
393
+processing path, passing the value_bitmap argument directly to the respective
394
+.get/set_multiple() callback of the chip.  That allows for utilization of GPIO
395
+banks as data I/O ports without much loss of performance.
378
396
 
379
397
 The return value of gpiod_get_array_value() and its variants is 0 on success
380
398
 or negative on error. Note the difference to gpiod_get_value(), which returns
..
..
@@ -417,7 +435,7 @@
417
435
 _DSD is not present, the mappings between GpioIo()/GpioInt() resources and GPIO
418
436
 connection IDs need to be provided by device drivers.
419
437
 
420
-For details refer to Documentation/acpi/gpio-properties.txt
438
+For details refer to Documentation/firmware-guide/acpi/gpio-properties.rst
421
439
 
422
440
 
423
441
 Interacting With the Legacy GPIO Subsystem