Received: by 2002:a25:8b91:0:0:0:0:0 with SMTP id j17csp20913159ybl; Sun, 5 Jan 2020 14:51:44 -0800 (PST) X-Google-Smtp-Source: APXvYqzDUBgxYctPe87CJWtQxUc1mgxDiYxbODbCVM8y/47+bDEBfMKOAt2vYOb9Dcm+oQMC+mrv X-Received: by 2002:a9d:74c7:: with SMTP id a7mr116060043otl.7.1578264704916; Sun, 05 Jan 2020 14:51:44 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1578264704; cv=none; d=google.com; s=arc-20160816; b=uWKnH/X4sAN9mqAVWqL6s/JjsX/avfvHNDICffLqvNel4y213FtnA2ENNdnBZV5Gvp fa+UMZQUZBRpVL8qxv7mIghI/J3u9qOIv+H6GttujTx+ZyNeNLmeRGH8IdCvxgwKtquC Czpv6bAsYhpH0kg/6pGB8PRucjcwrd0dpnxl7eyGekmSsgqEPlWJI3QQqUYA8J5tM6A5 jtWm+GZKohNG8KhpbGBSkHmxdQd1anqAFR8Nx43TXbahBO3nnDgdvJFrjupQY69fp6m1 3IEflAVwPdJ/fWr/fpU3MpnCOfxHtYdtQO7gVcAShTKWNmcoejzvP31hrmgtzlP5yvoM T9/Q== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-id:precedence:sender:content-transfer-encoding:mime-version :references:in-reply-to:message-id:date:subject:cc:to:from; bh=DP2DGRXaBiOW/zWZUqpoh6u/R+eoAwvbzNQ8tL4O9l0=; b=suRbg+3k2zQgCQQHw8bQ3uCovSwPW0T0Pz0jGePnZQ+M6PyKLS3p4SLFceDyMsOP2J F4gJFkisoETcfrqqygFO3AqoFUle4/2m1gNVnnXVWazoTPsPH03XA8XSyplLckIhiBLX /K2Ic5TQtHmbdjdgRZifc/8QwYfs8Xq29UDuECig+KgNVsAHF3+/bZkQC5+MjI+XXM9/ Js+XduDGvkqYnbKjcexJgdBwT16DjCibmxHpOlfn5u4SxZAqzY2JXzl4wwD/wK5esyyF cuUd1OhVfzwC3frGFoztMVXKtTW7UoRaIsOj244vkKEXv68FtAKzmQ9gkIsQMjXdzB93 xhwg== ARC-Authentication-Results: i=1; mx.google.com; spf=pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org Return-Path: Received: from vger.kernel.org (vger.kernel.org. [209.132.180.67]) by mx.google.com with ESMTP id x186si30400615oig.209.2020.01.05.14.51.32; Sun, 05 Jan 2020 14:51:44 -0800 (PST) Received-SPF: pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) client-ip=209.132.180.67; Authentication-Results: mx.google.com; spf=pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1727273AbgAEWul (ORCPT + 99 others); Sun, 5 Jan 2020 17:50:41 -0500 Received: from hostingweb31-40.netsons.net ([89.40.174.40]:37787 "EHLO hostingweb31-40.netsons.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1727146AbgAEWuk (ORCPT ); Sun, 5 Jan 2020 17:50:40 -0500 Received: from [37.160.42.38] (port=5507 helo=melee.fritz.box) by hostingweb31.netsons.net with esmtpa (Exim 4.92) (envelope-from ) id 1ioEjB-00GSqI-RV; Sun, 05 Jan 2020 23:50:34 +0100 From: Luca Ceresoli To: linux-doc@vger.kernel.org, linux-i2c@vger.kernel.org Cc: Luca Ceresoli , Wolfram Sang , Peter Rosin , linux-kernel@vger.kernel.org Subject: [PATCH 03/26] docs: i2c: summary: rewrite the "terminology" section Date: Sun, 5 Jan 2020 23:49:49 +0100 Message-Id: <20200105225012.11701-3-luca@lucaceresoli.net> X-Mailer: git-send-email 2.24.1 In-Reply-To: <20200105225012.11701-1-luca@lucaceresoli.net> References: <20200105224006.10321-1-luca@lucaceresoli.net> <20200105225012.11701-1-luca@lucaceresoli.net> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-AntiAbuse: This header was added to track abuse, please include it with any abuse report X-AntiAbuse: Primary Hostname - hostingweb31.netsons.net X-AntiAbuse: Original Domain - vger.kernel.org X-AntiAbuse: Originator/Caller UID/GID - [47 12] / [47 12] X-AntiAbuse: Sender Address Domain - lucaceresoli.net X-Get-Message-Sender-Via: hostingweb31.netsons.net: authenticated_id: luca+lucaceresoli.net/only user confirmed/virtual account not confirmed X-Authenticated-Sender: hostingweb31.netsons.net: luca@lucaceresoli.net X-Source: X-Source-Args: X-Source-Dir: Sender: linux-kernel-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org This section, partly dating back to the pre-git era, is somewhat unclear and partly incorrect. Rewrite it almost completely including a reference figure, concise but precise definition of each term and the paths where drivers are found. Particular care has been put in clarifying the relation between adapter and algorithm, which has no correspondence in the I2C spec terminology. Signed-off-by: Luca Ceresoli --- Documentation/i2c/i2c.svg | 1341 +++++++++++++++++++++++++++++++++ Documentation/i2c/summary.rst | 35 +- 2 files changed, 1362 insertions(+), 14 deletions(-) create mode 100644 Documentation/i2c/i2c.svg diff --git a/Documentation/i2c/i2c.svg b/Documentation/i2c/i2c.svg new file mode 100644 index 000000000000..5979405ad1c3 --- /dev/null +++ b/Documentation/i2c/i2c.svg @@ -0,0 +1,1341 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + Luca Ceresoli + + + 2020 + + + + + + + + + + + + + + + I2CMaster + + + I2CSlave + + SCL + SDA + + I2CSlave + + I2CSlave + + + + + + + + + + + + VDD + + diff --git a/Documentation/i2c/summary.rst b/Documentation/i2c/summary.rst index b7d3e620155b..fc69d9567d9d 100644 --- a/Documentation/i2c/summary.rst +++ b/Documentation/i2c/summary.rst @@ -31,21 +31,28 @@ implement all the common SMBus protocol semantics or messages. Terminology =========== -When we talk about I2C, we use the following terms:: +Using the terminology from the official documentation, the I2C bus connects +one or more *master* chips and one or more *slave* chips. - Bus -> Algorithm - Adapter - Device -> Driver - Client +.. kernel-figure:: i2c.svg + :alt: Simple I2C bus with one master and 3 slaves -An Algorithm driver contains general code that can be used for a whole class -of I2C adapters. Each specific adapter driver either depends on one algorithm -driver, or includes its own implementation. + Simple I2C bus -A Driver driver (yes, this sounds ridiculous, sorry) contains the general -code to access some type of device. Each detected device gets its own -data in the Client structure. Usually, Driver and Client are more closely -integrated than Algorithm and Adapter. +A **master** chip is a node that starts communications with slaves. In the +Linux kernel implementation it is called an **adapter** or bus. Adapter +drivers are in the ``drivers/i2c/busses/`` subdirectory. -For a given configuration, you will need a driver for your I2C bus, and -drivers for your I2C devices (usually one driver for each device). +An **algorithm** contains general code that can be used to implement a +whole class of I2C adapters. Each specific adapter driver either depends on +one algorithm driver, or includes its own implementation. + +A **slave** chip is a node that responds to communications when addressed +by the master. In Linux it is called a **client**. Client drivers are kept +in a directory specific to the feature they provide, for example +``drivers/media/gpio/`` for GPIO expanders and ``drivers/media/i2c/`` for +video-related chips. + +For the example configuration in figure, you will need a driver for your +I2C adapter, and drivers for your I2C devices (usually one driver for each +device). -- 2.24.1