Difference between revisions of "GPIO pins"

From LinuxTVWiki
Jump to: navigation, search
(GPIOs of BT8x8)
m (How GPIO pins work: more minor edits; rephrasing and clarifying)
 
(35 intermediate revisions by 9 users not shown)
Line 1: Line 1:
==What are GPIO pins?==
+
'''GPIO''' (General Purpose Input/Output) is an interface that may be found on some computer IC components such as a micro-controller or interface chipset.   Typically, the GPIO is a one or more pins on the IC which have no special purpose in of themselves, but which facilitate an optional ability for device designers to create an interface/connection between the IC and a peripheral component.  Thereby, within limitations, GPIO pins can be tailored for use to provide some specific function or purpose within a hardware device design.
GPIO means General Purpose I/O. Video decoder chips like the [[PCI_interface_chipsets_used_for_v4l_cards|SAA713x]] or the [[PCI_interface_chipsets_used_for_v4l_cards|BT8x8]] have a number of I/O pins that are not used by the video decoder itself. They have no special purpose, each manufacturer can do with them whatever he wants.
+
  
That makes it hard to answer questions like "What I'll have to fill into these gpio fields when adding a new card", because there simply is no general answer to that question, it completely depends on the board design.  Some hopefully useful hints:
+
==How GPIO pins work==
 +
A GPIO pin on an IC is typically connected to some other chip, and performs some function by reading or changing its state. GPIO pins can act as either an:
 +
* input - to read digital signals from a circuit; that is, when configured for input mode, they read the current state as either "high" or "low"
 +
* output - to control or signal other devices attached to the IC and, as such, the pins are configured to be “high” or “low” when in output mode
  
* First ignore them completely.  Especially with non-bt878 cards (saa7134, cx88 drivers) they might not be used at all or at least not needed for the basic functionality of the board.
+
Usually each GPIO pin is individually configurable as either an input or output -- each pin can be setup flexibly to accept or source different logic voltages, with configurable drive strengths and pull up/downs.
 +
In others cases, GPIOs are arranged into very simple groups, typically of 8 pins – known as a GPIO port - that can be switched as a group to either input or output.
  
* Failing that check out whenever there are already entries for other cards from the same vendor and try these settings. Vendors usually don't redesign everything from scratch for a new card, so chances are good that a identical or very simliar configuation works fine.
+
The input and output voltages are typically, though not universally, limited to the supply voltage of the IC upon which the GPIOs reside, and usage of voltages greater then that may cause damage to the chip. Though, in the case of some ICs, the GPIOs have 5V tolerant inputs, such that even when the IC itself has a low supply voltages (2V), it can accept the greater voltage (5V) on the GPIO pin input without damage.
  
What the gpio pins are used for:
+
In some cases, GPIOs may be configurable to produce CPU interrupts and be able to use Direct Memory Access to move large quantities of data efficiently into or out of the device.
  
* Sometimes, 2 or 3 of them  are used to control an audio multiplexer.  That is especially true for bt878-based cards, because that chip hasn't a audio mux built-in.
+
==GPIO pins within the context of V4L-DVB devices==
 +
It is quite common for the [[interface chipsets|interface chipset]] of a V4L-DVB device to be equipped with GPIO pins.    For example, interface chipsets/Video decoder chips like the [[NXP SAA713x Family|SAA713x]] or the  [[PCI_interface_chipsets_used_for_v4l_cards|BT8x8]] have a number of I/O pins that are not used by the video decoder itself.
  
* IR receiver chips are also often connected via GPIO. Thats not the only way though. i2c is common as well, and the cx2388x has built-in support for IR signal sampling.
+
Typically what the GPIO pins are used for:
 +
* Sometimes, 2 or 3 of them are used to control an audio multiplexer found elsewhere on the device. That is especially true for bt878-based cards, as that particular chip lacks a built-in audio mux and therefore must rely upon external components to provide such functionality.  
  
