From 27600805e62f800bacf990354632eae4e487d34c Mon Sep 17 00:00:00 2001 From: Yazen Ghannam Date: Thu, 3 Sep 2026 10:43:25 -0500 Subject: x86/amd_node: Fix PCI device reference counting in amd_smn_init() The local "root" pointer is a temporary variable used during the device search. Therefore, refcount related to the search iterators should be cleaned up after the search is complete. Use the __free() cleanup macro to ensure the refcount is decremented when the temporary pointer goes out of scope. Additionally, increment the refcount when caching a root pointer. This ensures the in-use refcount is separate from the temporary search refcounting. Finally, drop the redundant "root = NULL" before the second search loop. The pci_get_class() iterator always decrements the refcount of its "from" argument, so the first loop can only fall through with "root" already NULL. Fixes: 0a4b61d9c2e4 ("x86/amd_node: Fix AMD root device caching") Closes: https://sashiko.dev/#/patchset/20260806160159.230453-1-jason.andryuk%40amd.com Reported-by: Sashiko Assisted-by: LLM Signed-off-by: Yazen Ghannam Signed-off-by: Borislav Petkov (AMD) Reviewed-by: Mario Limonciello (AMD) Cc: Link: https://patch.msgid.link/20260903154325.74343-1-yazen.ghannam@amd.com --- Documentation/i2c/summary.rst | 82 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 82 insertions(+) create mode 100644 Documentation/i2c/summary.rst (limited to 'Documentation/i2c/summary.rst') diff --git a/Documentation/i2c/summary.rst b/Documentation/i2c/summary.rst new file mode 100644 index 000000000..579a1c7df --- /dev/null +++ b/Documentation/i2c/summary.rst @@ -0,0 +1,82 @@ +============================= +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 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, +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 `"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 +SMBus, but some SMBus protocols add semantics beyond what is required to +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 +meet both SMBus and I2C electrical constraints; and others which can't +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. + +.. kernel-figure:: i2c_bus.svg + :alt: Simple I2C bus with one controller and 3 targets + + Simple I2C bus + +A **controller** chip is a node that starts communications with targets. In the +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 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 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 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 +-------------------- + +In earlier I2C specifications, controller was named "master" and target was +named "slave". These terms have been obsoleted with v7 of the specification and +their use is also discouraged by the Linux Kernel Code of Conduct. You may +still find them in references to documentation which has not been updated. The +general attitude, however, is to use the inclusive terms: controller and +target. Work to replace the old terminology in the Linux Kernel is on-going. -- cgit v1.3.1