lkml.org 
[lkml]   [2011]   [Jul]   [8]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
    Patch in this message
    /
    From
    Subject[RFC PATCH v2 4/4] Core devices: documentation
    Date
    Add the documentation file for core devices.

    Signed-off-by: Marc Zyngier <marc.zyngier@arm.com>
    ---
    Documentation/core_devices.txt | 247 ++++++++++++++++++++++++++++++++++++++++
    1 files changed, 247 insertions(+), 0 deletions(-)
    create mode 100644 Documentation/core_devices.txt

    diff --git a/Documentation/core_devices.txt b/Documentation/core_devices.txt
    new file mode 100644
    index 0000000..5d1581f
    --- /dev/null
    +++ b/Documentation/core_devices.txt
    @@ -0,0 +1,247 @@
    +Core Device Subsystem:
    +=====================
    +
    +There is a small number of devices that the core kernel needs very
    +early in the boot process, namely an interrupt controller and a timer,
    +long before the driver model is up and running.
    +
    +Most architectures implement this requirement by hardcoding the
    +initialisation of a "well known" piece of hardware which is standard
    +enough to work on any platform.
    +
    +This is very different on the ARM architecture, where platforms have a
    +variety of interrupt controllers and timers. While the same hardcoding
    +is possible (and is actually used), it makes it almost impossible to
    +support several platforms in the same kernel.
    +
    +Though the device tree is helping greatly to solve this problem, some
    +platform won't ever be converted to DT, hence the need to have a
    +mechanism supporting a variety of information source. Early platform
    +devices having been deemed unsuitable (complexity, abuse of various
    +subsystems), this subsystem has been designed to provide the very
    +minimal level of functionality.
    +
    +The "core device subsystem" offers a class based device/driver
    +matching model, doesn't rely on any other subsystem, is very (too?)
    +simple, and support getting information both from DT as well as from
    +static data provided by the platform. It also gives the opportunity to
    +define the probing order by offering a sorting hook at run-time.
    +
    +As for the Linux driver model, the core device subsystem deals mainly
    +with device and driver objects. It also has the notion of "class" to
    +designate a group of devices implementing the same functionality, and
    +a group of drivers to be matched against the above devices
    +(CORE_DEV_CLASS_TIMER for example).
    +
    +One of the features is that the whole subsystem is discarded once the
    +kernel has booted. No structures can or should be retained after the
    +device has been probed. Of course, no support for module or other
    +evolved features. Another design feature is that it is *NOT* thread
    +safe. If you need any kind of mutual exclusion, you're probably using
    +core devices for something they are not designed for.
    +
    +* Core Device:
    + ===========
    +
    +The struct core_device is fairly similar to a platform_device.
    +From "include/linux/core_device.h":
    +
    +struct core_device {
    + const char *name;
    + u32 num_resources;
    + struct resource *resource;
    + struct device_node *of_node;
    + struct list_head entry;
    +};
    +
    +- name: friendly name for the device, will be used to match the driver
    +- num_resources: number of resources associated with the device
    +- resource: address of the resource array
    +- of_node: pointer to the DT node if the device has been populated by
    + parsing the device tree. This is managed internally by the subsystem.
    +- entry: internal management list (not to be initialised).
    +
    +The device is registered with the core device subsystem with:
    +void core_device_register(enum core_device_class class,
    + struct core_device *dev);
    +
    +where:
    +- class is one of CORE_DEV_CLASS_IRQ or CORE_DEV_CLASS_TIMER
    +- dev is the core device to be registered.
    +
    +A typical use is the following:
    +static struct resources twd_resources[] __initdata = {
    + {
    + .start = 0x1f000600,
    + .end = 0x1f0006ff,
    + .flags = IORESOURCE_MEM,
    + },
    + {
    + .start = IRQ_LOCALTIMER,
    + .end = IRQ_LOCALTIMER,
    + .flags = IORESOURCE_IRQ,
    + },
    +};
    +
    +static struct core_device twd_device _initdata = {
    + .name = "arm_smp_twd",
    + .resource = twd_resources,
    + .num_resources = ARRAY_SIZE(twd_resources),
    +};
    +
    +static void __init timer_init(void)
    +{
    + core_device_register(CORE_DEV_CLASS_TIMER, &twd_device);
    +}
    +
    +Note that all structures are marked as __inidata, as none of them is
    +expected to be used after the kernel has booted.
    +
    +The devices can also be automatically allocated and registered by
    +parsing the device tree (if available) with the following function:
    +
    +void of_core_device_populate(enum core_device_class class,
    + struct of_device_id *matches);
    +
    +The allocated core_device structures will have their of_node member
    +pointing to the corresponding DT node. Resources will be allocated and
    +populated according to attributes found in the device tree.
    +
    +
    +
    +* Core driver:
    + ===========
    +
    +The struct core_driver is the pendant to the core_device.
    +
    +struct core_driver {
    + int (*init)(struct core_device *);
    + struct core_device_id *ids;
    +};
    +
    +- init: initialisation function. Returns 0 on success, error code on
    + failure.
    +- ids: a null-terminated array of struct core_device_id against which
    + the device is matched.
    +
    +struct core_device_id {
    + const char *name;
    +};
    +
    +- name: string against which the device is matched
    +
    +core_driver_register(class, driver);
    +
    +Note that core_driver_register() is *not* a function, but expands to a
    +static data structure stored in a discardable section.
    +
    +A typical use is the following:
    +
    +static int __init twd_core_init(struct core_device *dev)
    +{
    + [...]
    + return 0;
    +}
    +static struct core_device_id twd_core_ids[] __initdata = {
    + { .name = "arm,smp-twd", },
    + { .name = "arm_smp_twd", },
    + {},
    +};
    +
    +static struct core_driver twd_core_driver __initdata = {
    + .init = twd_core_init,
    + .ids = twd_core_ids,
    +};
    +
    +core_driver_register(CORE_DEV_CLASS_TIMER, twd_core_driver);
    +
    +As for the core_device, all structures should be marked __initdata,
    +and the init function should be marked __init. The driver code must
    +*not* hold any reference to the core_device, as it can be freed just
    +after the init function has returned.
    +
    +
    +
    +* Device/Driver matching:
    + ======================
    +
    +The core kernel code directly controls when devices and drivers are
    +matched (no matching-at-register-time) by calling:
    +
    +void core_driver_init_class(enum core_device_class class,
    + void (*sort)(struct list_head *));
    +
    +Where:
    +- class is one of CORE_DEV_CLASS_IRQ or CORE_DEV_CLASS_TIMER,
    +- sort is a pointer to a function sorting the device list before they
    + are matched (NULL if unused).
    +
    +When this function is called:
    +
    +- All devices registered in "class" are probed with the matching
    + registered drivers
    +- Once the devices in the class have been tried against the compiled
    + in drivers, they are removed from the list (whether they have
    + actually been probed or not).
    +- If core devices have been dynamically allocated (by
    + of_core_device_populate()), they are freed.
    +
    +For example:
    +
    +/* List of supported timers */
    +static struct of_device_id timer_ids[] __initdata = {
    + { .compatible = "arm,smp-twd", },
    + {},
    +};
    +
    +static void __init __arm_late_time_init(void)
    +{
    + if (arm_late_time_init)
    + arm_late_time_init();
    +
    + /* Fetch the supported timers from the device tree */
    + of_core_device_populate(CORE_DEV_CLASS_TIMER, timer_ids);
    + /* Init the devices (both DT based and static), no preliminary sort */
    + core_driver_init_class(CORE_DEV_CLASS_TIMER, NULL);
    +}
    +
    +
    +
    +* Sorting functions
    + =================
    +
    +This may well fall into the hack category, and is probably only useful
    +when used with the device tree.
    +
    +Imagine you have a bunch of interrupt controllers to initialise. There
    +is probably one controller directly attached to the CPUs, and all the
    +others cascading (in)directly into the first one. There is a strong
    +requirement that these controllers are initialised in the right order
    +(closest to the CPU first).
    +
    +This is easy enough to achieve when static core devices are registered
    +(the registration order is preserved when probing), but is very
    +unlikely to occur when devices are imported from the device tree.
    +
    +The "sort" function that can be passed to core_driver_init_class() is
    +used to solve such a problem. It is called just before the devices are
    +matched against the drivers, and is allowed to reorganise the list
    +completely. It must not drop elements from the list though.
    +
    +One such sorting function is core_device_irq_sort(), which is designed
    +to solve the above problem, and is used like this:
    +
    +static struct of_device_id of_irq_controller_ids[] __initdata = {
    + { .compatible = "arm,gic-spi", },
    + {},
    +};
    +
    +void __init init_IRQ(void)
    +{
    + machine_desc->init_irq();
    + of_core_device_populate(CORE_DEV_CLASS_IRQ, of_irq_controller_ids);
    + core_driver_init_class(CORE_DEV_CLASS_IRQ, core_device_irq_sort);
    +}
    +
    +In this snippet, all the "arm,gic-spi" devices are registered, and
    +then sorted at initialisation time by core_device_irq_sort().
    --
    1.7.0.4



    \
     
     \ /
      Last update: 2011-07-08 10:57    [W:0.042 / U:59.324 seconds]
    ©2003-2016 Jasper Spaans. hosted at Digital OceanAdvertise on this site