From patchwork Thu Dec 7 10:27:08 2017 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Srinivas Kandagatla X-Patchwork-Id: 120949 Delivered-To: patch@linaro.org Received: by 10.140.22.227 with SMTP id 90csp8178484qgn; Thu, 7 Dec 2017 02:30:44 -0800 (PST) X-Google-Smtp-Source: AGs4zMbvd4SdPDVNUi/6QFYI12d9DLz5lrLOrwhl+3fgnWcKb2IDMkPveJQLOu0kp5UT3mfEdNpU X-Received: by 10.84.244.12 with SMTP id g12mr12294254pll.69.1512642644594; Thu, 07 Dec 2017 02:30:44 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1512642644; cv=none; d=google.com; s=arc-20160816; b=EpHFy9tRt/0DpwHLWg7wJ8sGVCXex8xANBLpweHRu9lxlBsaCTb0GUI4WJ927dfjxA OM0hHm38qymUaa6ThOUIwY3FYcER25gHg7MxsUpJPp5fbMsDScB/vBI4VjOOoRDYrl4B 159Vdxx4Eg9jj5v4jjDpwSAd+AV66XMU0NFln87R/D+CrNSkuhVPLTUlf/q+AsOcaHmO B+c9OTqyov03D5nf74qvBjss2FW4ixQ0M1rsta/IU6EPm0T06bH2adg84NunQP2SLGjT bij7z4nA8tq8VtK9GWHbWoeelQxdCHh1LUqUmV3efUn6mleRS5ERD2JuXnYd9Tz6aK/e 0srQ== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-id:precedence:sender:references:in-reply-to:message-id:date :subject:cc:to:from:dkim-signature:arc-authentication-results; bh=UBbUIbsiqgkAbjlQAMyLG0t4MFdhWqZU5WQAJ65PyVA=; b=THUqMvQzyph6cMFM0169vczidF9h/bWbGhigRnfRwQ7GLQRAF1O4yQ571qoHxNIitG O7q36PwQ/LJ/VJ8dtd8QECXi76NLYyYp5AxuafDwIdM55Y7tSt6j+Fuv2+iEEgikLLP+ ib5UKP8Zog/xRz/4VA4AYP2MlMqDnoQ2f120Igs2S7XU3qHe8c5PQ+uA12jcbMfsHHDU F6NsBj+I9twTXvy0fUsVQvIYRuOZgowluxz1EiMPADwYjLTbj19Fg/ofGts7qd9uGZ// MfnAQ05AKDywLxc3KUoeR3t9YTND4T9a/EpzPzYqXvtUFDPLvuHoFKWZxhkmWQ+MQ4AY n/2w== ARC-Authentication-Results: i=1; mx.google.com; dkim=neutral (body hash did not verify) header.i=@linaro.org header.s=google header.b=SE7DJzjI; spf=pass (google.com: best guess record for domain of devicetree-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) smtp.mailfrom=devicetree-owner@vger.kernel.org; dmarc=fail (p=NONE sp=NONE dis=NONE) header.from=linaro.org Return-Path: Received: from vger.kernel.org (vger.kernel.org. [209.132.180.67]) by mx.google.com with ESMTP id q1si3547248plb.29.2017.12.07.02.30.44; Thu, 07 Dec 2017 02:30:44 -0800 (PST) Received-SPF: pass (google.com: best guess record for domain of devicetree-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) client-ip=209.132.180.67; Authentication-Results: mx.google.com; dkim=neutral (body hash did not verify) header.i=@linaro.org header.s=google header.b=SE7DJzjI; spf=pass (google.com: best guess record for domain of devicetree-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) smtp.mailfrom=devicetree-owner@vger.kernel.org; dmarc=fail (p=NONE sp=NONE dis=NONE) header.from=linaro.org Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1752751AbdLGKal (ORCPT + 6 others); Thu, 7 Dec 2017 05:30:41 -0500 Received: from mail-wm0-f45.google.com ([74.125.82.45]:42330 "EHLO mail-wm0-f45.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1752709AbdLGKah (ORCPT ); Thu, 7 Dec 2017 05:30:37 -0500 Received: by mail-wm0-f45.google.com with SMTP id l141so12132685wmg.1 for ; Thu, 07 Dec 2017 02:30:37 -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=TWw1aBzCC+o6KMQ3eRt88ZFpRWuWGERBuDsTZu+HFZg=; b=SE7DJzjIJl0TKw0YBfwjx/BBJOUEGGOdwwmCBW6aG7hdp4wQdmCyUsntxMx+t8Q+3/ SiX1u7UxsAnIP7OwIu+rJRuO0EpjH8VCBIPHaJoJo0ppwgWFOKNAav3dtoryz3JM+1+f EsLmyX65RNFcYPGRrdb7Cl0wo76zND1dtgDzk= 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=TWw1aBzCC+o6KMQ3eRt88ZFpRWuWGERBuDsTZu+HFZg=; b=UhmYsIhWvXrToOeV10s6g6jjoD5O5lPjj0FquYnroJybh+v0akgDbaBL3iuDE7ZQ3X 1BJJkMssaYDPvKQoe86ilN4OIJRRHynO77ZHGes8vWiHDX90nxn9rqIolCH/dde+jtr1 BgmdCFMI9x2NzuBhdYRTbPLS5kRVunDHAIbRCDSxztbspNdKi/qHD/ndPOX1VvBdhOxK ex2fjDELoaGHPRdCHwUH+I45EBpMlUEJW7TbBjc8DJUvqetaFfxWcBep7gTl532ahd8m 514SBxv0+8nZLHTWxzWiloraDHlEQp8/r+FYqP6iM9AGktkKxVbUI+oqR6hAwZMp+sAf RQUw== X-Gm-Message-State: AKGB3mIaOL4EjxSKDYTgVn4S21fxfPVBkC+yrK4rP9QD01RUR/Jl3oim SoGwbYFw49e4GWNh4wxw/DTkcA== X-Received: by 10.28.129.77 with SMTP id c74mr704496wmd.124.1512642636203; Thu, 07 Dec 2017 02:30:36 -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 k2sm4837734wrg.4.2017.12.07.02.30.35 (version=TLS1_2 cipher=ECDHE-RSA-AES128-SHA bits=128/128); Thu, 07 Dec 2017 02:30:35 -0800 (PST) From: srinivas.kandagatla@linaro.org To: Mark Brown , Greg Kroah-Hartman , alsa-devel@alsa-project.org Cc: sdharia@codeaurora.org, Rob Herring , Mark Rutland , Jonathan Corbet , pombredanne@nexb.com, j.neuschaefer@gmx.net, linux-arm-msm@vger.kernel.org, devicetree@vger.kernel.org, linux-kernel@vger.kernel.org, linux-doc@vger.kernel.org, Srinivas Kandagatla Subject: [PATCH v9 01/13] Documentation: Add SLIMbus summary Date: Thu, 7 Dec 2017 10:27:08 +0000 Message-Id: <20171207102720.21071-2-srinivas.kandagatla@linaro.org> X-Mailer: git-send-email 2.15.0 In-Reply-To: <20171207102720.21071-1-srinivas.kandagatla@linaro.org> References: <20171207102720.21071-1-srinivas.kandagatla@linaro.org> Sender: devicetree-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: devicetree@vger.kernel.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/index.rst | 1 + Documentation/driver-api/slimbus/index.rst | 15 ++++ Documentation/driver-api/slimbus/summary.rst | 106 +++++++++++++++++++++++++++ 3 files changed, 122 insertions(+) create mode 100644 Documentation/driver-api/slimbus/index.rst create mode 100644 Documentation/driver-api/slimbus/summary.rst -- 2.15.0 -- To unsubscribe from this list: send the line "unsubscribe devicetree" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst index d17a9876b473..3de6097525f4 100644 --- a/Documentation/driver-api/index.rst +++ b/Documentation/driver-api/index.rst @@ -47,6 +47,7 @@ available subsections can be seen below. gpio misc_devices dmaengine/index + slimbus/index .. only:: subproject and html 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..9a296766dc46 --- /dev/null +++ b/Documentation/driver-api/slimbus/summary.rst @@ -0,0 +1,106 @@ +============================ +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 compatibility 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 regmap and read/write apis to exchange control-information +with a SLIMbus device. APIs can be synchronous or asynchronous. +The header file has more documentation about messaging APIs.