Porting a driver to powerpc using FDT

[Grant Likely]

Hi Chris, thanks for the write up.  Some comments below, and I'm also
in the process of writing better documentation for all of this.  You
can find it here:

http://devicetree.org/Device_Tree_Usage

That page describes how the device tree is structured.  I'm about to
start another page on how Linux uses the device tree.  That page
should cover the same topics that you describe below.

On Thu, Jun 17, 2010 at 5:11 AM, Chris Alfred <c.alfred at internode.on.net> wrote:
>> virtual-devices {
>>         compatible = "simple-bus";
>>         dsa {
>>               compatible = "<vendor>,jkc5200n8-dsa";
>>         };
>> };
>
> Ok, after correcting the names, the basic OF driver is probed.
>
> Now to try and use probe to register the DSA platform driver with the
> OF driver as its parent.
>
>
> =======
>
> For those interested in how to get a very basic OF (uses FDT) driver
> going, the steps I did are below.
>
> 'myvendor' is your company name, and 'mydevice' is the name of the
> device - use better names in real code.
>
> (1) The .dts file - this is the Flattened Device Tree (FDT)
> descriptor:
>
>    / {
>        ...
>
>         virtual-device {
>          compatible = "simple-bus";
>          mydevice0 {
>           compatible = "myvendor,mydevice";
>          };
>         };
>
>        ...
>    };
>
>    For my board "simple-bus" is an already defined bus in the .dts.
> In my case the .dts had:

This comment raised warning flags for me.  Can you post your new
current device tree?  It sounds like you put your DSA device into the
localbus node.  You shouldn't need to do that.  Many nodes in a single
tree can claim compatibility with "simple-bus".

>
>    / {
>        ...
>
>        localbus {
>          compatible =
> "fsl,mpc5200b-lpb","fsl,mpc5200-lpb","simple-bus";
>
>          ...
>         };
>
>        ...
>    };
>
> (2) Create the OF driver:
>
>    #include <linux/of.h>
>    #include <linux/kernel.h>
>    #include <linux/of_platform.h>
>
>    static int __devinit mydevice_probe(struct of_device *ofdev, const
> struct of_device_id *match)
>    {
>     printk("mydevice_probe\n");
>     return 0;
>    }
>
>    static int mydevice_remove(struct of_device *ofdev)

__devexit

>    {
>     printk("mydevice_remove\n");
>     return 0;
>    }
>
>
>    static const struct of_device_id mydevice_match[] = {
>     {
>      .compatible = "myvendor,mydevice",
>     },
>     {}
>    };
>
>    static struct of_platform_driver mydevice_driver = {
>     .name = "mydevice-driver",
>     .match_table = mydevice_match,
>     .probe = mydevice_probe,
>     .remove = mydevice_remove,
>    };

.remove = __devexit_P(mydevice_remove),

>
>    static int __init mydevice_driver_init(void)
>    {
>     printk("mydevice_drver_init\n");
>
>     if (of_register_platform_driver(&mydevice_driver))
>      printk(KERN_ERR "Unable to register platform driver\n");
>
>     return 0;
>    }
>    module_init(mydevice_driver_init);

Should actually be:
    static int __init mydevice_driver_init(void)
    {
     printk("mydevice_drver_init\n");
     return of_register_platform_driver(&mydevice_driver);
    }
    module_init(mydevice_driver_init);

The driver core will report an error if registration fails.

>
>    static void __exit mydevice_driver_cleanup(void)
>    {
>     printk("mydevice_driver_cleanup\n");
>
>     of_unregister_platform_driver(&mydevice_driver);
>    }
>    module_exit(mydevice_driver_cleanup);
>
>    MODULE_DESCRIPTION("mydevice driver");
>    MODULE_AUTHOR("name <email>");
>    MODULE_LICENSE("GPL v2");
>    MODULE_ALIAS("platform:mydevice-driver");
>
> (3) Change the appropriate Makefile and Kconfig to compile the OF
> driver.
>
> During kernel boot you should see the lines:
>
>    mydevice_driver_init
>    mydevice_probe
>
> If not, you probably have one of the strings (text in " ") incorrect.
>
> In /sys/bus/of_platform/drivers, you should have a directory named
> 'mydevice-driver'.
>
> In /sys/bus/of_platform/drivers/mydevice-driver you should have a
> directory named 'mydevice0.1'. The name 'mydevice0' comes from the
> .dts above.

which will be a symlink to the actual device location in the internal
Linux device hierarchy.

>
> ==========
>
> Brief explaination of how I think this is all tied together:
>
> (1) The Flattened Device Tree is included with the compiled kernel
> image.

Generally not.  Usually the device tree is passed in via u-boot.
There is a form (cuImage) that links the dtb into the kernel, but that
is not recommended, and is only used for supporting old version of
u-boot that cannot pass the dtb at boot.

> (2) The module_init(...) macro is like declaring a 'main' for drivers.
> The kernel calls all of the functions declared in the module_init(...)
> macros during startup.

yes.

> (3) When a device driver is registered via
> of_register_platform_driver(), this invokes a scan of the FDT to find
> matches with strings in the .match_table. If a match is found, the
> .probe is called for the created device instance.

Not quite.  Registering drivers does not cause a scan of the DT.
Instead, it looks in the list of registered devices to see if there is
anything to bind against.  The devices are actually registered at boot
time in the function of_platform_bus_probe() which on the mpc5200 is
called by the function mpc52xx_declare_of_platform_devices().

Drivers won't bind against anything that isn't already registered as a
device in the Linux device model.

Cheers,
g.