doc/driver-model/soc-framework.rst

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