Merge branch 'master' of git://git.denx.de/u-boot-mpc85xx
[platform/kernel/u-boot.git] / include / fdtdec.h
1 /*
2  * Copyright (c) 2011 The Chromium OS Authors.
3  * See file CREDITS for list of people who contributed to this
4  * project.
5  *
6  * This program is free software; you can redistribute it and/or
7  * modify it under the terms of the GNU General Public License as
8  * published by the Free Software Foundation; either version 2 of
9  * the License, or (at your option) any later version.
10  *
11  * This program is distributed in the hope that it will be useful,
12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
14  * GNU General Public License for more details.
15  *
16  * You should have received a copy of the GNU General Public License
17  * along with this program; if not, write to the Free Software
18  * Foundation, Inc., 59 Temple Place, Suite 330, Boston,
19  * MA 02111-1307 USA
20  */
21
22 #ifndef __fdtdec_h
23 #define __fdtdec_h
24
25 /*
26  * This file contains convenience functions for decoding useful and
27  * enlightening information from FDTs. It is intended to be used by device
28  * drivers and board-specific code within U-Boot. It aims to reduce the
29  * amount of FDT munging required within U-Boot itself, so that driver code
30  * changes to support FDT are minimized.
31  */
32
33 #include <libfdt.h>
34
35 /*
36  * A typedef for a physical address. Note that fdt data is always big
37  * endian even on a litle endian machine.
38  */
39 #ifdef CONFIG_PHYS_64BIT
40 typedef u64 fdt_addr_t;
41 #define FDT_ADDR_T_NONE (-1ULL)
42 #define fdt_addr_to_cpu(reg) be64_to_cpu(reg)
43 #else
44 typedef u32 fdt_addr_t;
45 #define FDT_ADDR_T_NONE (-1U)
46 #define fdt_addr_to_cpu(reg) be32_to_cpu(reg)
47 #endif
48
49 /* Information obtained about memory from the FDT */
50 struct fdt_memory {
51         fdt_addr_t start;
52         fdt_addr_t end;
53 };
54
55 /**
56  * Compat types that we know about and for which we might have drivers.
57  * Each is named COMPAT_<dir>_<filename> where <dir> is the directory
58  * within drivers.
59  */
60 enum fdt_compat_id {
61         COMPAT_UNKNOWN,
62         COMPAT_NVIDIA_TEGRA20_USB,      /* Tegra20 USB port */
63         COMPAT_NVIDIA_TEGRA20_I2C,      /* Tegra20 i2c */
64         COMPAT_NVIDIA_TEGRA20_DVC,      /* Tegra20 dvc (really just i2c) */
65         COMPAT_NVIDIA_TEGRA20_EMC,      /* Tegra20 memory controller */
66         COMPAT_NVIDIA_TEGRA20_EMC_TABLE, /* Tegra20 memory timing table */
67         COMPAT_NVIDIA_TEGRA20_KBC,      /* Tegra20 Keyboard */
68         COMPAT_NVIDIA_TEGRA20_NAND,     /* Tegra2 NAND controller */
69
70         COMPAT_COUNT,
71 };
72
73 /* GPIOs are numbered from 0 */
74 enum {
75         FDT_GPIO_NONE = -1U,    /* an invalid GPIO used to end our list */
76
77         FDT_GPIO_ACTIVE_LOW = 1 << 0,   /* input is active low (else high) */
78 };
79
80 /* This is the state of a GPIO pin as defined by the fdt */
81 struct fdt_gpio_state {
82         const char *name;       /* name of the fdt property defining this */
83         uint gpio;              /* GPIO number, or FDT_GPIO_NONE if none */
84         u8 flags;               /* FDT_GPIO_... flags */
85 };
86
87 /* This tells us whether a fdt_gpio_state record is valid or not */
88 #define fdt_gpio_isvalid(x) ((x)->gpio != FDT_GPIO_NONE)
89
90 /**
91  * Find the next numbered alias for a peripheral. This is used to enumerate
92  * all the peripherals of a certain type.
93  *
94  * Do the first call with *upto = 0. Assuming /aliases/<name>0 exists then
95  * this function will return a pointer to the node the alias points to, and
96  * then update *upto to 1. Next time you call this function, the next node
97  * will be returned.
98  *
99  * All nodes returned will match the compatible ID, as it is assumed that
100  * all peripherals use the same driver.
101  *
102  * @param blob          FDT blob to use
103  * @param name          Root name of alias to search for
104  * @param id            Compatible ID to look for
105  * @return offset of next compatible node, or -FDT_ERR_NOTFOUND if no more
106  */
107 int fdtdec_next_alias(const void *blob, const char *name,
108                 enum fdt_compat_id id, int *upto);
109
110 /**
111  * Find the next compatible node for a peripheral.
112  *
113  * Do the first call with node = 0. This function will return a pointer to
114  * the next compatible node. Next time you call this function, pass the
115  * value returned, and the next node will be provided.
116  *
117  * @param blob          FDT blob to use
118  * @param node          Start node for search
119  * @param id            Compatible ID to look for (enum fdt_compat_id)
120  * @return offset of next compatible node, or -FDT_ERR_NOTFOUND if no more
121  */
122 int fdtdec_next_compatible(const void *blob, int node,
123                 enum fdt_compat_id id);
124
125 /**
126  * Find the next compatible subnode for a peripheral.
127  *
128  * Do the first call with node set to the parent and depth = 0. This
129  * function will return the offset of the next compatible node. Next time
130  * you call this function, pass the node value returned last time, with
131  * depth unchanged, and the next node will be provided.
132  *
133  * @param blob          FDT blob to use
134  * @param node          Start node for search
135  * @param id            Compatible ID to look for (enum fdt_compat_id)
136  * @param depthp        Current depth (set to 0 before first call)
137  * @return offset of next compatible node, or -FDT_ERR_NOTFOUND if no more
138  */
139 int fdtdec_next_compatible_subnode(const void *blob, int node,
140                 enum fdt_compat_id id, int *depthp);
141
142 /**
143  * Look up an address property in a node and return it as an address.
144  * The property must hold either one address with no trailing data or
145  * one address with a length. This is only tested on 32-bit machines.
146  *
147  * @param blob  FDT blob
148  * @param node  node to examine
149  * @param prop_name     name of property to find
150  * @return address, if found, or FDT_ADDR_T_NONE if not
151  */
152 fdt_addr_t fdtdec_get_addr(const void *blob, int node,
153                 const char *prop_name);
154
155 /**
156  * Look up a 32-bit integer property in a node and return it. The property
157  * must have at least 4 bytes of data. The value of the first cell is
158  * returned.
159  *
160  * @param blob  FDT blob
161  * @param node  node to examine
162  * @param prop_name     name of property to find
163  * @param default_val   default value to return if the property is not found
164  * @return integer value, if found, or default_val if not
165  */
166 s32 fdtdec_get_int(const void *blob, int node, const char *prop_name,
167                 s32 default_val);
168
169 /**
170  * Checks whether a node is enabled.
171  * This looks for a 'status' property. If this exists, then returns 1 if
172  * the status is 'ok' and 0 otherwise. If there is no status property,
173  * it returns 1 on the assumption that anything mentioned should be enabled
174  * by default.
175  *
176  * @param blob  FDT blob
177  * @param node  node to examine
178  * @return integer value 0 (not enabled) or 1 (enabled)
179  */
180 int fdtdec_get_is_enabled(const void *blob, int node);
181
182 /**
183  * Make sure we have a valid fdt available to control U-Boot.
184  *
185  * If not, a message is printed to the console if the console is ready.
186  *
187  * @return 0 if all ok, -1 if not
188  */
189 int fdtdec_prepare_fdt(void);
190
191 /**
192  * Checks that we have a valid fdt available to control U-Boot.
193
194  * However, if not then for the moment nothing is done, since this function
195  * is called too early to panic().
196  *
197  * @returns 0
198  */
199 int fdtdec_check_fdt(void);
200
201 /**
202  * Find the nodes for a peripheral and return a list of them in the correct
203  * order. This is used to enumerate all the peripherals of a certain type.
204  *
205  * To use this, optionally set up a /aliases node with alias properties for
206  * a peripheral. For example, for usb you could have:
207  *
208  * aliases {
209  *              usb0 = "/ehci@c5008000";
210  *              usb1 = "/ehci@c5000000";
211  * };
212  *
213  * Pass "usb" as the name to this function and will return a list of two
214  * nodes offsets: /ehci@c5008000 and ehci@c5000000.
215  *
216  * All nodes returned will match the compatible ID, as it is assumed that
217  * all peripherals use the same driver.
218  *
219  * If no alias node is found, then the node list will be returned in the
220  * order found in the fdt. If the aliases mention a node which doesn't
221  * exist, then this will be ignored. If nodes are found with no aliases,
222  * they will be added in any order.
223  *
224  * If there is a gap in the aliases, then this function return a 0 node at
225  * that position. The return value will also count these gaps.
226  *
227  * This function checks node properties and will not return nodes which are
228  * marked disabled (status = "disabled").
229  *
230  * @param blob          FDT blob to use
231  * @param name          Root name of alias to search for
232  * @param id            Compatible ID to look for
233  * @param node_list     Place to put list of found nodes
234  * @param maxcount      Maximum number of nodes to find
235  * @return number of nodes found on success, FTD_ERR_... on error
236  */
237 int fdtdec_find_aliases_for_id(const void *blob, const char *name,
238                         enum fdt_compat_id id, int *node_list, int maxcount);
239
240 /*
241  * This function is similar to fdtdec_find_aliases_for_id() except that it
242  * adds to the node_list that is passed in. Any 0 elements are considered
243  * available for allocation - others are considered already used and are
244  * skipped.
245  *
246  * You can use this by calling fdtdec_find_aliases_for_id() with an
247  * uninitialised array, then setting the elements that are returned to -1,
248  * say, then calling this function, perhaps with a different compat id.
249  * Any elements you get back that are >0 are new nodes added by the call
250  * to this function.
251  *
252  * Note that if you have some nodes with aliases and some without, you are
253  * sailing close to the wind. The call to fdtdec_find_aliases_for_id() with
254  * one compat_id may fill in positions for which you have aliases defined
255  * for another compat_id. When you later call *this* function with the second
256  * compat_id, the alias positions may already be used. A debug warning may
257  * be generated in this case, but it is safest to define aliases for all
258  * nodes when you care about the ordering.
259  */
260 int fdtdec_add_aliases_for_id(const void *blob, const char *name,
261                         enum fdt_compat_id id, int *node_list, int maxcount);
262
263 /*
264  * Get the name for a compatible ID
265  *
266  * @param id            Compatible ID to look for
267  * @return compatible string for that id
268  */
269 const char *fdtdec_get_compatible(enum fdt_compat_id id);
270
271 /* Look up a phandle and follow it to its node. Then return the offset
272  * of that node.
273  *
274  * @param blob          FDT blob
275  * @param node          node to examine
276  * @param prop_name     name of property to find
277  * @return node offset if found, -ve error code on error
278  */
279 int fdtdec_lookup_phandle(const void *blob, int node, const char *prop_name);
280
281 /**
282  * Look up a property in a node and return its contents in an integer
283  * array of given length. The property must have at least enough data for
284  * the array (4*count bytes). It may have more, but this will be ignored.
285  *
286  * @param blob          FDT blob
287  * @param node          node to examine
288  * @param prop_name     name of property to find
289  * @param array         array to fill with data
290  * @param count         number of array elements
291  * @return 0 if ok, or -FDT_ERR_NOTFOUND if the property is not found,
292  *              or -FDT_ERR_BADLAYOUT if not enough data
293  */
294 int fdtdec_get_int_array(const void *blob, int node, const char *prop_name,
295                 u32 *array, int count);
296
297 /**
298  * Look up a property in a node and return a pointer to its contents as a
299  * unsigned int array of given length. The property must have at least enough
300  * data for the array ('count' cells). It may have more, but this will be
301  * ignored. The data is not copied.
302  *
303  * Note that you must access elements of the array with fdt32_to_cpu(),
304  * since the elements will be big endian even on a little endian machine.
305  *
306  * @param blob          FDT blob
307  * @param node          node to examine
308  * @param prop_name     name of property to find
309  * @param count         number of array elements
310  * @return pointer to array if found, or NULL if the property is not
311  *              found or there is not enough data
312  */
313 const u32 *fdtdec_locate_array(const void *blob, int node,
314                                const char *prop_name, int count);
315
316 /**
317  * Look up a boolean property in a node and return it.
318  *
319  * A boolean properly is true if present in the device tree and false if not
320  * present, regardless of its value.
321  *
322  * @param blob  FDT blob
323  * @param node  node to examine
324  * @param prop_name     name of property to find
325  * @return 1 if the properly is present; 0 if it isn't present
326  */
327 int fdtdec_get_bool(const void *blob, int node, const char *prop_name);
328
329 /**
330  * Decode a single GPIOs from an FDT.
331  *
332  * If the property is not found, then the GPIO structure will still be
333  * initialised, with gpio set to FDT_GPIO_NONE. This makes it easy to
334  * provide optional GPIOs.
335  *
336  * @param blob          FDT blob to use
337  * @param node          Node to look at
338  * @param prop_name     Node property name
339  * @param gpio          gpio elements to fill from FDT
340  * @return 0 if ok, -FDT_ERR_NOTFOUND if the property is missing.
341  */
342 int fdtdec_decode_gpio(const void *blob, int node, const char *prop_name,
343                 struct fdt_gpio_state *gpio);
344
345 /**
346  * Set up a GPIO pin according to the provided gpio information. At present this
347  * just requests the GPIO.
348  *
349  * If the gpio is FDT_GPIO_NONE, no action is taken. This makes it easy to
350  * deal with optional GPIOs.
351  *
352  * @param gpio          GPIO info to use for set up
353  * @return 0 if all ok or gpio was FDT_GPIO_NONE; -1 on error
354  */
355 int fdtdec_setup_gpio(struct fdt_gpio_state *gpio);
356
357 /*
358  * Look up a property in a node and return its contents in a byte
359  * array of given length. The property must have at least enough data for
360  * the array (count bytes). It may have more, but this will be ignored.
361  *
362  * @param blob          FDT blob
363  * @param node          node to examine
364  * @param prop_name     name of property to find
365  * @param array         array to fill with data
366  * @param count         number of array elements
367  * @return 0 if ok, or -FDT_ERR_MISSING if the property is not found,
368  *              or -FDT_ERR_BADLAYOUT if not enough data
369  */
370 int fdtdec_get_byte_array(const void *blob, int node, const char *prop_name,
371                 u8 *array, int count);
372
373 /**
374  * Look up a property in a node and return a pointer to its contents as a
375  * byte array of given length. The property must have at least enough data
376  * for the array (count bytes). It may have more, but this will be ignored.
377  * The data is not copied.
378  *
379  * @param blob          FDT blob
380  * @param node          node to examine
381  * @param prop_name     name of property to find
382  * @param count         number of array elements
383  * @return pointer to byte array if found, or NULL if the property is not
384  *              found or there is not enough data
385  */
386 const u8 *fdtdec_locate_byte_array(const void *blob, int node,
387                              const char *prop_name, int count);
388 #endif