Changes between Version 1 and Version 2 of FlattenedDeviceTree

Timestamp:

Oct 28, 2009, 11:10:50 AM (16 years ago)

Author:

Nicolas Pouillon

Comment:

--

FlattenedDeviceTree

@@ -11 +11 @@
 Using FDT is mainstream, andis also used by Linux  and BSD, supported is U-Boot and other bootloaders.
 
-= Implementation =
+= References =
+
+ * You may learn many things [http://www.google.com/search?q=flattened%20device%20tree googling] for "flattened device tree".
+ * The `dtc` utility used to compile `.dts` files in MutekH is mainteained at http://git.jdl.com/. You may:
+  * Browse the git there http://git.jdl.com/gitweb/
+  * Download a snapshot http://git.jdl.com/software/
+   This repository also includes some documentation and a reference library for handling FDTs.
+ * The Linux kernel documentation tree contains [http://git.kernel.org/?p=linux/kernel/git/next/linux-next.git;a=blob;f=Documentation/powerpc/booting-without-of.txt;h=79f533f38c6112d64bed9398c44d31cf3b552f6b;hb=HEAD an useful document] about device trees (`Documentation/powerpc/booting-without-of.txt`)
+
+= Implementation and example =
 
 In MutekH, FDT is handled through an hardware enumerator device driver, it behaves like the other enumerators (PCI, ISAPnP).
@@ -50 +59 @@
 
 This will make the FDT enumerator use the correct driver, matching `"soclib:tty"`
+
+= MutekH-Specific Node syntax quick reference =
+
+== Processors ==
+
+Processor nodes look like:
+{{{
+Mips,32@0 {
+        name = "Mips,32";
+        device_type = "cpu";
+        reg = <0>;
+};
+}}}
+
+ `reg`::
+   This is the CPU identification number
+ `device_type`::
+   must be `"cpu"`
+
+== Memories ==
+
+Memory nodes look like:
+{{{
+memory@0 {
+        device_type = "memory";
+        cached;
+        reg = <0x61100000 0x00100000>;
+};
+}}}
+
+ `device_type`::
+   must be "memory"
+ `reg`::
+   must be a couple of <address size> with both the values respecting `#address-cells` and `#size-cells`.
+
+There are two optional attributes:
+
+ `cached`::
+   The memory is cacheable
+ `coherent`::
+   The memory is cached and coherent (`cached` is implied, setting it is optional)
+
+== References to interrupt controllers ==
+
+Interrupts controller are referenced from one node to another in order to describe the interrupt tree. References are handled through the following properties:
+ `icudev`::
+   Must be a path to an existing ICU device, enclosing in `&{}` is syntactic
+ `irq`::
+   Is the irq number in `icudev`.
+
+== Parameter structure construction for calling `_init` functions ==
+
+Some devices require a structure containing parameters in order to correctly initialize them. This case is handled in the FDT description. Let's see the example of the `soclib:xicu` component. It needs a structure containing:
+
+{{{
+struct soclib_xicu_param_s
+{
+        size_t output_line_no;
+};
+}}}
+
+In the driver, the id definition is:
+{{{
+static const struct driver_param_binder_s xicu_param_binder[] =
+{
+        PARAM_BIND(struct soclib_xicu_param_s, output_line_no, PARAM_DATATYPE_INT),
+        { 0 }
+};
+
+static const struct devenum_ident_s     xicu_soclib_ids[] =
+{
+        DEVENUM_FDTNAME_ENTRY("soclib:xicu", sizeof(struct soclib_xicu_param_s), xicu_param_binder),
+        { 0 }
+};
+}}}
+
+This informs the FDT parser this device will need a parameter structure, with the parameters described in the `xicu_param_binder` correctly filled-in.
+
+In this table, there is one entry telling the `output_line_no` parameter is an integer.
+
+Available data types are:
+ `PARAM_DATATYPE_INT`::
+   a simple integer
+ `PARAM_DATATYPE_DEVICE_PTR`::
+   a device reference (`&{/node/path}` in the device tree source), which will be transparently translated to a `struct device_s *` before filling the structure. Device must exist in the tree.
+ `PARAM_DATATYPE_ADDR`::
+   an address, `#address-cells` will be honored
+ `PARAM_DATATYPE_BOOL`::
+   a simple boolean, i.e. a property with no value, if present it is true, if absent it is false (like the `cached` attribute in memory nodes)