doc/imx/clk/ccf.txt

   1 Introduction:
   2 =============
   3
   4 This documentation entry describes the Common Clock Framework [CCF]
   5 port from Linux kernel (v5.1.12) to U-Boot.
   6
   7 This code is supposed to bring CCF to IMX based devices (imx6q, imx7
   8 imx8). Moreover, it also provides some common clock code, which would
   9 allow easy porting of CCF Linux code to other platforms.
  10
  11 Design decisions:
  12 =================
  13
  14 * U-Boot's driver model [DM] for clk differs from Linux CCF. The most
  15   notably difference is the lack of support for hierarchical clocks and
  16   "clock as a manager driver" (single clock DTS node acts as a starting
  17   point for all other clocks).
  18
  19 * The clk_get_rate() caches the previously read data if CLK_GET_RATE_NOCACHE
  20   is not set (no need for recursive access).
  21
  22 * On purpose the "manager" clk driver (clk-imx6q.c) is not using large
  23   table to store pointers to clocks - e.g. clk[IMX6QDL_CLK_USDHC2_SEL] = ....
  24   Instead we use udevice's linked list for the same class (UCLASS_CLK).
  25
  26   Rationale:
  27   ----------
  28     When porting the code as is from Linux, one would need ~1KiB of RAM to
  29     store it. This is way too much if we do plan to use this driver in SPL.
  30
  31 * The "central" structure of this patch series is struct udevice and its
  32   uclass_priv field contains the struct clk pointer (to the originally created
  33   one).
  34
  35 * Up till now U-Boot's driver model (DM) CLK operates on udevice (main
  36   access to clock is by udevice ops)
  37   In the CCF the access to struct clk (embodying pointer to *dev) is
  38   possible via dev_get_clk_ptr() (it is a wrapper on dev_get_uclass_priv()).
  39
  40 * To keep things simple the struct udevice's uclass_priv pointer is used to
  41   store back pointer to corresponding struct clk. However, it is possible to
  42   modify clk-uclass.c file and add there struct uc_clk_priv, which would have
  43   clock related members (like pointer to clk). As of this writing there is no
  44   such need, so to avoid extra allocations (as it can be auto allocated by
  45   setting .per_device_auto_alloc_size = sizeof(struct uc_clk_priv)) the
  46   uclass_priv stores the pointer to struct clk.
  47
  48 * It is advised to add common clock code (like already added rate and flags) to
  49   the struct clk, which is a top level description of the clock.
  50
  51 * U-Boot's driver model already provides the facility to automatically allocate
  52   (via private_alloc_size) device private data (accessible via dev->priv).
  53   It may look appealing to use this feature to allocate private structures for
  54   CCF clk devices e.g. divider (struct clk_divider *divider) for IMX6Q clock.
  55
  56   The above feature had not been used for following reasons:
  57   - The original CCF Linux kernel driver is the "manager" for clocks - it
  58     decides when clock is instantiated (and when memory for it is allocated).
  59
  60   - Using it would change the original structure of the CCF code.
  61
  62   - To bind (via clk_register()) the clock device with U-Boot driver model we
  63     first need udevice for it (the "chicken and egg problem").
  64
  65 * I've added the clk_get_parent(), which reads parent's dev->uclass_priv to
  66   provide parent's struct clk pointer. This seems the easiest way to get
  67   child/parent relationship for struct clk in U-Boot's udevice based clocks.
  68
  69 * Linux's CCF 'struct clk_core' corresponds to U-Boot's udevice in 'struct clk'.
  70   Clock IP block agnostic flags from 'struct clk_core' (e.g. NOCACHE) have been
  71   moved from this struct one level up to 'struct clk'.
  72
  73 * For tests the new ./test/dm/clk_ccf.c and ./drivers/clk/clk_sandbox_ccf.c
  74   files have been introduced. The latter setups the CCF clock structure for
  75   sandbox by reusing, if possible, generic clock primitives - like divier
  76   and mux. The former file provides code to tests this setup.
  77
  78   For sandbox new CONFIG_SANDBOX_CLK_CCF Kconfig define has been introduced.
  79   All new primitives added for new architectures must have corresponding test
  80   in the two aforementioned files.
  81
  82
  83 Testing (sandbox):
  84 ==================
  85
  86 make mrproper; make sandbox_defconfig; make -j4
  87 ./u-boot -i -d arch/sandbox/dts/test.dtb
  88 => ut dm clk
  89
  90 or in a more "scriptable" way (with -v to print debug output):
  91 ./u-boot --fdt arch/sandbox/dts/test.dtb --command "ut dm clk_ccf" -v
  92
  93 To do:
  94 ------
  95
  96 * Use of OF_PLATDATA in the SPL setup for CCF - as it is now - the SPL grows
  97   considerably and using CCF in boards with tiny resources (OCRAM) is
  98   problematic.
  99
 100 * On demand port other parts of CCF to U-Boot - as now only features _really_
 101   needed by DM/DTS converted drivers are used.