From patchwork Thu Nov 30 17:41:48 2017 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Srinivas Kandagatla X-Patchwork-Id: 120264 Delivered-To: patch@linaro.org Received: by 10.140.22.227 with SMTP id 90csp90006qgn; Thu, 30 Nov 2017 09:46:14 -0800 (PST) X-Google-Smtp-Source: AGs4zMZ9fq03TLyWt0ftgCDsdVyTumFCO/p08uby1ej416rLtdnQ7wH3/tQkH2jkm4iMh0dVfqnU X-Received: by 10.28.104.6 with SMTP id d6mr1167612wmc.101.1512063974725; Thu, 30 Nov 2017 09:46:14 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1512063974; cv=none; d=google.com; s=arc-20160816; b=LmgAOa0YFOwOm/cuui8LO2b7+WC7YlppG+Pol2nZlXgTodU5zrrQsa1lWMpuu8Sg4K cSTnkWxYYL/1KbUNs+nK4PeREqhaMfQMg+3eVP2pskG8s6vZz4QIEZ9JfC8leRHa4ycG Ls+eQ+DG83K9DphEIPHKj4z3BIcxddlYBzkcjguTBaj1mfe6qsAe9ZG335l/FfiPd15Z OAdT00I8WmuID/zehfGuW5uJx1Yf/6bOf4ktJbYa8LaLFSn47PXPNXMAGW5UDjsFZSvM GcwBqmmIGwdy78xT9+4iFYolalQofAegmMcwVs/2jbR5grPn0qYFiRLJnXngrOFI0KtJ +0QA== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=sender:errors-to:content-transfer-encoding:mime-version :list-subscribe:list-help:list-post:list-archive:list-unsubscribe :list-id:precedence:subject:cc:references:in-reply-to:message-id :date:to:from:dkim-signature:delivered-to:arc-authentication-results; bh=0uGUoca/QTf7OP5/1esLd0CVAk4jslHGEHlJOQl4Y+w=; b=K+vm5t2EiulucwHzlFcqM0LBIqbmOZblgRcaV40f4gFk95BqqwW4Dd99bcez3keD+/ k7L5DCYx30BoWmsI3AUKIS+K6/LVF82rPTvriZRMJ4K84JK5iTmTi/O/UkKloIhcRIs3 FxKfxYYApmpea9ytmJLtdYlu7boWf1UMwe2vfNZmlwD9aE+mqYwgzbMY19jXN9F79M8l A3vJDpii2UeAvQz1FUy/P4VCPctJ5QQfb4qWHqDEbrluBCrWB+ddhbzAY7qKN9q105p+ iTjcFpLSEXwKBiUVBVzzAnnsA3ByX8MTHX0RF86ju09kbQ/lQLrujjNX9wHCqC63EVgm EFag== ARC-Authentication-Results: i=1; mx.google.com; dkim=neutral (body hash did not verify) header.i=@linaro.org header.s=google header.b=C+EwUO5m; spf=pass (google.com: domain of alsa-devel-bounces@alsa-project.org designates 77.48.224.243 as permitted sender) smtp.mailfrom=alsa-devel-bounces@alsa-project.org; dmarc=fail (p=NONE sp=NONE dis=NONE) header.from=linaro.org Return-Path: Received: from alsa0.perex.cz (alsa0.perex.cz. [77.48.224.243]) by mx.google.com with ESMTP id m70si3280888wma.241.2017.11.30.09.46.14; Thu, 30 Nov 2017 09:46:14 -0800 (PST) Received-SPF: pass (google.com: domain of alsa-devel-bounces@alsa-project.org designates 77.48.224.243 as permitted sender) client-ip=77.48.224.243; Authentication-Results: mx.google.com; dkim=neutral (body hash did not verify) header.i=@linaro.org header.s=google header.b=C+EwUO5m; spf=pass (google.com: domain of alsa-devel-bounces@alsa-project.org designates 77.48.224.243 as permitted sender) smtp.mailfrom=alsa-devel-bounces@alsa-project.org; dmarc=fail (p=NONE sp=NONE dis=NONE) header.from=linaro.org Received: from alsa0.perex.cz (localhost [127.0.0.1]) by alsa0.perex.cz (Postfix) with ESMTP id D2005267B23; Thu, 30 Nov 2017 18:45:53 +0100 (CET) X-Original-To: alsa-devel@alsa-project.org Delivered-To: alsa-devel@alsa-project.org Received: by alsa0.perex.cz (Postfix, from userid 1000) id ADBF426698E; Thu, 30 Nov 2017 18:45:51 +0100 (CET) X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on mail1.perex.cz X-Spam-Level: X-Spam-Status: No, score=-0.1 required=5.0 tests=DKIM_SIGNED,DKIM_VALID, DKIM_VALID_AU, RCVD_IN_DNSWL_NONE, RCVD_IN_MSPIKE_H3, RCVD_IN_MSPIKE_WL, SPF_PASS autolearn=disabled version=3.4.0 Received: from mail-wm0-f52.google.com (mail-wm0-f52.google.com [74.125.82.52]) by alsa0.perex.cz (Postfix) with ESMTP id 5895F26698E for ; Thu, 30 Nov 2017 18:45:49 +0100 (CET) Received: by mail-wm0-f52.google.com with SMTP id l141so14608613wmg.1 for ; Thu, 30 Nov 2017 09:45:49 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references; bh=TH6vZrTf7sKBObXmKnOO0pM/GAEeyTki2/Vfhmv7KDg=; b=C+EwUO5m2ktrVEOgT31cCT5C9Eh56Bfi65UoFDxN3XhLcwVULP3/CrVg+FsZYsa2J+ CjMjsOZJ+IS8y6LxLAgnO/Iba6egNEATGYQjzuUm2dLBHxpB8NPJp07aBwm57eY2+YaN AwHjpYAaJtM0rvU3RO1ci/UQvPkiZVssUnrl0= X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references; bh=TH6vZrTf7sKBObXmKnOO0pM/GAEeyTki2/Vfhmv7KDg=; b=niN+CYDMuDclbxPucQs6lLPgzHr7IO31+Svck+WUH6yZav/nYcAqldqKAw2ftpiCs2 5t2IKfbZDhVrM0ao4qnprNKa3MlrN3KRbbqmbG2bkE3HyWpyBlgI+FQ1DHQOqhUyqUyK A1nsA18aNfSFNGIVawAGaKovzVXjMlb06ujrrrIiANsf51AsGJgfvxsP0qC5VRMLmFSm YhhHkpSJjpNzARRKFPIIycnMX2Lo05TE3KU6+2IOmyivUN5MfISvbVM5LPWqPrEwwFCa gPbwAJJ34lmB/yskd0DpYM3enXaCGYCieHAduUnFB9vhdn21J7vozQVTVw8FrsOeCq1I kuxg== X-Gm-Message-State: AJaThX5FVH92x3KM+UDYBWFusOkbsoK/8T5nb/q5K5WOgk+jhF/wdDJT /Cj5kI0dmPDwUvrFKYG+zeiBzA== X-Received: by 10.28.245.11 with SMTP id t11mr2681872wmh.113.1512063948665; Thu, 30 Nov 2017 09:45:48 -0800 (PST) Received: from localhost.localdomain (cpc90716-aztw32-2-0-cust92.18-1.cable.virginm.net. [86.26.100.93]) by smtp.gmail.com with ESMTPSA id 189sm2412189wmu.3.2017.11.30.09.45.47 (version=TLS1_2 cipher=ECDHE-RSA-AES128-SHA bits=128/128); Thu, 30 Nov 2017 09:45:48 -0800 (PST) From: srinivas.kandagatla@linaro.org To: gregkh@linuxfoundation.org, broonie@kernel.org, alsa-devel@alsa-project.org Date: Thu, 30 Nov 2017 17:41:48 +0000 Message-Id: <20171130174200.6684-2-srinivas.kandagatla@linaro.org> X-Mailer: git-send-email 2.15.0 In-Reply-To: <20171130174200.6684-1-srinivas.kandagatla@linaro.org> References: <20171130174200.6684-1-srinivas.kandagatla@linaro.org> Cc: mark.rutland@arm.com, michael.opdenacker@free-electrons.com, poeschel@lemonage.de, srinivas.kandagatla@linaro.org, andreas.noever@gmail.com, arnd@arndb.de, vinod.koul@intel.com, bp@suse.de, devicetree@vger.kernel.org, james.hogan@imgtec.com, pawel.moll@arm.com, linux-arm-msm@vger.kernel.org, sharon.dvir1@mail.huji.ac.il, robh+dt@kernel.org, sdharia@codeaurora.org, alan@linux.intel.com, treding@nvidia.com, mathieu.poirier@linaro.org, jkosina@suse.cz, linux-kernel@vger.kernel.org, daniel@ffwll.ch, joe@perches.com, davem@davemloft.net Subject: [alsa-devel] [PATCH v8 01/13] Documentation: Add SLIMbus summary X-BeenThere: alsa-devel@alsa-project.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: "Alsa-devel mailing list for ALSA developers - http://www.alsa-project.org" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , MIME-Version: 1.0 Errors-To: alsa-devel-bounces@alsa-project.org Sender: alsa-devel-bounces@alsa-project.org From: Sagar Dharia SLIMbus (Serial Low Power Interchip Media Bus) is a specification developed by MIPI (Mobile Industry Processor Interface) alliance. SLIMbus is a 2-wire implementation, which is used to communicate with peripheral components like audio-codec. The summary of SLIMbus and API is documented in the 'summary' file. Signed-off-by: Sagar Dharia Signed-off-by: Srinivas Kandagatla --- Documentation/driver-api/slimbus/index.rst | 15 ++++ Documentation/driver-api/slimbus/summary.rst | 108 +++++++++++++++++++++++++++ 2 files changed, 123 insertions(+) create mode 100644 Documentation/driver-api/slimbus/index.rst create mode 100644 Documentation/driver-api/slimbus/summary.rst -- 2.15.0 _______________________________________________ Alsa-devel mailing list Alsa-devel@alsa-project.org http://mailman.alsa-project.org/mailman/listinfo/alsa-devel diff --git a/Documentation/driver-api/slimbus/index.rst b/Documentation/driver-api/slimbus/index.rst new file mode 100644 index 000000000000..586f979659e6 --- /dev/null +++ b/Documentation/driver-api/slimbus/index.rst @@ -0,0 +1,15 @@ +===================== +SLIMbus Documentation +===================== + +.. toctree:: + :maxdepth: 1 + + summary + +.. only:: subproject + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/driver-api/slimbus/summary.rst b/Documentation/driver-api/slimbus/summary.rst new file mode 100644 index 000000000000..ba165611725a --- /dev/null +++ b/Documentation/driver-api/slimbus/summary.rst @@ -0,0 +1,108 @@ +============================ +Linux kernel SLIMbus support +============================ + +Overview +======== + +What is SLIMbus? +---------------- +SLIMbus (Serial Low Power Interchip Media Bus) is a specification developed by +MIPI (Mobile Industry Processor Interface) alliance. The bus uses master/slave +configuration, and is a 2-wire multi-drop implementation (clock, and data). + +Currently, SLIMbus is used to interface between application processors of SoCs +(System-on-Chip) and peripheral components (typically codec).SLIMbus uses +Time-Division-Multiplexing to accommodate multiple data channels, and +a control channel. + +The control channel is used for various control functions such as bus +management, configuration and status updates.These messages can be unicast (e.g. +reading/writing device specific values), or multicast (e.g. data channel +reconfiguration sequence is a broadcast message announced to all devices) + +A data channel is used for data-transfer between 2 SLIMbus devices. Data +channel uses dedicated ports on the device. + +Hardware description: +--------------------- +SLIMbus specification has different types of device classifications based on +their capabilities. +A manager device is responsible for enumeration, configuration, and dynamic +channel allocation. Every bus has 1 active manager. + +A generic device is a device providing application functionality (e.g. codec). + +Framer device is responsible for clocking the bus, and transmitting frame-sync +and framing information on the bus. + +Each SLIMbus component has an interface device for monitoring physical layer. + +Typically each SoC contains SLIMbus component having 1 manager, 1 framer device, +1 generic device (for data channel support), and 1 interface device. +External peripheral SLIMbus component usually has 1 generic device (for +functionality/data channel support), and an associated interface device. +The generic device's registers are mapped as 'value elements' so that they can +be written/read using SLIMbus control channel exchanging control/status type of +information. +In case there are multiple framer devices on the same bus, manager device is +responsible to select the active-framer for clocking the bus. + +Per specification, SLIMbus uses "clock gears" to do power management based on +current frequency and bandwidth requirements. There are 10 clock gears and each +gear changes the SLIMbus frequency to be twice its previous gear. + +Each device has a 6-byte enumeration-address and the manager assigns every +device with a 1-byte logical address after the devices report presence on the +bus. + +Software description: +--------------------- +There are 2 types of SLIMbus drivers: + +slim_controller represents a 'controller' for SLIMbus. This driver should +implement duties needed by the SoC (manager device, associated +interface device for monitoring the layers and reporting errors, default +framer device). + +slim_device represents the 'generic device/component' for SLIMbus, and a +slim_driver should implement driver for that slim_device. + +Device notifications to the driver: +----------------------------------- +Since SLIMbus devices have mechanisms for reporting their presence, the +framework allows drivers to bind when corresponding devices report their +presence on the bus. +However, it is possible that the driver needs to be probed +first so that it can enable corresponding SLIMbus device (e.g. power it up and/or +take it out of reset). To support that behavior, the framework allows drivers +to probe first as well (e.g. using standard DeviceTree compatbility field). +This creates the necessity for the driver to know when the device is functional +(i.e. reported present). device_up callback is used for that reason when the +device reports present and is assigned a logical address by the controller. + +Similarly, SLIMbus devices 'report absent' when they go down. A 'device_down' +callback notifies the driver when the device reports absent and its logical +address assignment is invalidated by the controller. + +Another notification "boot_device" is used to notify the slim_driver when +controller resets the bus. This notification allows the driver to take necessary +steps to boot the device so that it's functional after the bus has been reset. + +Clock-pause: +------------ +SLIMbus mandates that a reconfiguration sequence (known as clock-pause) be +broadcast to all active devices on the bus before the bus can enter low-power +mode. Controller uses this sequence when it decides to enter low-power mode so +that corresponding clocks and/or power-rails can be turned off to save power. +Clock-pause is exited by waking up framer device (if controller driver initiates +exiting low power mode), or by toggling the data line (if a slave device wants +to initiate it). + +Messaging APIs: +--------------- +The framework supports APIs to exchange control-information with a SLIMbus +device. APIs can be synchronous or asynchronous. +From controller's perspective, multiple buffers can be queued to/from +hardware for sending/receiving data using slim_ctrl_buf circular buffer. +The header file has more documentation about messaging APIs.