From patchwork Wed Aug 8 11:42:18 2012 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Marek Vasut X-Patchwork-Id: 175904 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Received: from theia.denx.de (theia.denx.de [85.214.87.163]) by ozlabs.org (Postfix) with ESMTP id 1A8322C008B for ; Wed, 8 Aug 2012 21:44:47 +1000 (EST) Received: from localhost (localhost [127.0.0.1]) by theia.denx.de (Postfix) with ESMTP id 3421C2815F; Wed, 8 Aug 2012 13:44:32 +0200 (CEST) X-Virus-Scanned: Debian amavisd-new at theia.denx.de Received: from theia.denx.de ([127.0.0.1]) by localhost (theia.denx.de [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id o-fT3j7Ar27Z; Wed, 8 Aug 2012 13:44:31 +0200 (CEST) Received: from theia.denx.de (localhost [127.0.0.1]) by theia.denx.de (Postfix) with ESMTP id 6C42228175; Wed, 8 Aug 2012 13:43:55 +0200 (CEST) Received: from localhost (localhost [127.0.0.1]) by theia.denx.de (Postfix) with ESMTP id AC4D62814B for ; Wed, 8 Aug 2012 13:43:45 +0200 (CEST) X-Virus-Scanned: Debian amavisd-new at theia.denx.de Received: from theia.denx.de ([127.0.0.1]) by localhost (theia.denx.de [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id yyEUIw+tFrQv for ; Wed, 8 Aug 2012 13:43:45 +0200 (CEST) X-policyd-weight: NOT_IN_SBL_XBL_SPAMHAUS=-1.5 NOT_IN_SPAMCOP=-1.5 NOT_IN_BL_NJABL=-1.5 (only DNSBL check requested) Received: from mail-out.m-online.net (mail-out.m-online.net [212.18.0.9]) by theia.denx.de (Postfix) with ESMTPS id 128AA2813C for ; Wed, 8 Aug 2012 13:43:39 +0200 (CEST) Received: from frontend1.mail.m-online.net (unknown [192.168.8.180]) by mail-out.m-online.net (Postfix) with ESMTP id 3WsW2K4YBfz4KKBm; Wed, 8 Aug 2012 13:43:37 +0200 (CEST) X-Auth-Info: MYYspiePzZkDx5KN/ysszrYiS/2OXg5qgq0zu76BWu8= Received: from mashiro.ms.mff.cuni.cz (unknown [195.140.253.167]) by smtp-auth.mnet-online.de (Postfix) with ESMTPA id 3WsW2K3gLBzbbjG; Wed, 8 Aug 2012 13:43:37 +0200 (CEST) From: Marek Vasut To: u-boot@lists.denx.de Date: Wed, 8 Aug 2012 13:42:18 +0200 Message-Id: <1344426150-1229-2-git-send-email-marex@denx.de> X-Mailer: git-send-email 1.7.10.4 In-Reply-To: <1344426150-1229-1-git-send-email-marex@denx.de> References: <1344426150-1229-1-git-send-email-marex@denx.de> Subject: [U-Boot] [PATCH 02/14] dm: Add Driver cores design document X-BeenThere: u-boot@lists.denx.de X-Mailman-Version: 2.1.11 Precedence: list List-Id: U-Boot discussion List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , MIME-Version: 1.0 Sender: u-boot-bounces@lists.denx.de Errors-To: u-boot-bounces@lists.denx.de From: Pavel Herrmann Signed-off-by: Pavel Herrmann --- doc/driver-model/UDM-cores.txt | 127 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 127 insertions(+) create mode 100644 doc/driver-model/UDM-cores.txt diff --git a/doc/driver-model/UDM-cores.txt b/doc/driver-model/UDM-cores.txt new file mode 100644 index 0000000..56a417c --- /dev/null +++ b/doc/driver-model/UDM-cores.txt @@ -0,0 +1,127 @@ +The U-Boot Driver Model Project +=============================== +Driver cores API document +========================= + +Pavel Herrmann + +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. +