[U-Boot] [RFC PATCH v2 5/6] fdt: add decode helper library

Simon Glass
2011-09-12T22:04:26Z

This library provides useful functions to drivers which want to use
the fdt to control their operation. Functions are provided to:

- look up and enumerate a device type (for example assigning i2c bus 0,
i2c bus 1, etc.)
- decode basic types from the fdt, like addresses and integers
- decode common information for each device class (e.g. i2c has speed,
controller address, etc.)

While this library is not strictly necessary, it serves two purposes:

1. It allows us to minimise the changes to a driver, in order to make
it work under fdt control. Less code is required, and so the barrier to
switch drivers over is lower.

2. It takes advantage of the fact that (just as with CONFIG), each device
class tends to have similar config requirements whether it be Tegra I2C
or Atmel I2C, for example. Additional config can still be provided in the
fdt, if the driver decodes it itself.

Note: We also add FDT_ERR_MISSING in this commit, to record missing
properties. This is a small change to libfdt, which can be dealt with
separately. This error is useful in the case when the correct node exists
but the properties within it do not match our expectations.

Signed-off-by: Simon Glass <sjg@chromium.org>
---
Changes in v2:
- Add example proposed decode helper library

common/Makefile | 1 +
common/fdt_decode.c | 177 ++++++++++++++++++++++++++++++++++++++++++++++++++
include/fdt_decode.h | 90 +++++++++++++++++++++++++
include/libfdt.h | 5 +-
4 files changed, 272 insertions(+), 1 deletions(-)
create mode 100644 common/fdt_decode.c
create mode 100644 include/fdt_decode.h

diff --git a/common/Makefile b/common/Makefile
index 2edbd71..760073c 100644
--- a/common/Makefile
+++ b/common/Makefile
@@ -173,6 +173,7 @@ COBJS-$(CONFIG_LYNXKDI) += lynxkdi.o
COBJS-$(CONFIG_MODEM_SUPPORT) += modem.o
COBJS-$(CONFIG_UPDATE_TFTP) += update.o
COBJS-$(CONFIG_USB_KEYBOARD) += usb_kbd.o
+COBJS-$(CONFIG_OF_CONTROL) += fdt_decode.o
endif

