include: zephyr: drivers: gic: Deprecate GIC_NUM_CPU_IF

Deprecate GIC_NUM_CPU_IF that is not used in-tree and for which
one should already use CONFIG_MP_MAX_NUM_CPUS.

While at it, provide a Doxygen formatted description for this
deprecated macro.

Signed-off-by: Etienne Carriere <etienne.carriere@st.com>

Author: etienne-lms

doc/releases/migration-guide-4.5.rst

@@ -373,6 +373,9 @@ Interrupt Controllers
   ``DT_INST_IRQ(n, sense)`` or ``DT_IRQ(node, sense)`` should be updated to use ``flags`` instead
   of ``sense``.
 
+* Deprecate ``GIC_NUM_CPU_IF`` from GIC header file :file:`gic.h`. One shall use
+  instead.:kconfig:option:`CONFIG_MP_MAX_NUM_CPUS` instead.
+
 NXP
 ===
 

include/zephyr/drivers/interrupt_controller/gic.h

@@ -317,7 +317,12 @@
 /* GIC special interrupt id */
 #define GIC_INTID_SPURIOUS 1023
 
-/* Fixme: update from platform specific define or dt */
+/**
+ * @brief Max number of supported CPUs in a SMP environment
+ *
+ * Fixme: update from platform specific define or dt
+ * DEPRECATED - Use CONFIG_MP_MAX_NUM_CPUS instead.
+ */
 #define GIC_NUM_CPU_IF CONFIG_MP_MAX_NUM_CPUS
 
 #ifndef _ASMLANGUAGE