dm: Add Driver cores design document
Signed-off-by: Pavel Herrmann <morpheus.ibis@gmail.com>
diff --git a/doc/driver-model/UDM-cores.txt b/doc/driver-model/UDM-cores.txt
new file mode 100644
index 0000000..4e13188
--- /dev/null
+++ b/doc/driver-model/UDM-cores.txt
@@ -0,0 +1,126 @@
+The U-Boot Driver Model Project
+===============================
+Driver cores API document
+=========================
+
+Pavel Herrmann <morpheus.ibis@gmail.com>
+
+1) Overview
+-----------
+ Driver cores will be used as a wrapper for devices of the same type, and as
+ an abstraction for device driver APIs. For each driver API (which roughly
+ correspond to device types), there will be one driver core. Each driver core
+ will implement three APIs - a driver API (which will be the same as API of
+ drivers the core wraps around), a core API (which will be implemented by all
+ cores) and a command API (core-specific API which will be exposed to
+ commands).
+
+ A) Command API
+ The command API will provide access to shared functionality for a specific
+ device, which is currently located mostly in commands. Commands will be
+ rewritten to be more lightweight by using this API. As this API will be
+ different for each core, it is out of scope of this document.
+
+ B) Driver API
+ The driver API will act as a wrapper around actual device drivers,
+ providing a single entrypoint for device access. All functions in this API
+ have an instance* argument (probably called "this" or "i"), which will be
+ examined by the core, and a correct function for the specified driver will
+ get called.
+
+ If the core gets called with a group instance pointer (as discussed in
+ design), it will automatically select the instance that is associated
+ with this core, and use it as target of the call. if the group contains
+ multiple instances of a single type, the caller must explicitly use an
+ accessor to select the correct instance.
+
+ This accessor will look like:
+ struct instance *get_instance_from_group(struct instance *group, int i)
+
+ When called with a non-group instance, it will simply return the instance.
+
+ C) Core API
+ The core API will be implemented by all cores, and will provide
+ functionality for getting driver instances from non-driver code. This API
+ will consist of following functions:
+
+ int get_count(struct instance *core);
+ struct instance* get_instance(struct instance *core, int index);
+ int init(struct instance *core);
+ int bind(struct instance *core, struct instance *dev, void *ops,
+ void *hint);
+ int unbind(struct instance *core, instance *dev);
+ int replace(struct instance *core, struct_instance *new_dev,
+ struct instance *old_dev);
+ int destroy(struct instance *core);
+ int reloc(struct instance *new_core, struct instance *old_core);
+
+ The 'hint' parameter of bind() serves for additional data a driver can
+ pass to the core, to help it create the correct internal state for this
+ instance. the replace() function will get called during instance
+ relocation, and will replace the old instance with the new one, keeping
+ the internal state untouched.
+
+
+2) Lifetime of a driver core
+----------------------------
+ Driver cores will be initialized at runtime, to limit memory footprint in
+ early-init stage, when we have to fit into ~1KB of memory. All active cores
+ will be stored in a tree structure (referenced as "Core tree") in global data,
+ which provides good tradeoff between size and access time.
+ Every core will have a number constant associated with it, which will be used
+ to find the instance in Core tree, and to refer to the core in all calls
+ working with the Core tree.
+ The Core Tree should be implemented using B-tree (or a similar structure)
+ to guarantee acceptable time overhead in all cases.
+
+ Code for working with the core (i2c in this example) follows:
+
+ core_init(CORE_I2C);
+ This will check whether we already have a i2c core, and if not it creates
+ a new instance and adds it into the Core tree. This will not be exported,
+ all code should depend on get_core_instance to init the core when
+ necessary.
+
+ get_core_instance(CORE_I2C);
+ This is an accessor into the Core tree, which will return the instance
+ of i2c core, creating it if necessary
+
+ core_bind(CORE_I2C, instance, driver_ops);
+ This will get called in bind() function of a driver, and will add the
+ instance into cores internal list of devices. If the core is not found, it
+ will get created.
+
+ driver_activate(instance *inst);
+ This call will recursively activate all devices necessary for using the
+ specified device. the code could be simplified as:
+ {
+ if (is_activated(inst))
+ return;
+ driver_activate(inst->bus);
+ get_driver(inst)->probe(inst);
+ }
+
+ The case with multiple parents will need to be handled here as well.
+ get_driver is an accessor to available drivers, which will get struct
+ driver based on a name in the instance.
+
+ i2c_write(instance *inst, ...);
+ An actual call to some method of the driver. This code will look like:
+ {
+ driver_activate(inst);
+ struct instance *core = get_core_instance(CORE_I2C);
+ device_ops = get_ops(inst);
+ device_ops->write(...);
+ }
+
+ get_ops will not be an exported function, it will be internal and specific
+ to the core, as it needs to know how are the ops stored, and what type
+ they are.
+
+ Please note that above examples represent the algorithm, not the actual code,
+ as they are missing checks for validity of return values.
+
+ core_init() function will get called the first time the core is requested,
+ either by core_link() or core_get_instance(). This way, the cores will get
+ created only when they are necessary, which will reduce our memory footprint.