* Sometimes it is possible to reset external chips via gpio.  For example bt878-designs with a msp34xx audio processor usually have the msp34xx reset line linked to one of the gpio pins.
+
* IR receiver chips are also often connected via GPIO pins (though, thats not the only way, as [[I²C Protocol|I²C]] is common as well, and some interface chipsets, like the cx2388x, have built-in support for IR signal sampling).  
  
* Sometimes external chips can be enabled/disabled via GPIO. saa7134-based cardbus devices often have the tuner chip disabled, it's impossible to see the device on the i2c bus without waking it up by programming the correct GPIO pin. Probably done to power-down the tuner when unused for a longer battery life. For example, the Terratec Cinergy 400TV mobile uses GPIO 18 to switch the tuner on (0) or off (1).
+
* Sometimes it is possible to reset external chips via GPIO. For example, bt878-designs with a msp34xx audio processor usually have the msp34xx reset line linked to one of the GPIO pins.  As another example, in the case of the [[Hauppauge WinTV-HVR-950]] device, one of the GPIO pins on its em28xx bridge is connected to the “RESET” pin on the xc3028 tuner. Setting the state of the GPIO pin to low momentarily and then high again has the effect of resetting the chip to a known state. <br> It’s also worth noting that holding a chip in reset is often done as a power management measure, which is why you can see driver problems communicating with certain chips if the GPIOs are improperly configured. This sort of power management measure becomes particularly important on USB devices, where there is often not enough power available on the USB bus to have both the analog components and the digital components powered up at the same time.
  
That list likely isn't complete, but should give an
+
* Sometimes external chips can be enabled/disabled via GPIO. saa7134-based cardbus devices often have the tuner chip disabled, it's impossible to see the device on the i2c bus without waking it up by programming the correct GPIO pin. Probably done to power-down the tuner when unused for a longer battery life. For example, the Terratec Cinergy 400TV mobile uses GPIO 18 to switch the tuner on (0) or off (1).  
idea what GPIO pins are used for. They might also
+
be completely unused.
+
  
It's also noteworthy that some of the GPIO lines can be used to trigger interrupts, i.e. the video chip can raise an IRQ on the PCI bus on GPIO state changes.
+
* Other common uses of GPIO pins include connecting it to the power supply on a board to cut off power to certain peripheral components, or controlling whether a low noise amplifier (LNA) connected to the tuner is enabled.
  
Unused Pins are usually programmed as inputs.
+
* It's also noteworthy that some of the GPIO lines can be used to trigger interrupts i.e. the video chip can raise an IRQ on the PCI bus on GPIO state changes.
  
These GPIOs can not be read/written from user space. There is no IOCTL for them. They can only be used from within the kernel driver.
+
This list likely isn't complete, but it should give an idea what GPIO pins are used for in the context of V4L-DVB devices.  Also keep in mind that the GPIO pins might be completely unused -- it's a choice entirely up to the device manufacturer. Note: In practical terms, for tuner products, it is pretty rare for GPIO pins to be configured as inputs. [Side note: a related terminology to GPIO is GPO – which stands for “General Purpose Output” and is the same thing as a GPIO but functions as output only].  
  
===GPIOs of SAA713x===
+
===Programming GPIO pins===
 +
GPIOs can not be read_from/written_to from user space. There is no IOCTL for them. They can only be used from within the kernel driver.
 +
 
 +
Because each device manufacturer can do with GPIO pins whatever they want, it is hard to answer questions like "What do I have to fill into these GPIO fields when adding a new card?", because there simply is no general answer to that question;  it completely depends on the board design. Some hopefully useful hints:
 +
* First, ignore them completely. Especially with non-bt878 cards (saa7134, cx88 drivers) they might not be used at all or at least not needed for the basic functionality of the board.
 +
* Failing that check out whenever there are already entries for other cards from the same vendor and try these settings. Vendors usually don't redesign everything from scratch for a new card, so chances are good that a identical or very similar configuration works fine.
 +
