Documentation/arm/samsung-s3c24xx/gpio.rst

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