[U-Boot] [PATCH 01/14] dm: Initial import of design documents

[Marek Vasut <marex@denx.de>]

Dear Stephen Warren,

> On 08/08/2012 12:37 PM, Marek Vasut wrote:
> > Dear Stephen Warren,
> > 
> >> On 08/08/2012 05:42 AM, Marek Vasut wrote:
> >>> From: Marek Vasut <marek.vasut@gmail.com>
> >>> 
> >>> This patch contains UDM-design.txt, which is document containing
> >>> general description of the driver model. The remaining files contains
> >>> descriptions of conversion process of particular subsystems.
> >>> 
> >>> diff --git a/doc/driver-model/UDM-design.txt
> >>> b/doc/driver-model/UDM-design.txt
> >>> 
> >>> +II) Driver core initialization stages
> >>> +-------------------------------------
> >>> +
> >>> +The drivers have to be initialized in two stages, since the U-Boot
> >>> bootloader +runs in two stages itself. The first stage is the one which
> >>> is executed before +the bootloader itself is relocated. The second
> >>> stage then happens after +relocation.
> >>> +
> >>> +  1) First stage
> >>> +  --------------
> >>> +
> >>> +  The first stage runs after the bootloader did very basic hardware
> >>> init. This +  means the stack pointer was configured, caches disabled
> >>> and that's about it. +  The problem with this part is the memory
> >>> management isn't running at all. To +  make things even worse, at this
> >>> point, the RAM is still likely uninitialized +  and therefore
> >>> unavailable.
> >>> +
> >>> +  2) Second stage
> >>> +  ---------------
> >>> +
> >>> +  At this stage, the bootloader has initialized RAM and is running
> >>> from it's +  final location. Dynamic memory allocations are working at
> >>> this point. Most of +  the driver initialization is executed here.
> >> 
> >> Given the above descriptions of the two stages, ...
> >> 
> >>> +III) The drivers
> >>> +----------------
> >>> +
> >>> +  1) The structure of a driver
> >>> +  ----------------------------
> >>> +
> >>> +  The driver will contain a structure located in a separate section,
> >>> which +  will allow linker to create a list of compiled-in drivers at
> >>> compile time. +  Let's call this list "driver_list".
> >>> +
> >>> +  struct driver __attribute__((section(driver_list))) {
> >>> +    /* The name of the driver */
> >>> +    char		name[STATIC_CONFIG_DRIVER_NAME_LENGTH];
> >>> +
> >>> +    /*
> >>> +     * This function should connect this driver with cores it depends
> >>> on and +     * with other drivers, likely bus drivers
> >>> +     */
> >>> +    int			(*bind)(struct instance *i);
> >> 
> >> ... the comments here should probably say which stage each function will
> >> be run at.
> > 
> > The drivers must be agnostic to where they're executed
> > 
> >>> +
> >>> +    /* This function actually initializes the hardware. */
> >>> +    int			(*probe)(struct instance *i);
> >>> +
> >>> +    /*
> >>> +     * The function of the driver called when U-Boot finished
> >>> relocation. +     * This is particularly important to eg. move pointers
> >>> to DMA buffers +     * and such from the location before relocation to
> >>> their final location. +     */
> >>> +    int			(*reloc)(struct instance *i);
> >> 
> >> The need for this function implies that some other functions (both bind
> >> and probe?) are to be called before relocation.
> > 
> > They can be called after reloc too.
> > 
> >> Isn't the pre-relocation
> >> environment rather strict
> > 
> > Yes
> 
> Maybe I'm misinterpreting the exact definition of the stages, but isn't
> the pre-relocation stage restricted by e.g. a lack of ability to access
> global data, so you have to store everything in the "gd" global data
> pointer

Correct! That's why the early allocator must only use global-data-alike space.

> or something like that? If that's not the case, perhaps
> explicitly spelling out which restrictions do/don't exist in the
> definition of the stages above would be helpful to prevent anyone else
> reading them the wrong way.

That's the case actually ... just making the information more accurate might 
help.

> >> and hence this will require a bunch of
> >> changes to driver code to initialize differently?
> > 
> > No
> 
> If what I said is above, that's certainly not true of most driver
> initialization code today, so migrating to an environment where global
> data wasn't allowed would require changes, wouldn't it?

Global data should eventually dissolve completely, yes. Drivers will definitelly 
need adjustments.

> >> Why not just
> >> initialize everything after relocation; IIRC, that's how most things are
> >> initialized now, isn't it?
> > 
> > You want eg. i2c bus running before relocation to init your DRAM
> > controller. Or serial console for debug output.
> > 
> >> Related, if you're intending to allow drivers to be loaded from e.g. the
> >> filesystem later
> > 
> > Not now, but we keep that in mind. Btw. (!) we're writing a bootloader
> > here, not an operating system.
> 
> Sure. I was surprised when you wrote about that feature, but my comment
> was triggered by your patch series explicitly mentioning loading drivers
> at run-time.

Yes, we thought about it at the early stages, but postponed it later on to start 
small.

> >> that will happen after relocation. There will then be
> >> a discrepancy between the environment where bind/probe get run for a
> >> built-in driver vs. a dynamically loaded driver.
> > 
> > Will there?
> 
> Yes. If bind/probe are called early, then they can't use certain
> features like dynamic memory allocation.

Yes they can, see the early malloc patches.

> If they're called late, then
> those features are available. Now perhaps you can decide to disallow
> their use anyway so that the code doesn't care, but that would require
> careful enforcement through either detailed code review, or perhaps
> forcing affected functions to be stored in a particular linker section
> and checking for symbol references outside that section (e.g. like
> __init in the Linux kernel).

No, we want to be able to use dynamic allocation (we even need it for the driver 
model to work at all).

Best regards,
Marek Vasut