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