Merge tag 'gpio-v4.1-1' of git://git.kernel.org/pub/scm/linux/kernel/git/linusw/linux-gpio

Altera GPIO controller bindings

Required properties:

- compatible:

  - "altr,pio-1.0"

- reg: Physical base address and length of the controller's registers.

- #gpio-cells : Should be 2

  - The first cell is the gpio offset number.

  - The second cell is reserved and is currently unused.

- gpio-controller : Marks the device node as a GPIO controller.

- interrupt-controller: Mark the device node as an interrupt controller

- #interrupt-cells : Should be 1. The interrupt type is fixed in the hardware.

  - The first cell is the GPIO offset number within the GPIO controller.

- interrupts: Specify the interrupt.

- altr,interrupt-trigger: Specifies the interrupt trigger type the GPIO

  hardware is synthesized. This field is required if the Altera GPIO controller

  used has IRQ enabled as the interrupt type is not software controlled,

  but hardware synthesized. Required if GPIO is used as an interrupt

  controller. The value is defined in <dt-bindings/interrupt-controller/irq.h>

  Only the following flags are supported:

    IRQ_TYPE_EDGE_RISING

    IRQ_TYPE_EDGE_FALLING

    IRQ_TYPE_EDGE_BOTH

    IRQ_TYPE_LEVEL_HIGH

Optional properties:

- altr,ngpio: Width of the GPIO bank. This defines how many pins the

  GPIO device has. Ranges between 1-32. Optional and defaults to 32 if not

  specified.

Example:

gpio_altr: gpio@0xff200000 {

	compatible = "altr,pio-1.0";

	reg = <0xff200000 0x10>;

	interrupts = <0 45 4>;

	altr,ngpio = <32>;

	altr,interrupt-trigger = <IRQ_TYPE_EDGE_RISING>;

	#gpio-cells = <2>;

	gpio-controller;

	#interrupt-cells = <1>;

	interrupt-controller;

};

property, and a #gpio-cells integer property, which indicates the number of

cells in a gpio-specifier.

The GPIO chip may contain GPIO hog definitions. GPIO hogging is a mechanism

providing automatic GPIO request and configuration as part of the

gpio-controller's driver probe function.

Each GPIO hog definition is represented as a child node of the GPIO controller.

Required properties:

- gpio-hog:   A property specifying that this child node represent a GPIO hog.

- gpios:      Store the GPIO information (id, flags, ...). Shall contain the

	      number of cells specified in its parent node (GPIO controller

	      node).

Only one of the following properties scanned in the order shown below.

This means that when multiple properties are present they will be searched

in the order presented below and the first match is taken as the intended

configuration.

- input:      A property specifying to set the GPIO direction as input.

- output-low  A property specifying to set the GPIO direction as output with

	      the value low.

- output-high A property specifying to set the GPIO direction as output with

	      the value high.

Optional properties:

- line-name:  The GPIO label name. If not present the node name is used.

Example of two SOC GPIO banks defined as gpio-controller nodes:

	qe_pio_a: gpio-controller@1400 {

		reg = <0x1400 0x18>;

		gpio-controller;

		#gpio-cells = <2>;

		line_b {

			gpio-hog;

			gpios = <6 0>;

			output-low;

			line-name = "foo-bar-gpio";

		};

	};

	qe_pio_e: gpio-controller@1460 {

  gpio_mux.

- interrupt-names : Should be the names of irq resources. Each interrupt

  uses its own interrupt name, so there should be as many interrupt names

  as referenced interrups.

  as referenced interrupts.

- interrupt-controller : Identifies the node as an interrupt controller.

- #interrupt-cells: Specifies the number of cells needed to encode an

  interrupt source.

gpiod_get_index_optional() functions can be used. These functions return NULL

instead of -ENOENT if no GPIO has been assigned to the requested function:

	struct gpio_desc *gpiod_get_optional(struct device *dev,

					     const char *con_id,

					     enum gpiod_flags flags)

						   unsigned int index,

						   enum gpiod_flags flags)

For a function using multiple GPIOs all of those can be obtained with one call:

	struct gpio_descs *gpiod_get_array(struct device *dev,

					   const char *con_id,

					   enum gpiod_flags flags)

This function returns a struct gpio_descs which contains an array of

descriptors:

	struct gpio_descs {

		unsigned int ndescs;

		struct gpio_desc *desc[];

	}

The following function returns NULL instead of -ENOENT if no GPIOs have been

assigned to the requested function:

	struct gpio_descs *gpiod_get_array_optional(struct device *dev,

						    const char *con_id,

						    enum gpiod_flags flags)

Device-managed variants of these functions are also defined:

	struct gpio_desc *devm_gpiod_get(struct device *dev, const char *con_id,

							unsigned int index,

							enum gpiod_flags flags)

	struct gpio_descs *devm_gpiod_get_array(struct device *dev,

						const char *con_id,

						enum gpiod_flags flags)

	struct gpio_descs *devm_gpiod_get_array_optional(struct device *dev,

							 const char *con_id,

							 enum gpiod_flags flags)

A GPIO descriptor can be disposed of using the gpiod_put() function:

	void gpiod_put(struct gpio_desc *desc)

It is strictly forbidden to use a descriptor after calling this function. The

device-managed variant is, unsurprisingly:

For an array of GPIOs this function can be used:

	void gpiod_put_array(struct gpio_descs *descs)

It is strictly forbidden to use a descriptor after calling these functions.

It is also not allowed to individually release descriptors (using gpiod_put())

from an array acquired with gpiod_get_array().

The device-managed variants are, unsurprisingly:

	void devm_gpiod_put(struct device *dev, struct gpio_desc *desc)

	void devm_gpiod_put_array(struct device *dev, struct gpio_descs *descs)

Using GPIOs

===========

corresponding chip driver. In that case a significantly improved performance

can be expected. If simultaneous setting is not possible the GPIOs will be set

sequentially.

The gpiod_set_array() functions take three arguments:

	* array_size	- the number of array elements

	* desc_array	- an array of GPIO descriptors

	* value_array	- an array of values to assign to the GPIOs

The descriptor array can be obtained using the gpiod_get_array() function

or one of its variants. If the group of descriptors returned by that function

matches the desired group of GPIOs, those GPIOs can be set by simply using

the struct gpio_descs returned by gpiod_get_array():

	struct gpio_descs *my_gpio_descs = gpiod_get_array(...);

	gpiod_set_array(my_gpio_descs->ndescs, my_gpio_descs->desc,

			my_gpio_values);

It is also possible to set a completely arbitrary array of descriptors. The

descriptors may be obtained using any combination of gpiod_get() and

gpiod_get_array(). Afterwards the array of descriptors has to be setup

manually before it can be used with gpiod_set_array().

Note that for optimal performance GPIOs belonging to the same chip should be

contiguous within the array of descriptors.

S:	Maintained

F:	drivers/mailbox/mailbox-altera.c

ALTERA PIO DRIVER

M:	Tien Hock Loh <thloh@altera.com>

L:	linux-gpio@vger.kernel.org

S:	Maintained

F:	drivers/gpio/gpio-altera.c

ALTERA TRIPLE SPEED ETHERNET DRIVER

M:	Vince Bridgers <vbridger@opensource.altera.com>

L:	netdev@vger.kernel.org