Documentation/arm/Samsung-S3C24XX/GPIO.txt

   1                         S3C2410 GPIO Control
   2                         ====================
   3
   4 Introduction
   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 implemetation.
  16
  17
  18 GPIOLIB
  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
  41 GPIOLIB conversion
  42 ------------------
  43
  44 If you need to convert your board or driver to use gpiolib from the exiting
  45 s3c2410 api, then here are some notes on the process.
  46
  47 1) 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
  54 2) 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
  58 3) s3c2410_gpio_pullup() changs 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
  68 4) 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
  72 5) 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
  77 6) s3c2410_gpio_getirq() should be directly replacable with the
  78    gpio_to_irq() call.
  79
  80 The s3c2410_gpio and gpio_ calls have always operated on the same gpio
  81 numberspace, so there is no problem with converting the gpio numbering
  82 between the calls.
  83
  84
  85 Headers
  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
 104 PIN Numbers
 105 -----------
 106
 107   Each pin has an unique number associated with it in regs-gpio.h,
 108   eg 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
 117 Configuring a pin
 118 -----------------
 119
 120   The following function allows the configuration of a given pin to
 121   be changed.
 122
 123     void s3c2410_gpio_cfgpin(unsigned int pin, unsigned int function);
 124
 125   Eg:
 126
 127      s3c2410_gpio_cfgpin(S3C2410_GPA(0), S3C2410_GPA0_ADDR0);
 128      s3c2410_gpio_cfgpin(S3C2410_GPE(8), S3C2410_GPE8_SDDAT1);
 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    The s3c_gpio_cfgpin() call is a functional replacement for this call.
 134
 135
 136 Reading the current configuration
 137 ---------------------------------
 138
 139   The current configuration of a pin can be read by using:
 140
 141   s3c2410_gpio_getcfg(unsigned int pin);
 142
 143   The return value will be from the same set of values which can be
 144   passed to s3c2410_gpio_cfgpin().
 145
 146   The s3c_gpio_getcfg() call should be a functional replacement for
 147   this call.
 148
 149
 150 Configuring a pull-up resistor
 151 ------------------------------
 152
 153   A large proportion of the GPIO pins on the S3C2410 can have weak
 154   pull-up resistors enabled. This can be configured by the following
 155   function:
 156
 157     void s3c2410_gpio_pullup(unsigned int pin, unsigned int to);
 158
 159   Where the to value is zero to set the pull-up off, and 1 to enable
 160   the specified pull-up. Any other values are currently undefined.
 161
 162   The s3c_gpio_setpull() offers similar functionality, but with the
 163   ability to encode whether the pull is up or down. Currently there
 164   is no 'just on' state, so up or down must be selected.
 165
 166
 167 Getting the state of a PIN
 168 --------------------------
 169
 170   The state of a pin can be read by using the function:
 171
 172     unsigned int s3c2410_gpio_getpin(unsigned int pin);
 173
 174   This will return either zero or non-zero. Do not count on this
 175   function returning 1 if the pin is set.
 176
 177   This call is now implemented by the relevant gpiolib calls, convert
 178   your board or driver to use gpiolib.
 179
 180
 181 Setting the state of a PIN
 182 --------------------------
 183
 184   The value an pin is outputing can be modified by using the following:
 185
 186     void s3c2410_gpio_setpin(unsigned int pin, unsigned int to);
 187
 188   Which sets the given pin to the value. Use 0 to write 0, and 1 to
 189   set the output to 1.
 190
 191   This call is now implemented by the relevant gpiolib calls, convert
 192   your board or driver to use gpiolib.
 193
 194
 195 Getting the IRQ number associated with a PIN
 196 --------------------------------------------
 197
 198   The following function can map the given pin number to an IRQ
 199   number to pass to the IRQ system.
 200
 201    int s3c2410_gpio_getirq(unsigned int pin);
 202
 203   Note, not all pins have an IRQ.
 204
 205   This call is now implemented by the relevant gpiolib calls, convert
 206   your board or driver to use gpiolib.
 207
 208
 209 Authour
 210 -------
 211
 212
 213 Ben Dooks, 03 October 2004
 214 Copyright 2004 Ben Dooks, Simtec Electronics