Using the EMAC GPIO Class - Revision history

Mdean: Updated with new templates. Left content since it may be replaced for new API.

2015-11-13T22:35:15Z

Updated with new templates. Left content since it may be replaced for new API.

Mdean: Marked page for revision because of Device Tree.

2014-11-18T23:47:52Z

Marked page for revision because of Device Tree.

Bserrano at 19:53, 14 April 2014

2014-04-14T19:53:20Z

Bserrano at 22:08, 26 March 2014

2014-03-26T22:08:34Z

Bserrano at 21:50, 26 March 2014

2014-03-26T21:50:11Z

Bserrano at 22:25, 4 March 2014

2014-03-04T22:25:19Z

Tstratman: updated project tags

2014-01-31T12:37:03Z

updated project tags

Tstratman: /* EMAC GPIO Class Definition */ fixed code formatting

2014-01-25T14:19:40Z

‎EMAC GPIO Class Definition: fixed code formatting

Mdean: Approved for Final Draft status.

2014-01-16T19:59:04Z

Approved for Final Draft status.

Mdean: /* Adding Asynchronous Notification Support */ Numerous fixes; restructured several paragraphs; improved phrasing.

2014-01-16T19:57:38Z

‎Adding Asynchronous Notification Support: Numerous fixes; restructured several paragraphs; improved phrasing.

