Add some documentation outlining the two CCF ports in U-Boot as well as documentatig the limitations of CCF_FULL with respect to SPL and pre-reloc support.
Signed-off-by: Casey Connolly <[email protected]> --- doc/api/clk.rst | 25 +++++++++++++++++++++++++ doc/develop/ccf.rst | 35 +++++++++++++++++++++++++++++++++++ doc/develop/index.rst | 1 + 3 files changed, 61 insertions(+) diff --git a/doc/api/clk.rst b/doc/api/clk.rst index 7c27066928e5..bce58cebef54 100644 --- a/doc/api/clk.rst +++ b/doc/api/clk.rst @@ -16,4 +16,29 @@ Driver API ---------- .. kernel-doc:: include/clk-uclass.h :internal: + +Common Clock Framework +---------------------- + +U-Boot includes optional support for the `Linux Common Clock Framework <https://www.kernel.org/doc/Documentation/clk.txt>`_ +in two forms: + +IMX U-Boot CCF +^^^^^^^^^^^^^^ + +Basic support for managing the clock tree, using per-clock ops, propagating rate change requests, and using common +divider/mux/gate clocks is provided by the earlier ``uCCF`` or ``U-Boot CCF``, it uses ``UCLASS_CLK`` and the associated +:c:struct:`clk_ops_uboot`. The clock tree itself is tracked through U-Boot driver model as each clock has a single ``udevice``. + +This is described in more detail in `The IMX CCF document <https://source.denx.de/u-boot/u-boot/-/blob/master/doc/imx/clk/ccf.txt>`_. + +CCF Full Port +^^^^^^^^^^^^^ + +The second version of CCF (*CCF Full*) focuses on maintaining compatibility with the Linux API. It introduces the +typical ``struct clk_hw`` and other expected functionality. Clocks are tracked by the CCF core rather than through the driver model. This +port uses ``struct clk_ops`` and allows drivers of any uclass to register clocks. This greatly simplifies the process of porting +devices that like some phy's which also provide clocks, as it removes the need to declare an additional ``U_BOOT_DRIVER`` for uclass clk. + +:doc:`More information, recommendations, and limitations of CCF Full </develop/ccf>` diff --git a/doc/develop/ccf.rst b/doc/develop/ccf.rst new file mode 100644 index 000000000000..d910ed44218f --- /dev/null +++ b/doc/develop/ccf.rst @@ -0,0 +1,35 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Linux Common Clock Framework +============================ + +U-Boot includes an API-compatible port of the Linux CCF. This replaces the traditional +``UCLASS_CLK`` and aims to simplify platform bringup by allowing straightforward reuse +of existing Linux drivers. + +As a result, there are some important limitations when it comes to using CCF: + +1. It is NOT possible to combine CCF clocks with ``UCLASS_CLK`` since neither is aware + of the other. When CCF is enabled, the CCF drivers will be used for fixed clocks and + the typical ``clk_*`` functions will only work with CCF clocks, essentially making + clock drivers that use ``UCLASS_CLK`` unusable. +2. CCF clocks can't currently be used pre-relocation. CCF expects to manage the entire + clock tree (and must in order to properly calculate clock rates) so while it would + be possible to probe only the minimum necessary clocks pre-reloc that can still be + a lot of associated clock provider logic. + There isn't today an ideal solution for this other than minimising/removing the use + of driver pre-relocation and relying on earlier bootloader stages to set up the UART. +3. Similarly, CCF currently isn't supported in SPL although it could be enabled if there + is enough malloc space available and dcache is enabled. It may be desirable to add + a mechanism for only supporting a subset of clocks and providing "stubs" for parent + clocks that are already configured to a good known rate. + +Porting Linux Clock Drivers +--------------------------- + +By remaining as close as possible to the Linux API, the process of porting Linux clock +drivers is fairly straightforward. The Qualcomm CCF drivers in ``drivers/clk/qcom/ccf/`` +can be used as an example. + +Predominantly, ``UCLASS_CLK`` should NOT be used, instead clock controller drivers should +use ``UCLASS_NOP`` or another appropriate uclass. diff --git a/doc/develop/index.rst b/doc/develop/index.rst index 3c044e679274..382de45221c9 100644 --- a/doc/develop/index.rst +++ b/doc/develop/index.rst @@ -32,8 +32,9 @@ Implementation directories bloblist bootstd/index + ccf ci_testing commands config_binding cyclic -- 2.55.0
