module: Introduce sc_pll driver module

The PLLs in both the Morello and N1SDP platforms are Silicon
Creations-provided IPs and are present as product-specific
modules within the each product.

Generalise the Silicon Creations PLL driver by making it a
common SCP driver module. The private PLL module(s) and
references to them will be removed from the N1SDP and
Morello products in the imminent commits.

Signed-off-by: Vishnu Satheesh <[email protected]>
Change-Id: Icec8342036f02f424b809e50faa20aaf0534ad6c

module/CMakeLists.txt

@@ -1,6 +1,6 @@
 #
 # Arm SCP/MCP Software
-# Copyright (c) 2021-2023, Arm Limited and Contributors. All rights reserved.
+# Copyright (c) 2021-2024, Arm Limited and Contributors. All rights reserved.
 #
 # SPDX-License-Identifier: BSD-3-Clause
 #
@@ -75,6 +75,7 @@ list(APPEND SCP_MODULE_PATHS "${CMAKE_CURRENT_SOURCE_DIR}/scmi_sensor_req")
 list(APPEND SCP_MODULE_PATHS "${CMAKE_CURRENT_SOURCE_DIR}/scmi_system_power")
 list(APPEND SCP_MODULE_PATHS "${CMAKE_CURRENT_SOURCE_DIR}/scmi_system_power_req")
 list(APPEND SCP_MODULE_PATHS "${CMAKE_CURRENT_SOURCE_DIR}/scmi_voltage_domain")
+list(APPEND SCP_MODULE_PATHS "${CMAKE_CURRENT_SOURCE_DIR}/sc_pll")
 list(APPEND SCP_MODULE_PATHS "${CMAKE_CURRENT_SOURCE_DIR}/sds")
 list(APPEND SCP_MODULE_PATHS "${CMAKE_CURRENT_SOURCE_DIR}/sensor")
 list(APPEND SCP_MODULE_PATHS "${CMAKE_CURRENT_SOURCE_DIR}/sensor_smcf_drv")

module/sc_pll/CMakeLists.txt

@@ -0,0 +1,19 @@
+#
+# Arm SCP/MCP Software
+# Copyright (c) 2024, Arm Limited and Contributors. All rights reserved.
+#
+# SPDX-License-Identifier: BSD-3-Clause
+#
+add_library(${SCP_MODULE_TARGET} SCP_MODULE)
+
+target_include_directories(${SCP_MODULE_TARGET}
+                           PUBLIC "${CMAKE_CURRENT_SOURCE_DIR}/include")
+
+target_include_directories(
+    ${SCP_MODULE_TARGET} PRIVATE "${CMAKE_CURRENT_SOURCE_DIR}/include/internal")
+
+target_sources(${SCP_MODULE_TARGET}
+               PRIVATE "${CMAKE_CURRENT_SOURCE_DIR}/src/mod_sc_pll.c")
+
+target_link_libraries(${SCP_MODULE_TARGET} PRIVATE module-clock
+                                                   module-power-domain)

module/sc_pll/Module.cmake

@@ -0,0 +1,10 @@
+#
+# Arm SCP/MCP Software
+# Copyright (c) 2024, Arm Limited and Contributors. All rights reserved.
+#
+# SPDX-License-Identifier: BSD-3-Clause
+#
+
+set(SCP_MODULE "sc-pll")
+
+set(SCP_MODULE_TARGET "module-sc-pll")

module/sc_pll/include/internal/sc_pll.h

@@ -0,0 +1,57 @@
+/*
+ * Arm SCP/MCP Software
+ * Copyright (c) 2024, Arm Limited and Contributors. All rights reserved.
+ *
+ * SPDX-License-Identifier: BSD-3-Clause
+ *
+ * Description:
+ *      SC PLL register definitions
+ */
+
+#ifndef INTERNAL_SC_PLL_H
+#define INTERNAL_SC_PLL_H
+
+#include <fwk_macros.h>
+
+/* PLL Control Register 0 bit positions. */
+#define PLL_HARD_BYPASS_BIT_POS     0
+#define PLL_PD_TIMER_BYPASS_BIT_POS 1
+#define PLL_LOCK_SEL_BIT_POS        2
+#define PLL_DSMEN_BIT_POS           4
+#define PLL_DACEN_BIT_POS           5
+#define PLL_BYPASS_POS              6
+#define PLL_FBDIV_BIT_POS           8
+#define PLL_REFDIV_POS              20
+#define PLL_PLLEN_POS               31
+
+/* PLL Control Register 1 bit positions. */
+#define PLL_FRAC_POS        0
+#define PLL_POSTDIV1_POS    24
+#define PLL_POSTDIV2_POS    28
+#define PLL_LOCK_STATUS_POS 31
+
+/*! The minimum reference frequency post REFDIV stage */
+#define MOD_SC_PLL_REF_MIN (2UL * FWK_MHZ)
+
+/*! The maximum reference frequency post REFDIV stage */
+#define MOD_SC_PLL_REF_MAX (1200UL * FWK_MHZ)
+
+/*! Step size for the PLL. */
+#define MOD_SC_PLL_STEP_SIZE UINT64_C(1000)
+
+/*! The minimum feedback divider value */
+#define MOD_SC_PLL_FBDIV_MIN 16
+/*! The maximum feedback divider value */
+#define MOD_SC_PLL_FBDIV_MAX 1600
+
+/*! The minimum frequency output that post divider requires. */
+#define MOD_SC_PLL_FVCO_MIN (800UL * FWK_MHZ)
+/*! The maximum frequency output that post divider handles. */
+#define MOD_SC_PLL_FVCO_MAX (3200UL * FWK_MHZ)
+
+/*! The minimum reference clock divider value */
+#define MOD_SC_PLL_REFDIV_MIN 1
+/*! The maximum reference clock divider value */
+#define MOD_SC_PLL_REFDIV_MAX 63
+
+#endif /* INTERNAL_SC_PLL_H */