@@ Line 1: / Line 1: @@
-{{todo|REVISE; List related hardware eventually; (12.17.13-18:20->KY+);(12.18.13-19:00->MD+);(12.19.13-11:21->MW+);(01.14.14-14:20->KY-);(01.15.14-14:00->KY+);(01.16.14-14:00->MD+);(01.25.14-14:19->TS+);(03.04.14-16:25->BS-);(03.26.14-16:50->BS+);(04.14.14-14:50->BS+);(11.18.14-17:45->MD-)|Klint Youngmeyer|project=oe 4, oe 5,mw,ky,SEOKWREV,md,ts,bs}}
+{{todo|REVISE; List related hardware eventually; (12.17.13-18:20->KY+);(12.18.13-19:00->MD+);(12.19.13-11:21->MW+);(01.14.14-14:20->KY-);(01.15.14-14:00->KY+);(01.16.14-14:00->MD+);(01.25.14-14:19->TS+);(03.04.14-16:25->BS-);(03.26.14-16:50->BS+);(04.14.14-14:50->BS+);(11.18.14-17:45->MD-);(11.13.2015-16:35->MD+)|Klint Youngmeyer|project=oe 4, oe 5,mw,ky,md,ts,bs,Revise}}
 {{#seo:
@@ Line 131: / Line 131: @@
 ===Lock===
 Many GPIO devices may be accessed by multiple processes simultaneously, which leads to the possibility of race conditions. The EMAC GPIO Class includes a locking mechanism to prevent these cases when used correctly. Without the locking mechanism, synchronization needs to be performed in userspace.
@@ Line 140: / Line 137: @@
 All access to a device must be synchronized using the lock. Further details on this implementation are described in later sections.
 ==User Interfaces==
@@ Line 149: / Line 147: @@
 The GPIO Class driver registers a directory at <code>/sys/class/gpio</code> assuming that sysfs has been mounted on the system. Under this directory, every GPIO Class device registered with the system will have a directory (i.e. <code>/sys/class/gpio/porta</code>). Within this directory, there will be some files that are a part of the sysfs heirarchy as well as the GPIO Class interface files <code>data</code>, <code>ddr</code>, and <code>index</code>. Depending on the type of device and its implementation, the <code>ddr</code> and <code>index</code> files may or may not exist; <code>data</code> should always be present.
+{{ note | '''Note:''' The <code>/sys/class/gpio</code> directory is used by the new I/O driver code in the standard Linux kernel tree. This location will be changed by EMAC in the near future to avoid conflict.}}
 ==== Reading ====
@@ Line 157: / Line 153: @@
 Reading the current value of a device's settings is as simple as reading the respective file. The <code>cat</code> command is typically used for this. The output is formatted as ASCII hexadecimal characters. For example, to read the value of the data member of the <code>porta</code> device, run the command:
-<syntaxhighlight lang=console>
+{{cli | hostname=emac-oe |cat /sys/class/gpio/porta/data}}
 The implementation of the read function for the <code>data</code>, <code>ddr</code>, and <code>index</code> members using the sysfs interface automatically acquires and frees the lock on the respective GPIO device. The actual value returned depends on the device implementation.
@@ Line 166: / Line 160: @@
 Writing a new setting to a member of the GPIO device through the sysfs interface is accomplished by writing a new value to the respective file. The <code>echo</code> command is typically used along with file redirection to set the new value directly, although the output of any command could be used as long as it is formatted correctly. For example, to set the <code>porta</code> device to <code>0xFF</code> (all on) the user would first set all bits to output using the <code>ddr</code> register and then write <code>0xFF</code> to the data register as shown below:
+{{cli | hostname=emac-oe |echo 0xff > /sys/class/gpio/porta/ddr}}
-<syntaxhighlight lang=console>
+{{cli | hostname=emac-oe |echo 0xff > /sys/class/gpio/porta/data}}
 The implementation of the write function for the <code>data</code>, <code>ddr</code>, and <code>index</code> members using the sysfs interface automatically acquires and frees the lock on the respective GPIO device. The low-level effects of the write function depends on the device implementation.
@@ Line 220: / Line 211: @@
 ==== Programming ====
 The following general examples demonstrate the character driver programming interface.
+{{ note | The examples below do not check the return value of calls for errors. Be sure to check for and handle errors in a production system.}}
@@ Line 265: / Line 254: @@
 The following example utilizes the asynchronous notification interface for a device that supports it. This particular device is an interrupt-enabled register that will notify a process if the type of interrupt that occurs matches the notification mask of the particular file descriptor. When an applicable interrupt occurs, the data register will immediately be queued into the file descriptor specific data queue.
+{{ note | '''Note:''' The device utilized in the example below is an example device which does not exist on any EMAC system. The example is provided to illustrate the asynchronous notification interface which may be available on a system for a real device.}}

← Older revision		Revision as of 23:47, 18 November 2014
Line 1:		Line 1:
−	{{todo\|~~SEOKWREV~~; List related hardware eventually; (12.17.13-18:20->KY+);(12.18.13-19:00->MD+);(12.19.13-11:21->MW+);(01.14.14-14:20->KY-);(01.15.14-14:00->KY+);(01.16.14-14:00->MD+);(01.25.14-14:19->TS+);(03.04.14-16:25->BS-);(03.26.14-16:50->BS+);(04.14.14-14:50->BS+)\|Klint Youngmeyer\|project=oe 4, oe 5,mw,ky,SEOKWREV,md,ts,bs}}	+	{{todo\|REVISE; List related hardware eventually; (12.17.13-18:20->KY+);(12.18.13-19:00->MD+);(12.19.13-11:21->MW+);(01.14.14-14:20->KY-);(01.15.14-14:00->KY+);(01.16.14-14:00->MD+);(01.25.14-14:19->TS+);(03.04.14-16:25->BS-);(03.26.14-16:50->BS+);(04.14.14-14:50->BS+);(11.18.14-17:45->MD-)\|Klint Youngmeyer\|project=oe 4, oe 5,mw,ky,SEOKWREV,md,ts,bs}}

	{{#seo:		{{#seo:

@@ Line 1: / Line 1: @@
-{{todo|SEOKWREV; List related hardware eventually; (12.17.13-18:20->KY+);(12.18.13-19:00->MD+);(12.19.13-11:21->MW+);(01.14.14-14:20->KY-);(01.15.14-14:00->KY+);(01.16.14-14:00->MD+);(01.25.14-14:19->TS+);(03.04.14-16:25->BS-);(03.26.14-16:50->BS+)|Klint Youngmeyer|project=oe 4, oe 5,mw,ky,SEOKWREV,md,ts,bs}}
+{{todo|SEOKWREV; List related hardware eventually; (12.17.13-18:20->KY+);(12.18.13-19:00->MD+);(12.19.13-11:21->MW+);(01.14.14-14:20->KY-);(01.15.14-14:00->KY+);(01.16.14-14:00->MD+);(01.25.14-14:19->TS+);(03.04.14-16:25->BS-);(03.26.14-16:50->BS+);(04.14.14-14:50->BS+)|Klint Youngmeyer|project=oe 4, oe 5,mw,ky,SEOKWREV,md,ts,bs}}
 {{#seo:
 |title=Using the EMAC GPIO Class
 |titlemode=append
-|keywords=EMAC GPIO Class,EMAC GPIO Class Definition,Example GPIO Devices,Kernel Driver Implementation,GPIO Class Device Components
+|keywords=GPIO Components,GPIO User Interfaces,Asynchronous Notification Example,GPIO Example
 |description=The EMAC GPIO Class is a generic programming interface for General Purpose Input Output (GPIO) devices in the Linux Kernel.
 }}

@@ Line 4: / Line 4: @@
 |title=Using the EMAC GPIO Class
 |titlemode=append
-|keywords=EMAC GPIO Class,EMAC GPIO Class Definition,Example GPIO Devices,Kernal Driver Implementation,GPIO Class Device Components
+|keywords=EMAC GPIO Class,EMAC GPIO Class Definition,Example GPIO Devices,Kernel Driver Implementation,GPIO Class Device Components
 |description=The EMAC GPIO Class is a generic programming interface for General Purpose Input Output (GPIO) devices in the Linux Kernel.
 }}

← Older revision		Revision as of 21:50, 26 March 2014
Line 1:		Line 1:
−	{{todo\|~~SEOKWTODO~~; List related hardware eventually; (12.17.13-18:20->KY+);(12.18.13-19:00->MD+);(12.19.13-11:21->MW+);(01.14.14-14:20->KY-);(01.15.14-14:00->KY+);(01.16.14-14:00->MD+);(01.25.14-14:19->TS+);(03.04.14-16:25->BS-)\|~~Brian Serrano~~\|project=oe 4, oe 5,mw,ky,~~SEOKWTODO~~,md,ts,bs}}	+	{{todo\|SEOKWREV; List related hardware eventually; (12.17.13-18:20->KY+);(12.18.13-19:00->MD+);(12.19.13-11:21->MW+);(01.14.14-14:20->KY-);(01.15.14-14:00->KY+);(01.16.14-14:00->MD+);(01.25.14-14:19->TS+);(03.04.14-16:25->BS-);(03.26.14-16:50->BS+)\|Klint Youngmeyer\|project=oe 4, oe 5,mw,ky,SEOKWREV,md,ts,bs}}

		+	{{#seo:
		+	\|title=Using the EMAC GPIO Class
		+	\|titlemode=append
		+	\|keywords=EMAC GPIO Class,EMAC GPIO Class Definition,Example GPIO Devices,Kernal Driver Implementation,GPIO Class Device Components
		+	\|description=The EMAC GPIO Class is a generic programming interface for General Purpose Input Output (GPIO) devices in the Linux Kernel.
		+	}}
	The EMAC GPIO Class is a generic programming interface for General Purpose Input Output (GPIO) devices in the Linux Kernel. The GPIO class driver has two main interfaces under standard Linux: Linux sysfs and character device. The GPIO class is extremely flexible and uses a set of function pointers at the kernel level to allow for specialized read/write functions for each device. EMAC utilizes the GPIO class to create devices that use the same simple interface, such as GPIO registers, simple configuration variables, hardware registers, and Analog-to-Digital converter drivers where the user needs to retrieve a single value from the device.		The EMAC GPIO Class is a generic programming interface for General Purpose Input Output (GPIO) devices in the Linux Kernel. The GPIO class driver has two main interfaces under standard Linux: Linux sysfs and character device. The GPIO class is extremely flexible and uses a set of function pointers at the kernel level to allow for specialized read/write functions for each device. EMAC utilizes the GPIO class to create devices that use the same simple interface, such as GPIO registers, simple configuration variables, hardware registers, and Analog-to-Digital converter drivers where the user needs to retrieve a single value from the device.

← Older revision		Revision as of 22:25, 4 March 2014
Line 1:		Line 1:
−	{{todo\|~~Complete~~; List related hardware eventually; (12.17.13-18:20->KY+);(12.18.13-19:00->MD+);(12.19.13-11:21->MW+);(01.14.14-14:20->KY-);(01.15.14-14:00->KY+);(01.16.14-14:00->MD+);(01.25.14-14:19->TS+)\|~~Klint Youngmeyer~~\|project=oe 4, oe 5,mw,ky,~~Complete~~,md,ts}}	+	{{todo\|SEOKWTODO; List related hardware eventually; (12.17.13-18:20->KY+);(12.18.13-19:00->MD+);(12.19.13-11:21->MW+);(01.14.14-14:20->KY-);(01.15.14-14:00->KY+);(01.16.14-14:00->MD+);(01.25.14-14:19->TS+);(03.04.14-16:25->BS-)\|Brian Serrano\|project=oe 4, oe 5,mw,ky,SEOKWTODO,md,ts,bs}}

	The EMAC GPIO Class is a generic programming interface for General Purpose Input Output (GPIO) devices in the Linux Kernel. The GPIO class driver has two main interfaces under standard Linux: Linux sysfs and character device. The GPIO class is extremely flexible and uses a set of function pointers at the kernel level to allow for specialized read/write functions for each device. EMAC utilizes the GPIO class to create devices that use the same simple interface, such as GPIO registers, simple configuration variables, hardware registers, and Analog-to-Digital converter drivers where the user needs to retrieve a single value from the device.		The EMAC GPIO Class is a generic programming interface for General Purpose Input Output (GPIO) devices in the Linux Kernel. The GPIO class driver has two main interfaces under standard Linux: Linux sysfs and character device. The GPIO class is extremely flexible and uses a set of function pointers at the kernel level to allow for specialized read/write functions for each device. EMAC utilizes the GPIO class to create devices that use the same simple interface, such as GPIO registers, simple configuration variables, hardware registers, and Analog-to-Digital converter drivers where the user needs to retrieve a single value from the device.

← Older revision		Revision as of 12:37, 31 January 2014
Line 1:		Line 1:
−	{{todo\|~~Final Draft~~; List related hardware eventually; (12.17.13-18:20->KY+);(12.18.13-19:00->MD+);(12.19.13-11:21->MW+);(01.14.14-14:20->KY-);(01.15.14-14:00->KY+);(01.16.14-14:00->MD+)\|Klint Youngmeyer\|project=oe 4, oe 5,mw,ky,~~FinalDraft~~,md,ts}}	+	{{todo\|Complete; List related hardware eventually; (12.17.13-18:20->KY+);(12.18.13-19:00->MD+);(12.19.13-11:21->MW+);(01.14.14-14:20->KY-);(01.15.14-14:00->KY+);(01.16.14-14:00->MD+);(01.25.14-14:19->TS+)\|Klint Youngmeyer\|project=oe 4, oe 5,mw,ky,Complete,md,ts}}

	The EMAC GPIO Class is a generic programming interface for General Purpose Input Output (GPIO) devices in the Linux Kernel. The GPIO class driver has two main interfaces under standard Linux: Linux sysfs and character device. The GPIO class is extremely flexible and uses a set of function pointers at the kernel level to allow for specialized read/write functions for each device. EMAC utilizes the GPIO class to create devices that use the same simple interface, such as GPIO registers, simple configuration variables, hardware registers, and Analog-to-Digital converter drivers where the user needs to retrieve a single value from the device.		The EMAC GPIO Class is a generic programming interface for General Purpose Input Output (GPIO) devices in the Linux Kernel. The GPIO class driver has two main interfaces under standard Linux: Linux sysfs and character device. The GPIO class is extremely flexible and uses a set of function pointers at the kernel level to allow for specialized read/write functions for each device. EMAC utilizes the GPIO class to create devices that use the same simple interface, such as GPIO registers, simple configuration variables, hardware registers, and Analog-to-Digital converter drivers where the user needs to retrieve a single value from the device.

@@ Line 497: / Line 497: @@
 <syntaxhighlight lang=c>
-// Read functions
+/* Write functions */
-int          gpio_ddr_write8(  gpio_t *gpio, gpio_data data );
+int          gpio_ddr_write8(gpio_t *gpio, gpio_data data);
-int          gpio_data_write8( gpio_t *gpio, gpio_data data );
+int          gpio_data_write8(gpio_t *gpio, gpio_data data);
-int          gpio_index_write( gpio_t *gpio, gpio_data data );
+int          gpio_index_write(gpio_t *gpio, gpio_data data);
-int          gpio_empty_write( gpio_t *gpio, gpio_data data );
+int          gpio_empty_write(gpio_t *gpio, gpio_data data);
-// Write functions
+/* Read functions */
-gpio_data    gpio_ddr_read8(    gpio_t *gpio );
+gpio_data    gpio_ddr_read8(gpio_t *gpio);
-gpio_data    gpio_data_read8(   gpio_t *gpio );
+gpio_data    gpio_data_read8(gpio_t *gpio);
-gpio_data    gpio_index_read(   gpio_t *gpio );
+gpio_data    gpio_index_read(gpio_t *gpio);
-gpio_data    gpio_shadow_read8( gpio_t *gpio );
+gpio_data    gpio_shadow_read8(gpio_t *gpio);
-gpio_data    gpio_ff_read(      gpio_t *gpio );
+gpio_data    gpio_ff_read(gpio_t *gpio);
-gpio_data    gpio_zero_read(    gpio_t *gpio );
+gpio_data    gpio_zero_read(gpio_t *gpio);
 </syntaxhighlight>

← Older revision		Revision as of 19:59, 16 January 2014
Line 1:		Line 1:
−	{{todo\|~~Review again~~; List related hardware eventually; (12.17.13-18:20->KY+);(12.18.13-19:00->MD+);(12.19.13-11:21->MW+);(01.14.14-14:20->KY-);(01.15.14-14:00->KY+)\|Klint Youngmeyer\|project=oe 4, oe 5,mw,ky,~~Review~~,md}}	+	{{todo\|Final Draft; List related hardware eventually; (12.17.13-18:20->KY+);(12.18.13-19:00->MD+);(12.19.13-11:21->MW+);(01.14.14-14:20->KY-);(01.15.14-14:00->KY+);(01.16.14-14:00->MD+)\|Klint Youngmeyer\|project=oe 4, oe 5,mw,ky,FinalDraft,md,ts}}

	The EMAC GPIO Class is a generic programming interface for General Purpose Input Output (GPIO) devices in the Linux Kernel. The GPIO class driver has two main interfaces under standard Linux: Linux sysfs and character device. The GPIO class is extremely flexible and uses a set of function pointers at the kernel level to allow for specialized read/write functions for each device. EMAC utilizes the GPIO class to create devices that use the same simple interface, such as GPIO registers, simple configuration variables, hardware registers, and Analog-to-Digital converter drivers where the user needs to retrieve a single value from the device.		The EMAC GPIO Class is a generic programming interface for General Purpose Input Output (GPIO) devices in the Linux Kernel. The GPIO class driver has two main interfaces under standard Linux: Linux sysfs and character device. The GPIO class is extremely flexible and uses a set of function pointers at the kernel level to allow for specialized read/write functions for each device. EMAC utilizes the GPIO class to create devices that use the same simple interface, such as GPIO registers, simple configuration variables, hardware registers, and Analog-to-Digital converter drivers where the user needs to retrieve a single value from the device.

@@ Line 650: / Line 650: @@
 If required, asynchronous notification support could be added to the <code>ege_gpio</code> device from the example above. This section provides a simple example of the code required to add this feature.
-The <code>irq_data</code> member of the GPIO class device is used to specify the action used for asynchronous notification and interrupt handling. The IRQ will be requested, configured, and registered in the GPIO character interface (<code>gpio_char.c</code>) if <code>irq_data</code> is valid
+The <code>irq_data</code> member of the GPIO class device specifies the action to take for asynchronous notification and interrupt handling. The IRQ will be requested, configured, and registered in the GPIO character interface (<code>gpio_char.c</code>) if <code>irq_data</code> is valid.
-The <code>handler</code> member of <code>irq_data</code> is a function pointer which will be called by the generic GPIO class IRQ handler. This will be scheduled in a workqueue from the interrupt handler outside of interrupt context and called with the GPIO device lock held. This allows for the feature to be utilized by interfaces such as SPI devices which may sleep during hardware access. The function returns a bit mask for comparison with the notification mask set on any open devices. This reflects which type of hardware event has occurred. Typically, the <code>handler</code> function would read an interrupt status register from the device associated with the GPIO interface, such as a PLD register. In the most basic form where only one type of interrupt can occur the <code>handler</code> would simply return 1. The example <code>handler</code> function shown below calls a function <code>read_interrupt_status()</code>, the implementation for which is not discussed here.
 <syntaxhighlight lang=c>
 static gpio_data ege_gpio_handler(struct gpio_s *gpio)
@@ Line 660: / Line 666: @@
 </syntaxhighlight>
-The <code>get_queue</code> member of <code>irq_data</code> is a function pointer which is called by the GPIO class interface to determine what data to add to the queue for any file-descriptor matching the notify mask of the interrupt type that has occurred. This function will be called with the device mutex held. The most common implementation of this function is to simply utilize the <code>data_read</code> function of the associated device and store the current value. This is useful to capture the current hardware state as instantaneously as possible after the interrupt occurs before the userspace process is notified of the event. It may be used for other purposes, however, such as taking a timestamp or reading a different hardware register. The current notify mask returned by <code>handler</code> will be passed to the <code>get_queue</code> function, so it is possible to customize the action based on the type of event(s) that occurred. The <code>get_queue</code> function shown below simply reads the current value returned by <code>data_read</code>.
 <syntaxhighlight lang=c>
 static gpio_data ege_gpio_get_queue(struct gpio_s *gpio, gpio_data notify)
@@ Line 668: / Line 681: @@
 </syntaxhighlight>
 The <code>irq_config</code> member of <code>irq_data</code> is called by the GPIO class interface before calling <code>request_irq</code>. The purpose of this function is to configure and enable the interrupt in the associated hardware for the GPIO device. In many cases, this function will have few tasks to perform. In the example <code>irq_config</code> function shown below, the <code>set_irq_wake()</code> function is called to note that the interrupt should be allowed to wake the hardware from APM suspend mode.
 <syntaxhighlight lang=c>
 static void ege_gpio_irq_config(struct gpio_s *gpio)
@@ Line 676: / Line 694: @@
 </syntaxhighlight>
-The <code>change_notify</code> member of <code>irq_data</code> is used to make any changes to the hardware when the user interface changes the notification mask. This may or may not be necessary depending on the desired operation. The primary design function is to keep track of which types of interrupts should be enabled and disabled in the associated hardware. For example, if no file-descriptors are registered for notification on a certain type of event, the associated bit should be disabled in the interrupt enable register. The bit should be enabled in the interrupt enable register as soon as one or more file-descriptors are set up to be notified on this type of event. The current notify mask for the file-descriptor as well as the new notify mask will be passed as arguments so that <code>change_notify</code> can determine which bits have been altered. The function for this simple interface does nothing.
 <syntaxhighlight lang=c>
 static void ege_gpio_change_notify(struct gpio_s *gpio, gpio_data curr_notify,
@@ Line 684: / Line 707: @@
 </syntaxhighlight>
 The final step for adding IRQ handling and asynchronous notification to the interface is to specify the <code>irq_data</code> structure as part of the device initialization. The <code>irq</code> and <code>irq_flags</code> members are used to denote the specific interrupt and its features. The updated <code>ege_gpio_class_create</code> function is as follows:
 <syntaxhighlight lang=c>
 struct device *ege_gpio_class_create(void)
@@ Line 712: / Line 738: @@
+}
 </syntaxhighlight>
 After adding the code above, the EMAC GPIO Class driver will register, enable, and handle the interrupt exactly as specified. Notification can be enabled for userspace processes according to the [[#Asynchronous_Notification_Example|Asynchronous Notification Example]].
 <!--[[Category:Custom Development]]-->