Received: by 2002:a25:8b91:0:0:0:0:0 with SMTP id j17csp675755ybl; Thu, 23 Jan 2020 05:52:56 -0800 (PST) X-Google-Smtp-Source: APXvYqwMP50Hhd/6i87OvVuz/IYmzCsMDR5170PqXXwrBwZvr4JQEEi2jjQLIn79zH1xq83DTseE X-Received: by 2002:a05:6830:1f19:: with SMTP id u25mr11789004otg.170.1579787576176; Thu, 23 Jan 2020 05:52:56 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1579787576; cv=none; d=google.com; s=arc-20160816; b=S1MKDeSW5w9iTQLjOkTxfCIOGJE+V+S6ltcOy/m19Q46x70nrM263T0f5ALdB2ReQd M4TJLNXPYPfdwb+sCJ/+wtzzOcSWziHxnWek/pGtvHEYif9h6D5/6FdSb5885wouxaIa VwLySxyb9bx763VLhJRFd9gwZwgmXn4cIcOlD9+SPHMEAtgNlw0TyHBVJeXTARcEnx2K iJFv2ATnXNzjGuxK/ijgFwwxDiALpTk0dfX/IEezTHY95OxD4smoEU2bhdp3S+LhnoAm UbxeZwCt8A6ydQ0G5i+55rbgB43YLgNGqzS2Svt2aneGJEVQHw1WO1OZvteTwDVZ7s1H rLCw== 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=g4LggqncWuYQ/WNkXsDg1EzuFa59qCu8tj8brGM/oGA=; b=ZXDDQ0ltrsIl97TrpKMcIhffdM+VfvZcDvGTscw3CZjN+vrLCUF0L3ls1tQzq2DCLQ m5jPYROy05Cemj/jVzPR7YhlyuUezV4CfcVBVW/zca56Kv0dqoORSjK8ZiFwVd7Eta78 01z4/EFabGCt9XPZ8j9Uu7zHemaY7e6OG7Iw+VKN79mP5XI+D/x7jp1SGKxCeu/8Dkml So4H9W0jED8OjAawJC0VjG8XnWyZnqJNi4wzzTtQ0GzGrqxCAxoRPjMfABfZRR0kIXmF QJvQkIIFfQh9rhTG2BRVESj16EzF86kcRR56pW9yqXfM7hJMIaVJVL8MnauK7KJc9j/E av2w== 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 m85si889348oig.158.2020.01.23.05.52.44; Thu, 23 Jan 2020 05:52:56 -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 S1728981AbgAWNvo (ORCPT + 99 others); Thu, 23 Jan 2020 08:51:44 -0500 Received: from hostingweb31-40.netsons.net ([89.40.174.40]:39037 "EHLO hostingweb31-40.netsons.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1727312AbgAWNvn (ORCPT ); Thu, 23 Jan 2020 08:51:43 -0500 Received: from [109.168.11.45] (port=47192 helo=pc-ceresoli.dev.aim) by hostingweb31.netsons.net with esmtpa (Exim 4.92) (envelope-from ) id 1iuctV-000CNg-DS; Thu, 23 Jan 2020 14:51:37 +0100 From: Luca Ceresoli To: linux-i2c@vger.kernel.org, linux-doc@vger.kernel.org Cc: Luca Ceresoli , Wolfram Sang , Jean Delvare , Peter Rosin , linux-kernel@vger.kernel.org Subject: [PATCH v2 03/28] docs: i2c: summary: rewrite the "terminology" section Date: Thu, 23 Jan 2020 14:50:38 +0100 Message-Id: <20200123135103.20540-4-luca@lucaceresoli.net> X-Mailer: git-send-email 2.25.0 In-Reply-To: <20200123135103.20540-1-luca@lucaceresoli.net> References: <20200123135103.20540-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 Reviewed-by: Jean Delvare --- Changes in v2: - mention the drivers/i2c/algos/ directory when introducing algos (Jean Delvare) --- Documentation/i2c/i2c.svg | 1341 +++++++++++++++++++++++++++++++++ Documentation/i2c/summary.rst | 36 +- 2 files changed, 1363 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 dbab737d5075..09f73a608e25 100644 --- a/Documentation/i2c/summary.rst +++ b/Documentation/i2c/summary.rst @@ -31,21 +31,29 @@ 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 +an algorithm driver in the ``drivers/i2c/algos/`` subdirectory, 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.25.0