module/sc_pll/include/mod_sc_pll.h

@@ -0,0 +1,106 @@
+/*
+ * Arm SCP/MCP Software
+ * Copyright (c) 2024, Arm Limited and Contributors. All rights reserved.
+ *
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+
+#ifndef MOD_SC_PLL_H
+#define MOD_SC_PLL_H
+
+#include <fwk_element.h>
+#include <fwk_id.h>
+#include <fwk_macros.h>
+#include <fwk_module.h>
+
+#include <stdbool.h>
+#include <stddef.h>
+#include <stdint.h>
+
+/*!
+ * \addtogroup GroupSCModule Silicon Creations (SC) Product Modules
+ * \{
+ */
+
+/*!
+ * \defgroup GroupSC_PLL SC PLL Driver
+ *
+ * \details A driver for PLL hardware in Silicon Creations (SC) product.
+ *
+ * \{
+ */
+
+/*! Timeout value to wait for a PLL to lock. */
+#define MOD_SC_PLL_LOCK_TIMEOUT UINT32_C(0x100)
+
+/*! Indexes of APIs that the module offers for binding. */
+enum mod_sc_pll_api_types {
+    MOD_SC_PLL_API_TYPE_DEFAULT,
+    MOD_SC_PLL_API_COUNT,
+};
+
+static const fwk_id_t mod_sc_pll_api_id_pll =
+    FWK_ID_API_INIT(FWK_MODULE_IDX_SC_PLL, MOD_SC_PLL_API_TYPE_DEFAULT);
+
+/*!
+ * \brief PLL Parameters.
+ */
+struct mod_sc_pll_dev_param {
+    /*! The minimum post divider 1 value */
+    const uint8_t postdiv1_min;
+    /*! The maximum post divider 1 value */
+    const uint8_t postdiv1_max;
+    /*! The minimum post divider 2 value */
+    const uint8_t postdiv2_min;
+    /*! The maximum post divider 2 value */
+    const uint8_t postdiv2_max;
+    /*! The minimum frequency that the PLL hardware can output. */
+    const uint64_t pll_rate_min;
+    /*! The maximum frequency that the PLL hardware can output. */
+    const uint64_t pll_rate_max;
+};
+
+/*!
+ * \brief PLL device configuration.
+ */
+struct mod_sc_pll_dev_config {
+    /*! Pointer to the PLL's control register 0. */
+    volatile uint32_t *const control_reg0;
+
+    /*! Pointer to the PLL's control register 1. */
+    volatile uint32_t *const control_reg1;
+
+    /*! The initial rate the PLL is set to during initialization. */
+    const uint64_t initial_rate;
+
+    /*!
+     * The frequency of the reference clock applied to the PLL. Each PLL
+     * instance has a dedicated reference clock input configured through
+     * the board controller and the same value should be used in module's
+     * element configuration table. This value will be multiplied with a
+     * multiplication factor by the PLL to generate the required output
+     * frequency.
+     */
+    const uint64_t ref_rate;
+
+    /*!
+     * If \c true, the driver will not attempt to set a default frequency, or
+     * to otherwise configure the PLL during the pre-runtime phase. The PLL is
+     * expected to be initialized later in response to a notification or other
+     * event.
+     */
+    const bool defer_initialization;
+
+    /*! PLL Device Parameters used to configure it during init time */
+    struct mod_sc_pll_dev_param *dev_param;
+};
+
+/*!
+ * \}
+ */
+
+/*!
+ * \}
+ */
+
+#endif /* MOD_SC_PLL_H */