From mboxrd@z Thu Jan 1 00:00:00 1970 From: Dave Gerlach Date: Wed, 15 Jul 2020 23:39:56 -0500 Subject: [PATCH v2 1/9] doc: Add new doc for soc ID driver model In-Reply-To: <20200716044004.6014-1-d-gerlach@ti.com> References: <20200716044004.6014-1-d-gerlach@ti.com> Message-ID: <20200716044004.6014-2-d-gerlach@ti.com> List-Id: MIME-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit To: u-boot@lists.denx.de Add a new documentation file for UCLASS_SOC and its usage to describe the SoC Device ID framework that allows SoC identification and device data matching. Signed-off-by: Dave Gerlach --- doc/driver-model/index.rst | 1 + doc/driver-model/soc-framework.rst | 68 ++++++++++++++++++++++++++++++ 2 files changed, 69 insertions(+) create mode 100644 doc/driver-model/soc-framework.rst diff --git a/doc/driver-model/index.rst b/doc/driver-model/index.rst index b9df221627e2..f17c72ce69d8 100644 --- a/doc/driver-model/index.rst +++ b/doc/driver-model/index.rst @@ -19,5 +19,6 @@ Driver Model pmic-framework remoteproc-framework serial-howto + soc-framework spi-howto usb-info diff --git a/doc/driver-model/soc-framework.rst b/doc/driver-model/soc-framework.rst new file mode 100644 index 000000000000..2609fda64421 --- /dev/null +++ b/doc/driver-model/soc-framework.rst @@ -0,0 +1,68 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. (C) Copyright 2020 +.. Texas Instruments Incorporated - http://www.ti.com/ + +SOC ID Framework +================ + +Introduction +------------ + +The driver-model SOC ID framework is able to provide identification +information about a specific SoC in use at runtime, and also provide matching +from a set of identification information from an array. This can be useful for +enabling small quirks in drivers that exist between SoC variants that are +impractical to implement using device tree flags. It is based on UCLASS_SOC. + +UCLASS_SOC: + - drivers/soc/soc-uclass.c + - include/soc.h + +Configuration: + - CONFIG_SOC_DEVICE is selected by drivers as needed. + +Implementing a UCLASS_SOC provider +---------------------------------- + +The purpose of this framework is to allow UCLASS_SOC provider drivers to supply +identification information about the SoC in use at runtime. The framework +allows drivers to define soc_ops that return identification strings. All +soc_ops need not be defined and can be left as NULL, in which case the +framework will return -ENOSYS and not consider the value when doing an +soc_device_match. + +It is left to the driver implementor to decide how the information returned is +determined, but in general the same SOC should always return the same set of +identifying information. Information returned must be in the form of a NULL +terminated string. + +See include/soc.h for documentation of the available soc_ops and the intended +meaning of the values that can be returned. See drivers/soc/soc_sandbox.c for +an example UCLASS_SOC provider driver. + +Using a UCLASS_SOC driver +------------------------- + +The framework provides the ability to retrieve and use the identification +strings directly. It also has the ability to return a match from a list of +different sets of SoC data using soc_device_match. + +An array of 'struct soc_attr' can be defined, each containing ID information +for a specific SoC, and when passed to soc_device_match, the identifier values +for each entry in the list will be compared against the values provided by the +UCLASS_SOC driver that is in use. The first entry in the list that matches all +non-null values will be returned by soc_device_match. + +An example of various uses of the framework can be found at test/dm/soc.c. + +Describing the device using device tree +--------------------------------------- + +.. code-block:: none + + chipid: chipid { + compatible = "sandbox,soc"; + }; + +All that is required in a DT node is a compatible for a corresponding +UCLASS_SOC driver. -- 2.20.1