From patchwork Fri Jun 21 07:30:08 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Wolfram Sang X-Patchwork-Id: 806935 Received: from mail.zeus03.de (zeus03.de [194.117.254.33]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 7773282D68 for ; Fri, 21 Jun 2024 07:30:25 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=194.117.254.33 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1718955027; cv=none; b=fSJjzU/YDhRh9dA1ARJBNTh2TEh/6yGA3uZPzAjwOVXAA36N2kT7nA8r4b/h0XWgr5ORzypHm75B3sAUkwSjtbMVON6oaCpyAKcMOgTu3RojZye2xXMer8yEJOg+mv8UV/cXclc/IH+XRuTdc9TuLxc3BouwHk6WZVb/SfSqPvQ= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1718955027; c=relaxed/simple; bh=AaeKWFy6+MhJUSVDuiArePmxqwjpDms46lje4lfg78Y=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=WSoclfBRY5lXUho/d0r8PMOEN64yxtscthTPX/nRrzxtFf8ZX0SEQV/vs5qYYtfoD1p1J7iS7g3qmzxzqcYAcc3IWvqHyGMa9TUZ7Tq6Wvh89evGEvr5bLANybG4Hh/zOUY1CFpkdwa9+FoZYEcEXwJz5prmRRVu0X5a9ss6jys= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=none (p=none dis=none) header.from=sang-engineering.com; spf=pass smtp.mailfrom=sang-engineering.com; dkim=pass (2048-bit key) header.d=sang-engineering.com header.i=@sang-engineering.com header.b=Wg0mtBT9; arc=none smtp.client-ip=194.117.254.33 Authentication-Results: smtp.subspace.kernel.org; dmarc=none (p=none dis=none) header.from=sang-engineering.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=sang-engineering.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=sang-engineering.com header.i=@sang-engineering.com header.b="Wg0mtBT9" DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d= sang-engineering.com; h=from:to:cc:subject:date:message-id :in-reply-to:references:mime-version:content-type :content-transfer-encoding; s=k1; bh=QxN9/peWzKBlFqRmDXEKD0iHTiZ lunJFWOblMthWaXk=; b=Wg0mtBT9TyelcTDA6riZbZ61STrKMj128jtojXWdlDy cZGsCS4/HE6r3C5To2WPq1n3j9GVdKufVNIGHfPoxwwpkYmt++KVWSqrIClwPjIB hklChVsz1gt/PhbDBpPZKA1Plk8hU90bCHWCdcKg4xQpBu+rbnrZ8K2rKVpfMz4Q BIXiBXw/P0MU72PPsXGVLhACU7DcoUurSYGi3KvV9L25DjOXjdd6Iad0nQulC65M SMD6wXxoTyEU1H7C+rTSdKtExeBpVMWBybKZstz9ZWXv9iYglaJvDnT6t0yyZxCF 3KAZPL6lefdo2qGu9np8lkfUE4xwLZ+Tav8WrGdBOIg== Received: (qmail 1279036 invoked from network); 21 Jun 2024 09:30:23 +0200 Received: by mail.zeus03.de with ESMTPSA (TLS_AES_256_GCM_SHA384 encrypted, authenticated); 21 Jun 2024 09:30:23 +0200 X-UD-Smtp-Session: l3s3148p1@G1uLZ2Eb0MMgAwDPXzjQABqqX1QYyOSW From: Wolfram Sang To: linux-kernel@vger.kernel.org Cc: Andi Shyti , Easwar Hariharan , Wolfram Sang , linux-i2c@vger.kernel.org Subject: [PATCH v4 1/6] docs: i2c: summary: start sentences consistently. Date: Fri, 21 Jun 2024 09:30:08 +0200 Message-ID: <20240621073015.5443-2-wsa+renesas@sang-engineering.com> X-Mailer: git-send-email 2.43.0 In-Reply-To: <20240621073015.5443-1-wsa+renesas@sang-engineering.com> References: <20240621073015.5443-1-wsa+renesas@sang-engineering.com> Precedence: bulk X-Mailing-List: linux-i2c@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Change the first paragraphs to contain only one space after the end of the previous sentence like in the rest of the document. Signed-off-by: Wolfram Sang Reviewed-by: Easwar Hariharan --- Documentation/i2c/summary.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/Documentation/i2c/summary.rst b/Documentation/i2c/summary.rst index 786c618ba3be..28ff80a2302b 100644 --- a/Documentation/i2c/summary.rst +++ b/Documentation/i2c/summary.rst @@ -4,10 +4,10 @@ Introduction to I2C and SMBus I²C (pronounce: I squared C and written I2C in the kernel documentation) is a protocol developed by Philips. It is a slow two-wire protocol (variable -speed, up to 400 kHz), with a high speed extension (3.4 MHz). It provides +speed, up to 400 kHz), with a high speed extension (3.4 MHz). It provides an inexpensive bus for connecting many types of devices with infrequent or -low bandwidth communications needs. I2C is widely used with embedded -systems. Some systems use variants that don't meet branding requirements, +low bandwidth communications needs. I2C is widely used with embedded +systems. Some systems use variants that don't meet branding requirements, and so are not advertised as being I2C but come under different names, e.g. TWI (Two Wire Interface), IIC. @@ -18,14 +18,14 @@ access the PDF. An older version of the specification (revision 6) is archived `here `_. SMBus (System Management Bus) is based on the I2C protocol, and is mostly -a subset of I2C protocols and signaling. Many I2C devices will work on an +a subset of I2C protocols and signaling. Many I2C devices will work on an SMBus, but some SMBus protocols add semantics beyond what is required to -achieve I2C branding. Modern PC mainboards rely on SMBus. The most common +achieve I2C branding. Modern PC mainboards rely on SMBus. The most common devices connected through SMBus are RAM modules configured using I2C EEPROMs, and hardware monitoring chips. Because the SMBus is mostly a subset of the generalized I2C bus, we can -use its protocols on many I2C systems. However, there are systems that don't +use its protocols on many I2C systems. However, there are systems that don't meet both SMBus and I2C electrical constraints; and others which can't implement all the common SMBus protocol semantics or messages. From patchwork Fri Jun 21 07:30:09 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Wolfram Sang X-Patchwork-Id: 806934 Received: from mail.zeus03.de (zeus03.de [194.117.254.33]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 4048F14D449 for ; Fri, 21 Jun 2024 07:30:25 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=194.117.254.33 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1718955029; cv=none; b=jsLsorayjZ0Hjn8bVTZoZbJg7a2YnwqU7sw0LFyhaqb0aL5YS+hFF4CaE8vtRGF8d2kV9lw/gZNsr05XnSWTnPInaaWfnXFGNZ4XsanjXjExIroeMmuUUW4D5QE2UQxtI/Oa0NqFS4Pv6B7BjhooQOuZCwffU66fh3T2VI1I1p0= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1718955029; c=relaxed/simple; bh=tLa3YjKzTjbALrEqcR62zhXe0F7RUglCnTOQTHelM9A=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=r8xQk3TCxbhgFB42+gqolxB8d3KKWIDKN5waLMXBa8b8F60nLOJX6GgxTRJIRp9PcO37W9zQAj+sdiZ0uhR99+LQO24IfAf9rO5Mr7qMsNXVGTWn+CmiN8Om3+hygor1aNaD7uea/HzG+RJqDd9K5hXRYJW/bKjyfx4NTmOXGbM= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=none (p=none dis=none) header.from=sang-engineering.com; spf=pass smtp.mailfrom=sang-engineering.com; dkim=pass (2048-bit key) header.d=sang-engineering.com header.i=@sang-engineering.com header.b=e5da2N5a; arc=none smtp.client-ip=194.117.254.33 Authentication-Results: smtp.subspace.kernel.org; dmarc=none (p=none dis=none) header.from=sang-engineering.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=sang-engineering.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=sang-engineering.com header.i=@sang-engineering.com header.b="e5da2N5a" DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d= sang-engineering.com; h=from:to:cc:subject:date:message-id :in-reply-to:references:mime-version:content-type :content-transfer-encoding; s=k1; bh=ns0TUqgMIMc2G1ba8motoRRT6bt z+ty/Oyg8gP8SWmY=; b=e5da2N5atOPx9sU3HnbguoDU4x5iKVRPkVDDDEpkwqK HiHr5/qo1NyhMdC7ZFGP1l4nyBrQ4Bl8zceH3ze4/zsaZLtJVZExLd0OcKPeZLY7 ABAEm0iSVfhE88OP5WB1ZwBuRf+oG70iJXj0zGbcnJi3TarvrlKV6NA6K3U50yK9 4zvR7Pkeidg7aGuAVEjMBakop8ISfFjQvXEaiT74LRrS1H98474Nha97hU09ZR2x uVR0zx1iKUWMbcwIB3vkFs0MtW7+aIyEgW8AVnYujhaCAie9kkos9Ok7U8stIymt 4Gf0KWZqSXZZObSm/cYDI4KdqqgREOOsCnMuPzMv1xQ== Received: (qmail 1279065 invoked from network); 21 Jun 2024 09:30:24 +0200 Received: by mail.zeus03.de with ESMTPSA (TLS_AES_256_GCM_SHA384 encrypted, authenticated); 21 Jun 2024 09:30:24 +0200 X-UD-Smtp-Session: l3s3148p1@ZFyXZ2Eb0sMgAwDPXzjQABqqX1QYyOSW From: Wolfram Sang To: linux-kernel@vger.kernel.org Cc: Andi Shyti , Easwar Hariharan , Wolfram Sang , linux-i2c@vger.kernel.org Subject: [PATCH v4 2/6] docs: i2c: summary: update I2C specification link Date: Fri, 21 Jun 2024 09:30:09 +0200 Message-ID: <20240621073015.5443-3-wsa+renesas@sang-engineering.com> X-Mailer: git-send-email 2.43.0 In-Reply-To: <20240621073015.5443-1-wsa+renesas@sang-engineering.com> References: <20240621073015.5443-1-wsa+renesas@sang-engineering.com> Precedence: bulk X-Mailing-List: linux-i2c@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Luckily, the specs are directly downloadable again, so update the link. Also update its title to the original name "I²C". Signed-off-by: Wolfram Sang Reviewed-by: Easwar Hariharan --- Documentation/i2c/summary.rst | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/Documentation/i2c/summary.rst b/Documentation/i2c/summary.rst index 28ff80a2302b..e3ab1d414014 100644 --- a/Documentation/i2c/summary.rst +++ b/Documentation/i2c/summary.rst @@ -11,11 +11,9 @@ systems. Some systems use variants that don't meet branding requirements, and so are not advertised as being I2C but come under different names, e.g. TWI (Two Wire Interface), IIC. -The latest official I2C specification is the `"I2C-bus specification and user -manual" (UM10204) `_ -published by NXP Semiconductors. However, you need to log-in to the site to -access the PDF. An older version of the specification (revision 6) is archived -`here `_. +The latest official I2C specification is the `"I²C-bus specification and user +manual" (UM10204) `_ +published by NXP Semiconductors, version 7 as of this writing. SMBus (System Management Bus) is based on the I2C protocol, and is mostly a subset of I2C protocols and signaling. Many I2C devices will work on an From patchwork Fri Jun 21 07:30:10 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Wolfram Sang X-Patchwork-Id: 806430 Received: from mail.zeus03.de (zeus03.de [194.117.254.33]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id E790116B3A5 for ; Fri, 21 Jun 2024 07:30:26 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=194.117.254.33 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1718955029; cv=none; b=o0b4PlPHjnP3UrAs7RNUD2s+VaG8rOUnRoxpxDwmIePmx8JY3Mt8lRHtlZGxij4PDQomnE/p+7vWGhcG3jorBIxMi1FULfDptf4wRzwF1Rc1KXJ0kptt8n5WERnhNbqiLUx4+dpLleCz8RlN4ZiiNawRi7/WT3yiZvKTS4rcc/g= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1718955029; c=relaxed/simple; bh=tp/NGE8RxyPHEtfvReImUJ2XG70OLA+d30WQHKc29AY=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=lX6lsCfFEFRvkGx/zVecNSeH+Bd9VIT0femCQe7IJXcqY3oyQDYiXxboP3mrVcwXr/XNWtqsTXzw0jaxtxy76wz8yDUs+TwaJAiXUPb/4oX1uo6YhOXAOhtowY8Ar9fqi0uKyp1Py7GIt2BSpuZXEajwIJHzSbWq1QdoP6qSI9Y= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=none (p=none dis=none) header.from=sang-engineering.com; spf=pass smtp.mailfrom=sang-engineering.com; dkim=pass (2048-bit key) header.d=sang-engineering.com header.i=@sang-engineering.com header.b=mMdbDpmk; arc=none smtp.client-ip=194.117.254.33 Authentication-Results: smtp.subspace.kernel.org; dmarc=none (p=none dis=none) header.from=sang-engineering.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=sang-engineering.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=sang-engineering.com header.i=@sang-engineering.com header.b="mMdbDpmk" DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d= sang-engineering.com; h=from:to:cc:subject:date:message-id :in-reply-to:references:mime-version:content-type :content-transfer-encoding; s=k1; bh=CFQTXPUSMeT7AYVoruD7Npcs4kM +ge+9KCd3MJfEn/4=; b=mMdbDpmkdlmtdIGn7alJWBs9X8lSnmyMDx4wnFpSOv4 INM3gEzf5eKpf+2Q1nveHfi1wm/sgPMcMxlVMHHctox9jqRJYvrR4AWtxhfj0OpW EwJYgl8BTKHBiugU4Si/WV5f13g0jOFI+wKVYv2KLWlY8zM0y6sJEVQ/olHRBdHn V8ivlsHhAbGtuvWO0hwt7OxhX3yUEfMIiBTuSfIkodN3ZOQh+w4G89jAwLWkMAmk VdynEDw05kZLyG85ggoAXwQ9OYH8dRwam38LIXq0UCC40mDnwsd8en4fxp2tYj98 njKfMJqk8ap5Y3pg5NzV/2xZ0EFx9bblN8aatvGAAzQ== Received: (qmail 1279093 invoked from network); 21 Jun 2024 09:30:25 +0200 Received: by mail.zeus03.de with ESMTPSA (TLS_AES_256_GCM_SHA384 encrypted, authenticated); 21 Jun 2024 09:30:25 +0200 X-UD-Smtp-Session: l3s3148p1@3l2jZ2Eb/I8gAwDPXzjQABqqX1QYyOSW From: Wolfram Sang To: linux-kernel@vger.kernel.org Cc: Andi Shyti , Easwar Hariharan , Wolfram Sang , linux-i2c@vger.kernel.org Subject: [PATCH v4 3/6] docs: i2c: summary: update speed mode description Date: Fri, 21 Jun 2024 09:30:10 +0200 Message-ID: <20240621073015.5443-4-wsa+renesas@sang-engineering.com> X-Mailer: git-send-email 2.43.0 In-Reply-To: <20240621073015.5443-1-wsa+renesas@sang-engineering.com> References: <20240621073015.5443-1-wsa+renesas@sang-engineering.com> Precedence: bulk X-Mailing-List: linux-i2c@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Fastest I2C mode is 5 MHz. Update the docs and reword the paragraph slightly. Signed-off-by: Wolfram Sang Reviewed-by: Easwar Hariharan --- Documentation/i2c/summary.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Documentation/i2c/summary.rst b/Documentation/i2c/summary.rst index e3ab1d414014..a1e5c0715f8b 100644 --- a/Documentation/i2c/summary.rst +++ b/Documentation/i2c/summary.rst @@ -3,8 +3,8 @@ Introduction to I2C and SMBus ============================= I²C (pronounce: I squared C and written I2C in the kernel documentation) is -a protocol developed by Philips. It is a slow two-wire protocol (variable -speed, up to 400 kHz), with a high speed extension (3.4 MHz). It provides +a protocol developed by Philips. It is a two-wire protocol with variable +speed (typically up to 400 kHz, high speed modes up to 5 MHz). It provides an inexpensive bus for connecting many types of devices with infrequent or low bandwidth communications needs. I2C is widely used with embedded systems. Some systems use variants that don't meet branding requirements, From patchwork Fri Jun 21 07:30:11 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Wolfram Sang X-Patchwork-Id: 806933 Received: from mail.zeus03.de (zeus03.de [194.117.254.33]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id EB60816C69C for ; Fri, 21 Jun 2024 07:30:27 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=194.117.254.33 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1718955030; cv=none; b=MoMaWBR7gKry7mkTZC9Q2vUZkYHqHOln7mN4uE6hgJm8EjQzAQiKe3RKgRTeQFDKQWIF7arhJ1O5whT4jrJTmYnwFSDBn2NbQDLd8YEspT1FEsYPCqG5xXfc54Wf2OgMfFsN6CoVxme6uN32YyzoCVcXszcADPbt7zKvxrTtNVg= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1718955030; c=relaxed/simple; bh=tH0NOSAY7BDUS/VNB/ZGWgSpJi45DZYDHlrsL1Okdl4=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=QiI1WXZOl/bjdKF3sQDv4nDxhmml9mG6mYTK0v4aHB2xD1AfrNJJ9QowwWmkpjEscaKNsCodVJWyIQd7qtQXVXLKxSuFnJob5FK1fHHaDosY4Pdw0iaGZSjNliGc8Pt9b3uC+z75Xoaj7a9FCiApelpG5XwYY0QRFoHB35lGK4Y= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=none (p=none dis=none) header.from=sang-engineering.com; spf=pass smtp.mailfrom=sang-engineering.com; dkim=pass (2048-bit key) header.d=sang-engineering.com header.i=@sang-engineering.com header.b=N1K8je8b; arc=none smtp.client-ip=194.117.254.33 Authentication-Results: smtp.subspace.kernel.org; dmarc=none (p=none dis=none) header.from=sang-engineering.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=sang-engineering.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=sang-engineering.com header.i=@sang-engineering.com header.b="N1K8je8b" DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d= sang-engineering.com; h=from:to:cc:subject:date:message-id :in-reply-to:references:mime-version:content-transfer-encoding; s=k1; bh=ixLUA05ywsqk+tUJDK/loDg53P2byoU2nyRRhw8H0ik=; b=N1K8je 8bd5zxibUE9olBIun0NZzWz3hEhNAZb5Qya0F7FFstQhIPuMQQ4KI2hz3bc1aDLS dLugnRrgw2mm7TfqWWeun+e7dDMUTNe6e3y2KPBlDCJCOEI3tETodV2ZU+RzxrIA v1bT06waVERZpRg9tFVMtsoGQHzUqmnC/1mOumfH4p+QJUtA4hxjR8nLef/ypLEI 6fnKdPDWHHcOAdB3vFKOexuLjcW/fsG95OBPIfLA4Za48Ra3BWy08GW4UiVaOlkO ne7r34poFXojXa6SJ1EyjIseZAYF2qZWdqCSgfl/M7NyyU48HMj71zN9uRYzcXas APhQIDXgfHSLBQVA== Received: (qmail 1279121 invoked from network); 21 Jun 2024 09:30:25 +0200 Received: by mail.zeus03.de with ESMTPSA (TLS_AES_256_GCM_SHA384 encrypted, authenticated); 21 Jun 2024 09:30:25 +0200 X-UD-Smtp-Session: l3s3148p1@sQawZ2EbBJAgAwDPXzjQABqqX1QYyOSW From: Wolfram Sang To: linux-kernel@vger.kernel.org Cc: Andi Shyti , Easwar Hariharan , Wolfram Sang , linux-i2c@vger.kernel.org Subject: [PATCH v4 4/6] docs: i2c: summary: document use of inclusive language Date: Fri, 21 Jun 2024 09:30:11 +0200 Message-ID: <20240621073015.5443-5-wsa+renesas@sang-engineering.com> X-Mailer: git-send-email 2.43.0 In-Reply-To: <20240621073015.5443-1-wsa+renesas@sang-engineering.com> References: <20240621073015.5443-1-wsa+renesas@sang-engineering.com> Precedence: bulk X-Mailing-List: linux-i2c@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 We now have the updated I2C specs and our own Code of Conduct, so we have all we need to switch over to the inclusive terminology. Define them here. Signed-off-by: Wolfram Sang --- Documentation/i2c/i2c_bus.svg | 15 ++++++++------- Documentation/i2c/summary.rst | 23 +++++++++++++++++------ 2 files changed, 25 insertions(+), 13 deletions(-) diff --git a/Documentation/i2c/i2c_bus.svg b/Documentation/i2c/i2c_bus.svg index 3170de976373..45801de4af7d 100644 --- a/Documentation/i2c/i2c_bus.svg +++ b/Documentation/i2c/i2c_bus.svg @@ -1,5 +1,6 @@ + I2CMaster + id="tspan1285">Controller Slave + id="tspan1287">Target Slave + id="tspan1287-6">Target Slave + id="tspan1287-9">Target X-Patchwork-Id: 806429 Received: from mail.zeus03.de (zeus03.de [194.117.254.33]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 07B8616D4CA for ; Fri, 21 Jun 2024 07:30:28 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=194.117.254.33 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1718955030; cv=none; b=WHsCmSzyRm3DXgkVMaSYTJzsd0FJSa9/yXrKD/lyX53VnhfZ9F0Ge0qhl74tpKds9opr+NuG8zSwkMpbFm2xSR6HBoIm4itP0SP02w4TN6s1hnBqJ1AQShVO/k/BEstDatCPT/julp27DrLIpaAvFZzaViBaGSCsjSUgz8WFXD4= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1718955030; c=relaxed/simple; bh=rDqQbB8WtLI0sNUuiLmLKSokCC9jWiu+CRLfqoeNG94=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=MjyDqQVBjsA4Y4x2lw48H5CIgVrPA28cx24mI0ZFGM7TWTMhds5kK+NHJRddv/ywJujq1agHdevOHnN/aHjfPDfYxV4MkULj6RwF8Ui8n34dfGpJ3wQRbvR6EwAU1kvHkfCa+VbGeuNSIudKyeGBhpJRu2dyhCPwM2zeXjcsBA0= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=none (p=none dis=none) header.from=sang-engineering.com; spf=pass smtp.mailfrom=sang-engineering.com; dkim=pass (2048-bit key) header.d=sang-engineering.com header.i=@sang-engineering.com header.b=AJitrd3c; arc=none smtp.client-ip=194.117.254.33 Authentication-Results: smtp.subspace.kernel.org; dmarc=none (p=none dis=none) header.from=sang-engineering.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=sang-engineering.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=sang-engineering.com header.i=@sang-engineering.com header.b="AJitrd3c" DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d= sang-engineering.com; h=from:to:cc:subject:date:message-id :in-reply-to:references:mime-version:content-transfer-encoding; s=k1; bh=X8SjZrtr7vYauQzzWhyTb2doGzFDtsUQAd4VY9QcFf4=; b=AJitrd 3cWXG4yRPQpFSvpRs5EZ4klDtvdbmQ0+FSIW7qGhVXS7fJrh1yILhu6PiqszhHiS mYVX2DrmJ6XjWCqaQ/O6s2sXfX9aEC2VRtsZ7bEmr70yTLU6SSEevPZWdoRp5ULw HIKoKJ9DxTwq91k0g9cJiOgqWVMYp45Ong4stOdOtuqT250snO30SXW2ePX5ToMe lwMGS9lZb9kGjHbkzN8xbXMa2LrA3wjmyVBZMBa8QVcMGasLCs2L8Xd2Frx9qLUD c960g8LEZUfz2XKdKJS5YXm+cwsTnBcnFsvt7bt4pWx9Ay5FXx41yDEJloa5axPD fAsr0U/6ib8KvIfA== Received: (qmail 1279150 invoked from network); 21 Jun 2024 09:30:26 +0200 Received: by mail.zeus03.de with ESMTPSA (TLS_AES_256_GCM_SHA384 encrypted, authenticated); 21 Jun 2024 09:30:26 +0200 X-UD-Smtp-Session: l3s3148p1@Zia8Z2EbDJAgAwDPXzjQABqqX1QYyOSW From: Wolfram Sang To: linux-kernel@vger.kernel.org Cc: Andi Shyti , Easwar Hariharan , Wolfram Sang , linux-i2c@vger.kernel.org Subject: [PATCH v4 5/6] docs: i2c: summary: document 'local' and 'remote' targets Date: Fri, 21 Jun 2024 09:30:12 +0200 Message-ID: <20240621073015.5443-6-wsa+renesas@sang-engineering.com> X-Mailer: git-send-email 2.43.0 In-Reply-To: <20240621073015.5443-1-wsa+renesas@sang-engineering.com> References: <20240621073015.5443-1-wsa+renesas@sang-engineering.com> Precedence: bulk X-Mailing-List: linux-i2c@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Because Linux can be a target as well, add terminology to differentiate between Linux being the target and Linux accessing targets. Signed-off-by: Wolfram Sang Reviewed-by: Easwar Hariharan --- Documentation/i2c/summary.rst | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/Documentation/i2c/summary.rst b/Documentation/i2c/summary.rst index a6da1032fa06..ff8bda32b9c3 100644 --- a/Documentation/i2c/summary.rst +++ b/Documentation/i2c/summary.rst @@ -49,10 +49,15 @@ 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 **target** chip is a node that responds to communications when addressed -by the controller. 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 +A **target** chip is a node that responds to communications when addressed by a +controller. In the Linux kernel implementation it is called a **client**. While +targets are usually separate external chips, Linux can also act as a target +(needs hardware support) and respond to another controller on the bus. This is +then called a **local target**. In contrast, an external chip is called a +**remote target**. + +Target drivers are kept in a directory specific to the feature they provide, +for example ``drivers/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 From patchwork Fri Jun 21 07:30:13 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Wolfram Sang X-Patchwork-Id: 806932 Received: from mail.zeus03.de (zeus03.de [194.117.254.33]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 184DA16B743 for ; Fri, 21 Jun 2024 07:30:34 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=194.117.254.33 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1718955036; cv=none; b=r23LDEdt+PssnlugBnkZmmo2ze5zEw/Wa+ufHFjdxyn6aDdiTkRfUp42H0y8xd8fWqRwAp6pXpZeNiTPPyTuE3vpwd1JLg7IEyI+6i1OZMwujVHn3bhtZDbjN10yg/17S+pCRj/Xaq86WN/U5729hjuBmba1mbYIAj8RdWaAqbw= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1718955036; c=relaxed/simple; bh=X8INLkskdkYTHO9nLO+bqJ3aacRr5rFB23PLTToBN9k=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=AYs8sWyp2jakxpVZdz2nWMjAI2GRuqNgotDJAM7sdzAMgLAtjhf8kzb1RrHliqMN/9Op2WpwUtIrj3JWLqqnzPkYYDLeRXlm3Umjop+JpPqjlOoYJZAXwj3Gttj+r83XAtlpyT+I0M/drmD1xq1Cv0E5jpvNm4wVAcafazIMWAY= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=none (p=none dis=none) header.from=sang-engineering.com; spf=pass smtp.mailfrom=sang-engineering.com; dkim=pass (2048-bit key) header.d=sang-engineering.com header.i=@sang-engineering.com header.b=ZxXVfpDa; arc=none smtp.client-ip=194.117.254.33 Authentication-Results: smtp.subspace.kernel.org; dmarc=none (p=none dis=none) header.from=sang-engineering.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=sang-engineering.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=sang-engineering.com header.i=@sang-engineering.com header.b="ZxXVfpDa" DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d= sang-engineering.com; h=from:to:cc:subject:date:message-id :in-reply-to:references:mime-version:content-transfer-encoding; s=k1; bh=DWqmJaYmk7gfwFyT7gufw56IyMYdyCsAGXbbSjiY3n0=; b=ZxXVfp Da1ik4V4mvkkHeHMjxdeMRcprHpBymgYHmxAAjWaGePsGR6z26V/SH8U9SMz3B63 rLYcn9+qsLZK8fnurJxK6FYSKx6WyAz7z9ztlAY0WSHPP/ATNBl125RKjnD8o4i7 kvJYKanq6GEWKxj9X90/cjCn69QYqiRAQd/cDKujxQMMVT+QwiyhveBM/u3x6nzE Z6gcSPWOa4d4aplRSRGPAf0GhC7EsCYuT6cXFN/W1gJeNdikaP9D+hpW2oVlXthF zttPYVnZvijhDwwZC6ZWn8im6PpmBAMPV/mhOzVOZyPLg6JwjIh/4+8ArgcNAnlQ ArMHLjLWw283xi3Q== Received: (qmail 1279191 invoked from network); 21 Jun 2024 09:30:32 +0200 Received: by mail.zeus03.de with ESMTPSA (TLS_AES_256_GCM_SHA384 encrypted, authenticated); 21 Jun 2024 09:30:32 +0200 X-UD-Smtp-Session: l3s3148p1@2mPHZ2EbFpAgAwDPXzjQABqqX1QYyOSW From: Wolfram Sang To: linux-kernel@vger.kernel.org Cc: Andi Shyti , Easwar Hariharan , Wolfram Sang , linux-i2c@vger.kernel.org Subject: [PATCH v4 6/6] docs: i2c: summary: be clearer with 'controller/target' and 'adapter/client' pairs Date: Fri, 21 Jun 2024 09:30:13 +0200 Message-ID: <20240621073015.5443-7-wsa+renesas@sang-engineering.com> X-Mailer: git-send-email 2.43.0 In-Reply-To: <20240621073015.5443-1-wsa+renesas@sang-engineering.com> References: <20240621073015.5443-1-wsa+renesas@sang-engineering.com> Precedence: bulk X-Mailing-List: linux-i2c@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 This not only includes rewording, but also where to put which emphasis on terms in this document. Signed-off-by: Wolfram Sang --- Documentation/i2c/summary.rst | 41 ++++++++++++++++++++--------------- 1 file changed, 24 insertions(+), 17 deletions(-) diff --git a/Documentation/i2c/summary.rst b/Documentation/i2c/summary.rst index ff8bda32b9c3..579a1c7df200 100644 --- a/Documentation/i2c/summary.rst +++ b/Documentation/i2c/summary.rst @@ -31,9 +31,7 @@ implement all the common SMBus protocol semantics or messages. Terminology =========== -The I2C bus connects one or more *controller* chips and one or more *target* -chips. - +The I2C bus connects one or more controller chips and one or more target chips. .. kernel-figure:: i2c_bus.svg :alt: Simple I2C bus with one controller and 3 targets @@ -41,28 +39,37 @@ chips. Simple I2C bus A **controller** chip is a node that starts communications with targets. In the -Linux kernel implementation it is called an **adapter** or bus. Adapter -drivers are in the ``drivers/i2c/busses/`` subdirectory. +Linux kernel implementation it is also called an "adapter" or "bus". Controller +drivers are usually in the ``drivers/i2c/busses/`` subdirectory. -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. +An **algorithm** contains general code that can be used to implement a whole +class of I2C controllers. Each specific controller driver either depends on an +algorithm driver in the ``drivers/i2c/algos/`` subdirectory, or includes its +own implementation. A **target** chip is a node that responds to communications when addressed by a -controller. In the Linux kernel implementation it is called a **client**. While -targets are usually separate external chips, Linux can also act as a target -(needs hardware support) and respond to another controller on the bus. This is -then called a **local target**. In contrast, an external chip is called a -**remote target**. +controller. In the Linux kernel implementation it is also called a "client". +While targets are usually separate external chips, Linux can also act as a +target (needs hardware support) and respond to another controller on the bus. +This is then called a **local target**. In contrast, an external chip is called +a **remote target**. Target drivers are kept in a directory specific to the feature they provide, for example ``drivers/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). +For the example configuration in the figure above, you will need one driver for +the I2C controller, and drivers for your I2C targets. Usually one driver for +each target. + +Synonyms +-------- + +As mentioned above, the Linux I2C implementation historically uses the terms +"adapter" for controller and "client" for target. A number of data structures +have these synonyms in their name. So, when discussing implementation details, +you should be aware of these terms as well. The official wording is preferred, +though. Outdated terminology --------------------