COBJS-y += console.o
diff --git a/common/fdt_decode.c b/common/fdt_decode.c
new file mode 100644
index 0000000..9e8cf4d
--- /dev/null
+++ b/common/fdt_decode.c
@@ -0,0 +1,177 @@
+/*
+ * Copyright (c) 2011 The Chromium OS Authors.
+ * See file CREDITS for list of people who contributed to this
+ * project.
+ *
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU General Public License as
+ * published by the Free Software Foundation; either version 2 of
+ * the License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, write to the Free Software
+ * Foundation, Inc., 59 Temple Place, Suite 330, Boston,
+ * MA 02111-1307 USA
+ */
+
+#include <common.h>
+#include <serial.h>
+#include <libfdt.h>
+#include <fdt_decode.h>
+
+/* we need a generic GPIO interface here */
+#include <asm/arch/gpio.h>
+
+/*
+ * Here are the type we know about. One day we might allow drivers to
+ * register. For now we just put them here. The COMPAT macro allows us to
+ * turn this into a sparse list later, and keeps the ID with the name.
+ */
+#define COMPAT(id, name) name
+static const char *compat_names[COMPAT_COUNT] = {
+ COMPAT(NVIDIA_TEGRA250_I2C, "nvidia,tegra250-i2c"),
+};
+
+/**
+ * Look in the FDT for an alias with the given name and return its node.
+ *
+ * @param blob FDT blob
+ * @param name alias name to look up
+ * @return node offset if found, or an error code < 0 otherwise
+ */
+static int find_alias_node(const void *blob, const char *name)
+{
+ const char *path;
+ int alias_node;
+
+ debug("find_alias_node: %s\n", name);
+ alias_node = fdt_path_offset(blob, "/aliases");
+ if (alias_node < 0)
+ return alias_node;
+ path = fdt_getprop(blob, alias_node, name, NULL);
+ if (!path)
+ return -FDT_ERR_NOTFOUND;
+ return fdt_path_offset(blob, path);
+}
+
+/**
+ * Look up an address property in a node and return it as an address.
+ * The property must hold either one address with no trailing data or
+ * one address with a length. This is only tested on 32-bit machines.
+ *
+ * @param blob FDT blob
+ * @param node node to examine
+ * @param prop_name name of property to find
+ * @return address, if found, or ADDR_T_NONE if not
+ */
+static addr_t get_addr(const void *blob, int node, const char *prop_name)
+{
+ const addr_t *cell;
+ int len;
+
+ debug("get_addr: %s\n", prop_name);
+ cell = fdt_getprop(blob, node, prop_name, &len);
+ if (cell && (len == sizeof(addr_t) || len == sizeof(addr_t) * 2))
+ return addr_to_cpu(*cell);
+ return ADDR_T_NONE;
+}
+
+/**
+ * Look up a 32-bit integer property in a node and return it. The property
+ * must have@least 4 bytes of data. The value of the first cell is
+ * returned.
+ *
+ * @param blob FDT blob
+ * @param node node to examine
+ * @param prop_name name of property to find
+ * @param default_val default value to return if the property is not found
+ * @return integer value, if found, or default_val if not
+ */
+static s32 get_int(const void *blob, int node, const char *prop_name,
+ s32 default_val)
+{
+ const s32 *cell;
+ int len;
+
+ debug("get_size: %s\n", prop_name);
+ cell = fdt_getprop(blob, node, prop_name, &len);
+ if (cell && len >= sizeof(s32))
+ return fdt32_to_cpu(cell[0]);
+ return default_val;
+}
+
+/**
+ * Checks whether a node is enabled.
+ * This looks for a 'status' property. If this exists, then returns 1 if
+ * the status is 'ok' and 0 otherwise. If there is no status property,
+ * it returns the default value.
+ *
+ * @param blob FDT blob
+ * @param node node to examine
+ * @param default_val default value to return if no 'status' property exists
+ * @return integer value 0/1, if found, or default_val if not
+ */
+static int get_is_enabled(const void *blob, int node, int default_val)
+{
+ const char *cell;
+
+ cell = fdt_getprop(blob, node, "status", NULL);
+ if (cell)
+ return 0 == strcmp(cell, "ok");
+ return default_val;
+}
+
+enum fdt_compat_id fdt_decode_lookup(const void *blob, int node)
+{
+ enum fdt_compat_id id;
+
+ /* Search our drivers */
+ for (id = COMPAT_UNKNOWN; id < COMPAT_COUNT; id++)
+ if (0 == fdt_node_check_compatible(blob, node,
+ compat_names[id]))
+ return id;
+ return COMPAT_UNKNOWN;
+}
+
+int fdt_decode_next_compatible(const void *blob, int node,
+ enum fdt_compat_id id)
+{
+ return fdt_node_offset_by_compatible(blob, node, compat_names[id]);
+}
+
+int fdt_decode_next_alias(const void *blob, const char *name,
+ enum fdt_compat_id id, int *upto)
+{
+#define MAX_STR_LEN 20
+ char str[MAX_STR_LEN + 20];
+ int node, err;
+
+ sprintf(str, "%.*s%d", MAX_STR_LEN, name, *upto);
+ (*upto)++;
+ node = find_alias_node(blob, str);
+ if (node < 0)
+ return node;
+ err = fdt_node_check_compatible(blob, node, compat_names[id]);
+ if (err < 0)
+ return err;
+ return err ? -FDT_ERR_MISSING : node;
+}
+
+int fdt_decode_i2c(const void *blob, int node, struct fdt_i2c *config)
+{
+ config->reg = (struct i2c_ctlr *)get_addr(blob, node, "reg");
+ config->pinmux = get_int(blob, node, "pinmux", 0);
+ config->speed = get_int(blob, node, "speed", 0);
+ config->periph_id = get_int(blob, node, "periph-id", -1);
+ config->enabled = get_is_enabled(blob, node, 0);
+
+ if (config->periph_id == -1)
+ return -FDT_ERR_MISSING;
+
+ return 0;
+}
diff --git a/include/fdt_decode.h b/include/fdt_decode.h
new file mode 100644
index 0000000..bdcdbba
--- /dev/null
+++ b/include/fdt_decode.h
@@ -0,0 +1,90 @@
+/*
+ * Copyright (c) 2011 The Chromium OS Authors.
+ * See file CREDITS for list of people who contributed to this
+ * project.
+ *
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU General Public License as
+ * published by the Free Software Foundation; either version 2 of
+ * the License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, write to the Free Software
+ * Foundation, Inc., 59 Temple Place, Suite 330, Boston,
+ * MA 02111-1307 USA
+ */
+
+
+/*
+ * This file contains convenience functions for decoding useful and
+ * enlightening information from FDTs. It is intended to be used by device
+ * drivers and board-specific code within U-Boot. It aims to reduce the
+ * amount of FDT munging required within U-Boot itself, so that driver code
+ * changes to support FDT are minimized.
+ */
+
+#include <ns16550.h>
+#include <asm/arch/clock.h>
+
+/* A typedef for a physical address. We should move it to a generic place */
+#ifdef CONFIG_PHYS_64BIT
+typedef u64 addr_t;
+#define ADDR_T_NONE (-1ULL)
+#define addr_to_cpu(reg) be64_to_cpu(reg)
+#else
+typedef u32 addr_t;
+#define ADDR_T_NONE (-1U)
+#define addr_to_cpu(reg) be32_to_cpu(reg)
+#endif
+
+/* Information obtained about memory from the FDT */
+struct fdt_memory {
+ addr_t start;
+ addr_t end;
+};
+
+/**
+ * Compat types that we know about and for which we might have drivers.
+ * Each is named COMPAT_ _<filename> where is the directory
+ * within drivers.
+ */
+enum fdt_compat_id {
+ COMPAT_UNKNOWN,
+ COMPAT_NVIDIA_TEGRA250_I2C, /* Tegra 250 i2c */
+
+ COMPAT_COUNT,
+};
+
+/* Information about i2c controller */
+struct fdt_i2c {
+ struct i2c_ctlr *reg; /* Address of controller registers */
+ int pinmux; /* Which pin mux setting to use */
+ u32 speed; /* Speed in KHz */
+ enum periph_id periph_id; /* Peripheral ID for clock/pinmux */
+ int enabled; /* 1 if enabled, 0 if disabled */
+};
+
+/**
+ * Returns information from the FDT about an i2c controler. This function reads
+ * out the following attributes:
+ *
+ * reg
+ * enabled
+ * pinmux
+ * speed
+ * periph-id
+ *
+ * @param blob FDT blob to use
+ * @param node Node to read from
+ * @param config structure to use to return information
+ * @returns 0 on success, -ve on error, in which case config may or may not be
+ * unchanged. If the node is present but expected data is
+ * missing then this will generally return
+ * -FDT_ERR_MISSING.
+ */
+int fdt_decode_i2c(const void *blob, int node, struct fdt_i2c *config);
diff --git a/include/libfdt.h b/include/libfdt.h
index de82ed5..1c7ac84 100644
--- a/include/libfdt.h
+++ b/include/libfdt.h
@@ -116,7 +116,10 @@
* Should never be returned, if it is, it indicates a bug in
* libfdt itself. */

-#define FDT_ERR_MAX 13
+/* Expected data is missing/incomplete while decoding a node */
+#define FDT_ERR_MISSING 14
+
+#define FDT_ERR_MAX 14

/**********************************************************************/
/* Low-level functions (you probably don't need these) */
--
1.7.3.1