1====================
2S3C24XX GPIO Control
3====================
4
5Introduction
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
19GPIOLIB
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
42GPIOLIB conversion
43------------------
44
45If you need to convert your board or driver to use gpiolib from the phased
46out s3c2410 API, then here are some notes on the process.
47
481) 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
552) 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
593) 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
694) 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
735) 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
786) s3c2410_gpio_getirq() should be directly replaceable with the
79   gpio_to_irq() call.
80
81The s3c2410_gpio and `gpio_` calls have always operated on the same gpio
82numberspace, so there is no problem with converting the gpio numbering
83between the calls.
84
85
86Headers
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
94PIN 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
107Configuring 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
124Reading 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
136Configuring 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
150Getting 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
157Getting 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
168Author
169-------
170
171Ben Dooks, 03 October 2004
172Copyright 2004 Ben Dooks, Simtec Electronics
173