| Message ID | 1310115250-3859-5-git-send-email-marc.zyngier@arm.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
On Fri, 8 Jul 2011 09:54:10 +0100 Marc Zyngier wrote: > 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 There are > +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 sources. > +devices having been deemed unsuitable (complexity, abuse of various > +subsystems), this subsystem has been designed to provide the very s/,/;/ > +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 supports > +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 there is no support ... > +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: > + =========== [snip] > +* Core driver: > + =========== [snip] > +* 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). > + so the sort key ordering is not defined (or is user-defined), right? > +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: [snip] --- ~Randy *** Remember to use Documentation/SubmitChecklist when testing your code ***
On Fri, Jul 08, 2011 at 09:54:10AM +0100, Marc Zyngier wrote: > 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). Ignoring the question of "which devices are actually core devices" for the moment, (which is a question that does need to be answered regardless), I don't think the 'struct core_device' abstraction, or at least the "core_device_register()" abstraction is what is needed. When doing early setup for an SoC family, I better already have a pretty darn good idea about what devices are "core devices". We *do* need a way to hook in setup code for a lot of different hardware in abstract ways, but something like a device model I think goes to far. It should be sufficient to have either implicitly or explicitly registered setup functions and a helper function (lets call it an early setup agent) that knows how to call them (which is pretty much what you've got implemented), but instead of a separate core_device_register() step, SoC code can pass a list of core devices to the setup agent directly. Or in the DT case, a match table. g. > + > +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 > >
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().
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