1.. SPDX-License-Identifier: GPL-2.0+
2.. (C) Copyright 2020
3.. Texas Instruments Incorporated - http://www.ti.com/
4
5SOC ID Framework
6================
7
8Introduction
9------------
10
11The driver-model SOC ID framework is able to provide identification
12information about a specific SoC in use at runtime, and also provide matching
13from a set of identification information from an array. This can be useful for
14enabling small quirks in drivers that exist between SoC variants that are
15impractical to implement using device tree flags. It is based on UCLASS_SOC.
16
17UCLASS_SOC:
18  - drivers/soc/soc-uclass.c
19  - include/soc.h
20
21Configuration:
22  - CONFIG_SOC_DEVICE is selected by drivers as needed.
23
24Implementing a UCLASS_SOC provider
25----------------------------------
26
27The purpose of this framework is to allow UCLASS_SOC provider drivers to supply
28identification information about the SoC in use at runtime. The framework
29allows drivers to define soc_ops that return identification strings.  All
30soc_ops need not be defined and can be left as NULL, in which case the
31framework will return -ENOSYS and not consider the value when doing an
32soc_device_match.
33
34It is left to the driver implementor to decide how the information returned is
35determined, but in general the same SOC should always return the same set of
36identifying information. Information returned must be in the form of a NULL
37terminated string.
38
39See include/soc.h for documentation of the available soc_ops and the intended
40meaning of the values that can be returned. See drivers/soc/soc_sandbox.c for
41an example UCLASS_SOC provider driver.
42
43Using a UCLASS_SOC driver
44-------------------------
45
46The framework provides the ability to retrieve and use the identification
47strings directly. It also has the ability to return a match from a list of
48different sets of SoC data using soc_device_match.
49
50An array of 'struct soc_attr' can be defined, each containing ID information
51for a specific SoC, and when passed to soc_device_match, the identifier values
52for each entry in the list will be compared against the values provided by the
53UCLASS_SOC driver that is in use. The first entry in the list that matches all
54non-null values will be returned by soc_device_match.
55
56An example of various uses of the framework can be found at test/dm/soc.c.
57
58Describing the device using device tree
59---------------------------------------
60
61.. code-block:: none
62
63   chipid: chipid {
64        compatible = "sandbox,soc";
65   };
66
67All that is required in a DT node is a compatible for a corresponding
68UCLASS_SOC driver.
69