* Unused Pins are usually programmed as inputs.
 +
 
 +
{{Box Warning|Haphazardly playing with or mis-configuring GPIO-pins may damage your device!
 +
'''If you undertake any modifications, we take no responsibility for any damage caused or which may be incurred to your device through the process.  You proceed entirely at your own risk'''}}
 +
 
 +
Two Windows based utilities that can be handy in the process of determining what to program for GPIO values in device definitions are:
 +
* RegSpy, included with [http://dscaler.org DScaler] and
 +
* BtSpy - http://btwincap.sourceforge.net/custom.html
 +
 
 +
In addition, a good old magnifying glass is a great tool. GPIO inputs are, after all, just pins on an IC that will be connected in circuit to an external component.  For example, you should be able to find and track the traces on the device's printed circuit board between the GPIO pins on an interface chipset and, say, a remote controller or mux switch or audio chip etc.  In conjunction with the datasheets for these ICs you'll likely be able to easily find the correct GPIO values.
 +
 
 +
====GPIOs of SAA713x====
 
The SAA713x has 27 of these pins. Each of them can be programmed to be an input or an output.   
 
The SAA713x has 27 of these pins. Each of them can be programmed to be an input or an output.   
 
Unused inputs are usually programmed as inputs.   
 
Unused inputs are usually programmed as inputs.   
Line 39: Line 59:
 
Warning: If that pin is really used as an input, it is probably connected to an other chip's output. If you come and configure it as an output, you have two outputs connected together. Though it is unlikely, this might damage your card. You've been warned.
 
Warning: If that pin is really used as an input, it is probably connected to an other chip's output. If you come and configure it as an output, you have two outputs connected together. Though it is unlikely, this might damage your card. You've been warned.
  
===GPIOs of BT8x8===
+
====GPIOs of BT8x8====
Here's how to program gpio for card definitions inside bttv-cards.c using RegSpy, included with DScaler - http://dscaler.org
+
Here's how to program gpio for card definitions inside bttv-cards.c using RegSpy. The BtSpy utility is also handy during this process.
  
 
Attach RegSpy to your TV App. Switch some channels around in analog video mode. Take note of the following values:
 
Attach RegSpy to your TV App. Switch some channels around in analog video mode. Take note of the following values:
Line 65: Line 85:
 
The following equation gets the same thing done:
 
The following equation gets the same thing done:
  
  (value) = gpiodata - maskedfs + gpiomask
+
  (value) = gpiodata + gpiomask - maskedfs
  
 
Each .audiomux array member is for a different input:
 
Each .audiomux array member is for a different input:
Line 84: Line 104:
 
  .audiomux      = { 0x00400005, 0, 0, 0, 0, 0 },
 
  .audiomux      = { 0x00400005, 0, 0, 0, 0, 0 },
  
===GPIOs of CX2388x===
+
BtSpy works in a similar method, except that the formula for calculating the gpiodata isn't necessary.  The output from BtSpy can be used directly to populate the fields in bttv-cards.c, without the need to interpret the data, as described for use with regspy, above.
(To be written)
+
 
 +
====GPIOs of CX2388x====
 +
To program gpio for card definitions inside cx88-cards.c , follow the directions above for using RegSpy with bt8xx cards but you'll want to consider a different set of values, namely MO_GPx_IO (x=0 to 3).  The relevant part of RegSpy's output will look basically like this:
 +
 
 +
MO_GP0_IO:    000000ff  (00000000 00000000 00000000 11111111)
 +
MO_GP1_IO:    0000f35d  (00000000 00000000 11110011 01011101)
 +
MO_GP2_IO:    00000001  (00000000 00000000 00000000 00000001)
 +
MO_GP3_IO:    00000000  (00000000 00000000 00000000 00000000)
 +
 
 +
Ignoring the binary values in parenthesis, find the entry in cx88-cards.c for the card you want to edit, and copy the hex values just to the left of them over to the appropriate fields for the mode you want to change.
 +
 
 +
In the case of an analog TV tuner, the result of your changes should look something like this:
 +
 
 +
.type  = CX88_VMUX_TELEVISION,
 +
.vmux  = 0,
 +
.gpio0  = 0x000000ff,
 +
.gpio1  = 0x0000f35d,
 +
.gpio2  = 0x00000000,
 +
.gpio3  = 0x00000000,
 +
 
 +
As with all cards, some GPIO pins may be defined as inputs, from the CX2388x's viewpoint.  Those GPIO values can just be replaced with all 0's.  For the example above, the relevant card defines .gpio2 as input, so we ignored the value RegSpy returned for MO_GP2_IO.
 +
 
 +
===GPIO for Remotes Controllers===
 +
 
 +
Sometimes the remote is handled via GPIO. It works according to the following scheme:
 +
 
 +
There are data bits and signal bits. Signal bits show whether a key is pressed
 +
or released; data bits show the key code. Signal bits can be of two types:
 +
* The first type is 1 when the key is released and 0 when the key is pressed
 +
* The second type is 0 when the key is released and 1 when the key is pressed
 +
 
 +
The mask_keycode should contain only ''data'' bits.<br>
 +
The mask_keyup should contain signal bits of ''first'' type. <br>
 +
The mask_keydown should contain signal bits of ''second'' type.
 +
 
 +
A good test is that all these masks should ''not'' intersect. See also [[Remote_controllers-V4L]]
 +
 
 +
==External Links==
 +
* [[wikipedia:General_Purpose_Input/Output|Wikipedia's GPIO article]]
 +
 
 +
[[Category:Technology]]
 +
[[Category:Hardware]]
 +
[[Category:Development]]

Latest revision as of 20:57, 18 April 2010

GPIO (General Purpose Input/Output) is an interface that may be found on some computer IC components such as a micro-controller or interface chipset. Typically, the GPIO is a one or more pins on the IC which have no special purpose in of themselves, but which facilitate an optional ability for device designers to create an interface/connection between the IC and a peripheral component. Thereby, within limitations, GPIO pins can be tailored for use to provide some specific function or purpose within a hardware device design.

How GPIO pins work

A GPIO pin on an IC is typically connected to some other chip, and performs some function by reading or changing its state. GPIO pins can act as either an:

  • input - to read digital signals from a circuit; that is, when configured for input mode, they read the current state as either "high" or "low"
  • output - to control or signal other devices attached to the IC and, as such, the pins are configured to be “high” or “low” when in output mode

Usually each GPIO pin is individually configurable as either an input or output -- each pin can be setup flexibly to accept or source different logic voltages, with configurable drive strengths and pull up/downs. In others cases, GPIOs are arranged into very simple groups, typically of 8 pins – known as a GPIO port - that can be switched as a group to either input or output.

The input and output voltages are typically, though not universally, limited to the supply voltage of the IC upon which the GPIOs reside, and usage of voltages greater then that may cause damage to the chip. Though, in the case of some ICs, the GPIOs have 5V tolerant inputs, such that even when the IC itself has a low supply voltages (2V), it can accept the greater voltage (5V) on the GPIO pin input without damage.

In some cases, GPIOs may be configurable to produce CPU interrupts and be able to use Direct Memory Access to move large quantities of data efficiently into or out of the device.

GPIO pins within the context of V4L-DVB devices

It is quite common for the interface chipset of a V4L-DVB device to be equipped with GPIO pins. For example, interface chipsets/Video decoder chips like the SAA713x or the BT8x8 have a number of I/O pins that are not used by the video decoder itself.

Typically what the GPIO pins are used for:

  • Sometimes, 2 or 3 of them are used to control an audio multiplexer found elsewhere on the device. That is especially true for bt878-based cards, as that particular chip lacks a built-in audio mux and therefore must rely upon external components to provide such functionality.
  • IR receiver chips are also often connected via GPIO pins (though, thats not the only way, as I²C is common as well, and some interface chipsets, like the cx2388x, have built-in support for IR signal sampling).
  • Sometimes it is possible to reset external chips via GPIO. For example, bt878-designs with a msp34xx audio processor usually have the msp34xx reset line linked to one of the GPIO pins. As another example, in the case of the Hauppauge WinTV-HVR-950 device, one of the GPIO pins on its em28xx bridge is connected to the “RESET” pin on the xc3028 tuner. Setting the state of the GPIO pin to low momentarily and then high again has the effect of resetting the chip to a known state.
    It’s also worth noting that holding a chip in reset is often done as a power management measure, which is why you can see driver problems communicating with certain chips if the GPIOs are improperly configured. This sort of power management measure becomes particularly important on USB devices, where there is often not enough power available on the USB bus to have both the analog components and the digital components powered up at the same time.
  • Sometimes external chips can be enabled/disabled via GPIO. saa7134-based cardbus devices often have the tuner chip disabled, it's impossible to see the device on the i2c bus without waking it up by programming the correct GPIO pin. Probably done to power-down the tuner when unused for a longer battery life. For example, the Terratec Cinergy 400TV mobile uses GPIO 18 to switch the tuner on (0) or off (1).
  • Other common uses of GPIO pins include connecting it to the power supply on a board to cut off power to certain peripheral components, or controlling whether a low noise amplifier (LNA) connected to the tuner is enabled.
  • It's also noteworthy that some of the GPIO lines can be used to trigger interrupts i.e. the video chip can raise an IRQ on the PCI bus on GPIO state changes.

This list likely isn't complete, but it should give an idea what GPIO pins are used for in the context of V4L-DVB devices. Also keep in mind that the GPIO pins might be completely unused -- it's a choice entirely up to the device manufacturer. Note: In practical terms, for tuner products, it is pretty rare for GPIO pins to be configured as inputs. [Side note: a related terminology to GPIO is GPO – which stands for “General Purpose Output” and is the same thing as a GPIO but functions as output only].

Programming GPIO pins

GPIOs can not be read_from/written_to from user space. There is no IOCTL for them. They can only be used from within the kernel driver.

Because each device manufacturer can do with GPIO pins whatever they want, it is hard to answer questions like "What do I have to fill into these GPIO fields when adding a new card?", because there simply is no general answer to that question; it completely depends on the board design. Some hopefully useful hints:

  • First, ignore them completely. Especially with non-bt878 cards (saa7134, cx88 drivers) they might not be used at all or at least not needed for the basic functionality of the board.
  • Failing that check out whenever there are already entries for other cards from the same vendor and try these settings. Vendors usually don't redesign everything from scratch for a new card, so chances are good that a identical or very similar configuration works fine.
  • Unused Pins are usually programmed as inputs.

Warning !!!

align=left Haphazardly playing with or mis-configuring GPIO-pins may damage your device!

If you undertake any modifications, we take no responsibility for any damage caused or which may be incurred to your device through the process. You proceed entirely at your own risk

Two Windows based utilities that can be handy in the process of determining what to program for GPIO values in device definitions are:

In addition, a good old magnifying glass is a great tool. GPIO inputs are, after all, just pins on an IC that will be connected in circuit to an external component. For example, you should be able to find and track the traces on the device's printed circuit board between the GPIO pins on an interface chipset and, say, a remote controller or mux switch or audio chip etc. In conjunction with the datasheets for these ICs you'll likely be able to easily find the correct GPIO values.

GPIOs of SAA713x

The SAA713x has 27 of these pins. Each of them can be programmed to be an input or an output. Unused inputs are usually programmed as inputs. Because of weak internal pull-down resistors in the SAA713x, open inputs are read as zeroes. If a bit is read as "1" after loading the saa7134 module, this means the manufacturer soldered a pull-up resistor to that pin. As they have no resistors to waste, this usually means, they do something with that pin...

So, if you're looking for a GPIO output, and you have a bit that is set to "1" after reset, this pin is a good candidate. Hack the driver to pull this bit low, and see if it does what you want.

If all your GPIO bits are "0" after reset -- bad luck. If there are outputs, they have to be active high. Try to set them high, one by one or groupwise, until you find what you are looking for.

Warning: If that pin is really used as an input, it is probably connected to an other chip's output. If you come and configure it as an output, you have two outputs connected together. Though it is unlikely, this might damage your card. You've been warned.

GPIOs of BT8x8

Here's how to program gpio for card definitions inside bttv-cards.c using RegSpy. The BtSpy utility is also handy during this process.

Attach RegSpy to your TV App. Switch some channels around in analog video mode. Take note of the following values:

BT848_GPIO_OUT_EN
BT848_GPIO_DATA

Use value of BT848_GPIO_OUT_EN for .gpiomask.

Use the following formula to arrive at values to be inserted into .audiomux array:

(maskedf's) - BT848_GPIO_OUT_EN + (value) = BT848_GPIO_DATA

For example, for card#135, DViCO FusionHDTV5 Lite, I got the following from RegSpy:

BT848_GPIO_OUT_EN:  00e00007   (00000000 11100000 00000000 00000111)                 
BT848_GPIO_DATA:    005ffffd   (00000000 01011111 11111111 11111101)

Using the above formula, where "maskedfs" is found by taking gpiomask, and changing all non-zeros to f's. All the zeroed bits in the gpiomask should be ignored, for the purposes of the equation.

maskedfs - gpiomask +  (value) = gpiodata
00f0000f - 00e00007 + audiomux = 005ffffd
                      audiomux = 00400005

The following equation gets the same thing done:

(value) = gpiodata + gpiomask - maskedfs

Each .audiomux array member is for a different input:

audiomux[0] - tuner
audiomux[1] - radio
audiomux[2] - extern
audiomux[3] - intern
audiomux[4] - off
audiomux[5] - on
audiomux[6] - extern2

This led me to create the following:

/* ---- card 0x87 --------------------------- */
.audio_inputs   = 1,
.gpiomask       = 0x00e00007,
.audiomux       = { 0x00400005, 0, 0, 0, 0, 0 },

BtSpy works in a similar method, except that the formula for calculating the gpiodata isn't necessary. The output from BtSpy can be used directly to populate the fields in bttv-cards.c, without the need to interpret the data, as described for use with regspy, above.

GPIOs of CX2388x

To program gpio for card definitions inside cx88-cards.c , follow the directions above for using RegSpy with bt8xx cards but you'll want to consider a different set of values, namely MO_GPx_IO (x=0 to 3). The relevant part of RegSpy's output will look basically like this:

MO_GP0_IO:     000000ff   (00000000 00000000 00000000 11111111)
MO_GP1_IO:     0000f35d   (00000000 00000000 11110011 01011101)
MO_GP2_IO:     00000001   (00000000 00000000 00000000 00000001)
MO_GP3_IO:     00000000   (00000000 00000000 00000000 00000000)

Ignoring the binary values in parenthesis, find the entry in cx88-cards.c for the card you want to edit, and copy the hex values just to the left of them over to the appropriate fields for the mode you want to change.

In the case of an analog TV tuner, the result of your changes should look something like this:

.type   = CX88_VMUX_TELEVISION,
.vmux   = 0,
.gpio0  = 0x000000ff,
.gpio1  = 0x0000f35d,
.gpio2  = 0x00000000,
.gpio3  = 0x00000000,

As with all cards, some GPIO pins may be defined as inputs, from the CX2388x's viewpoint. Those GPIO values can just be replaced with all 0's. For the example above, the relevant card defines .gpio2 as input, so we ignored the value RegSpy returned for MO_GP2_IO.

GPIO for Remotes Controllers

Sometimes the remote is handled via GPIO. It works according to the following scheme:

There are data bits and signal bits. Signal bits show whether a key is pressed or released; data bits show the key code. Signal bits can be of two types:

  • The first type is 1 when the key is released and 0 when the key is pressed
  • The second type is 0 when the key is released and 1 when the key is pressed

The mask_keycode should contain only data bits.
The mask_keyup should contain signal bits of first type.
The mask_keydown should contain signal bits of second type.

A good test is that all these masks should not intersect. See also Remote_controllers-V4L

External Links