linux/Documentation/arm/Samsung-S3C24XX/GPIO.txt
<<
>>
Prefs
   1                        S3C24XX GPIO Control
   2                        ====================
   3
   4Introduction
   5------------
   6
   7  The s3c2410 kernel provides an interface to configure and
   8  manipulate the state of the GPIO pins, and find out other
   9  information about them.
  10
  11  There are a number of conditions attached to the configuration
  12  of the s3c2410 GPIO system, please read the Samsung provided
  13  data-sheet/users manual to find out the complete list.
  14
  15  See Documentation/arm/Samsung/GPIO.txt for the core implementation.
  16
  17
  18GPIOLIB
  19-------
  20
  21  With the event of the GPIOLIB in drivers/gpio, support for some
  22  of the GPIO functions such as reading and writing a pin will
  23  be removed in favour of this common access method.
  24
  25  Once all the extant drivers have been converted, the functions
  26  listed below will be removed (they may be marked as __deprecated
  27  in the near future).
  28
  29  The following functions now either have a s3c_ specific variant
  30  or are merged into gpiolib. See the definitions in
  31  arch/arm/plat-samsung/include/plat/gpio-cfg.h:
  32
  33  s3c2410_gpio_setpin()         gpio_set_value() or gpio_direction_output()
  34  s3c2410_gpio_getpin()         gpio_get_value() or gpio_direction_input()
  35  s3c2410_gpio_getirq()         gpio_to_irq()
  36  s3c2410_gpio_cfgpin()         s3c_gpio_cfgpin()
  37  s3c2410_gpio_getcfg()         s3c_gpio_getcfg()
  38  s3c2410_gpio_pullup()         s3c_gpio_setpull()
  39
  40
  41GPIOLIB conversion
  42------------------
  43
  44If you need to convert your board or driver to use gpiolib from the phased
  45out s3c2410 API, then here are some notes on the process.
  46
  471) If your board is exclusively using an GPIO, say to control peripheral
  48   power, then it will require to claim the gpio with gpio_request() before
  49   it can use it.
  50
  51   It is recommended to check the return value, with at least WARN_ON()
  52   during initialisation.
  53
  542) The s3c2410_gpio_cfgpin() can be directly replaced with s3c_gpio_cfgpin()
  55   as they have the same arguments, and can either take the pin specific
  56   values, or the more generic special-function-number arguments.
  57
  583) s3c2410_gpio_pullup() changes have the problem that whilst the
  59   s3c2410_gpio_pullup(x, 1) can be easily translated to the
  60   s3c_gpio_setpull(x, S3C_GPIO_PULL_NONE), the s3c2410_gpio_pullup(x, 0)
  61   are not so easy.
  62
  63   The s3c2410_gpio_pullup(x, 0) case enables the pull-up (or in the case
  64   of some of the devices, a pull-down) and as such the new API distinguishes
  65   between the UP and DOWN case. There is currently no 'just turn on' setting
  66   which may be required if this becomes a problem.
  67
  684) s3c2410_gpio_setpin() can be replaced by gpio_set_value(), the old call
  69   does not implicitly configure the relevant gpio to output. The gpio
  70   direction should be changed before using gpio_set_value().
  71
  725) s3c2410_gpio_getpin() is replaceable by gpio_get_value() if the pin
  73   has been set to input. It is currently unknown what the behaviour is
  74   when using gpio_get_value() on an output pin (s3c2410_gpio_getpin
  75   would return the value the pin is supposed to be outputting).
  76
  776) s3c2410_gpio_getirq() should be directly replaceable with the
  78   gpio_to_irq() call.
  79
  80The s3c2410_gpio and gpio_ calls have always operated on the same gpio
  81numberspace, so there is no problem with converting the gpio numbering
  82between the calls.
  83
  84
  85Headers
  86-------
  87
  88  See arch/arm/mach-s3c2410/include/mach/regs-gpio.h for the list
  89  of GPIO pins, and the configuration values for them. This
  90  is included by using #include <mach/regs-gpio.h>
  91
  92  The GPIO management functions are defined in the hardware
  93  header arch/arm/mach-s3c2410/include/mach/hardware.h which can be
  94  included by #include <mach/hardware.h>
  95
  96  A useful amount of documentation can be found in the hardware
  97  header on how the GPIO functions (and others) work.
  98
  99  Whilst a number of these functions do make some checks on what
 100  is passed to them, for speed of use, they may not always ensure
 101  that the user supplied data to them is correct.
 102
 103
 104PIN Numbers
 105-----------
 106
 107  Each pin has an unique number associated with it in regs-gpio.h,
 108  e.g. S3C2410_GPA(0) or S3C2410_GPF(1). These defines are used to tell
 109  the GPIO functions which pin is to be used.
 110
 111  With the conversion to gpiolib, there is no longer a direct conversion
 112  from gpio pin number to register base address as in earlier kernels. This
 113  is due to the number space required for newer SoCs where the later
 114  GPIOs are not contiguous.
 115
 116
 117Configuring a pin
 118-----------------
 119
 120  The following function allows the configuration of a given pin to
 121  be changed.
 122
 123    void s3c_gpio_cfgpin(unsigned int pin, unsigned int function);
 124
 125  e.g.:
 126
 127     s3c_gpio_cfgpin(S3C2410_GPA(0), S3C_GPIO_SFN(1));
 128     s3c_gpio_cfgpin(S3C2410_GPE(8), S3C_GPIO_SFN(2));
 129
 130   which would turn GPA(0) into the lowest Address line A0, and set
 131   GPE(8) to be connected to the SDIO/MMC controller's SDDAT1 line.
 132
 133
 134Reading the current configuration
 135---------------------------------
 136
 137  The current configuration of a pin can be read by using standard
 138  gpiolib function:
 139
 140  s3c_gpio_getcfg(unsigned int pin);
 141
 142  The return value will be from the same set of values which can be
 143  passed to s3c_gpio_cfgpin().
 144
 145
 146Configuring a pull-up resistor
 147------------------------------
 148
 149  A large proportion of the GPIO pins on the S3C2410 can have weak
 150  pull-up resistors enabled. This can be configured by the following
 151  function:
 152
 153    void s3c_gpio_setpull(unsigned int pin, unsigned int to);
 154
 155  Where the to value is S3C_GPIO_PULL_NONE to set the pull-up off,
 156  and S3C_GPIO_PULL_UP to enable the specified pull-up. Any other
 157  values are currently undefined.
 158
 159
 160Getting and setting the state of a PIN
 161--------------------------------------
 162
 163  These calls are now implemented by the relevant gpiolib calls, convert
 164  your board or driver to use gpiolib.
 165
 166
 167Getting the IRQ number associated with a PIN
 168--------------------------------------------
 169
 170  A standard gpiolib function can map the given pin number to an IRQ
 171  number to pass to the IRQ system.
 172
 173   int gpio_to_irq(unsigned int pin);
 174
 175  Note, not all pins have an IRQ.
 176
 177
 178Author
 179-------
 180
 181Ben Dooks, 03 October 2004
 182Copyright 2004 Ben Dooks, Simtec Electronics
 183