Add comprehensive help for PIC and OFW driver Kconfig files

Co-authored-by: Rbb666 <64397326+Rbb666@users.noreply.github.com>

Author: Copilot

components/drivers/ofw/Kconfig

@@ -6,24 +6,154 @@ menuconfig RT_USING_OFW
     select RT_USING_MEMBLOCK
     depends on RT_USING_DM
     default n
+    help
+        Enable Open Firmware (Device Tree) support.
+        
+        OFW/Device Tree provides hardware description separate from code:
+        - Flattened Device Tree (FDT/DTB) parsing
+        - Hardware discovery and configuration
+        - Platform-independent device drivers
+        - Runtime hardware detection
+        
+        Features:
+        - Standard device tree bindings
+        - Property parsing and access
+        - Node traversal and searching
+        - Phandle reference resolution
+        - Address translation
+        - Interrupt mapping
+        
+        Benefits:
+        - Single kernel binary for multiple boards
+        - Easier board porting (just change DTB)
+        - Better hardware abstraction
+        - Industry-standard hardware description
+        
+        Use cases:
+        - ARM/RISC-V systems with complex hardware
+        - Supporting multiple board variants
+        - Dynamic hardware configuration
+        - PCI, USB, network device enumeration
+        
+        Requires:
+        - RT_USING_DM (Device Model)
+        - Memory block allocator
+        - Abstract Data Types (ADT) support
+        
+        Essential for modern ARM Cortex-A and RISC-V systems.
+        Enable for device tree-based hardware discovery.
 
 config RT_USING_BUILTIN_FDT
     bool "Using builtin fdt in kernel"
     depends on RT_USING_OFW
     default n
+    help
+        Embed Flattened Device Tree (FDT) binary into kernel image.
+        
+        When enabled:
+        - DTB file linked into kernel binary
+        - No need for bootloader to pass DTB
+        - DTB always available at boot
+        
+        Advantages:
+        + Simpler boot process
+        + No DTB location dependencies
+        + Guaranteed DTB availability
+        
+        Disadvantages:
+        - Larger kernel image
+        - Must rebuild kernel to change DTB
+        - Less flexible than bootloader-provided DTB
+        
+        Typical use:
+        - Systems without proper bootloader
+        - Debugging and development
+        - Single-board configurations
+        
+        Alternative: Have bootloader pass DTB address to kernel.
+        
+        Enable for embedded DTB in kernel image.
 
 config RT_BUILTIN_FDT_PATH
     string "Builtin fdt path, will rebuild if have dts"
     depends on RT_USING_BUILTIN_FDT
     default "rtthread.dtb"
+    help
+        Path to the compiled Device Tree Blob (DTB) file to embed.
+        
+        Default: "rtthread.dtb"
+        
+        This file is included in the kernel binary during linking.
+        
+        Workflow:
+        1. Write device tree source (.dts file)
+        2. Compile to DTB: dtc -I dts -O dtb -o rtthread.dtb rtthread.dts
+        3. Set this path to the DTB location
+        4. Rebuild kernel (DTB will be embedded)
+        
+        Path can be:
+        - Relative to build directory
+        - Absolute path
+        
+        Kernel will automatically rebuild if DTS changes (if build system configured).
 
 config RT_FDT_EARLYCON_MSG_SIZE
     int "Earlycon message buffer size (KB)"
     depends on RT_USING_OFW
     default 128
+    help
+        Size of early console message buffer in kilobytes.
+        
+        Default: 128 KB
+        
+        Early console (earlycon) provides debug output before full console initialization:
+        - Available during early boot
+        - Before full UART driver loads
+        - Critical for debugging boot failures
+        
+        Buffer stores messages when:
+        - Console not yet available
+        - Output faster than transmission
+        
+        Larger buffer:
+        + More boot messages captured
+        + Better for verbose debugging
+        - More memory usage
+        
+        Smaller buffer:
+        + Less memory overhead
+        - May lose early messages
+        
+        Increase for detailed boot debugging.
+        Decrease to save memory if earlycon not critical.
 
 config RT_USING_OFW_BUS_RANGES_NUMBER
     int "Max bus ranges number"
     depends on RT_USING_OFW
     default 8 if ARCH_CPU_64BIT
     default 4
+    help
+        Maximum number of bus address ranges for device tree translation.
+        
+        Default:
+        - 64-bit systems: 8 ranges
+        - 32-bit systems: 4 ranges
+        
+        Bus ranges define address space mappings:
+        - CPU address to device bus address
+        - PCI memory/IO spaces
+        - Different bus protocols (AHB, APB, AXI)
+        
+        Each range describes a memory window mapping.
+        
+        Typical usage:
+        - PCI: 2-3 ranges (prefetchable mem, non-prefetchable mem, I/O)
+        - Complex SoCs: 4-8 ranges for different buses
+        
+        Increase for:
+        - Complex bus hierarchies
+        - Multiple PCI buses
+        - Systems with many address spaces
+        
+        Each range uses ~32-48 bytes of memory.
+        Set based on your SoC's bus complexity.

components/drivers/pic/Kconfig

@@ -4,57 +4,226 @@ menuconfig RT_USING_PIC
     select RT_USING_ADT_BITMAP
     depends on RT_USING_DM
     default n
+    help
+        Enable Platform Interrupt Controller (PIC) framework.
+        
+        PIC provides unified interrupt controller abstraction for:
+        - ARM GIC (Generic Interrupt Controller) v1/v2/v3
+        - Platform-specific interrupt controllers
+        - MSI/MSI-X (Message Signaled Interrupts)
+        - Interrupt hierarchy and cascading
+        
+        Features:
+        - Device model integration
+        - Device tree support (OFW)
+        - Multiple interrupt controller support
+        - Interrupt routing and affinity
+        - Statistics and profiling
+        
+        Use cases:
+        - ARM Cortex-A systems with GIC
+        - SMP systems requiring interrupt affinity
+        - Systems using device tree
+        - Complex interrupt hierarchies
+        
+        Requires:
+        - RT_USING_DM (Device Model)
+        - Abstract Data Types (ADT) support
+        
+        Enable for advanced interrupt management with GIC or complex IRQ routing.
 
 config RT_USING_PIC_STATISTICS
     bool "Enable ISR execution time statistics"
     depends on RT_USING_PIC
     depends on RT_USING_KTIME
     depends on RT_USING_INTERRUPT_INFO
     default n
+    help
+        Enable interrupt service routine (ISR) execution time tracking.
+        
+        Provides statistics for each interrupt:
+        - Total execution time
+        - Minimum/maximum execution time
+        - Average execution time
+        - Interrupt count
+        
+        Benefits:
+        - Performance profiling
+        - Identify slow interrupt handlers
+        - Optimize ISR performance
+        - Debug interrupt latency issues
+        
+        Requirements:
+        - KTIME for high-resolution timing
+        - RT_USING_INTERRUPT_INFO for interrupt tracking
+        
+        Overhead:
+        - Minimal per-interrupt timing overhead
+        - Memory for statistics (~40 bytes per IRQ)
+        
+        Enable for interrupt performance analysis.
+        Disable in production to save memory and overhead.
 
 config MAX_HANDLERS
     int "IRQ max handlers"
     depends on RT_USING_PIC
     range 1 4294967294
     default 256
+    help
+        Maximum number of interrupt handlers supported by PIC.
+        
+        Default: 256 handlers
+        
+        This limits the total number of IRQ lines the system can handle.
+        
+        Typical values:
+        - Small systems: 64-128 IRQs
+        - Medium systems: 256-512 IRQs
+        - Large systems: 512-1024 IRQs
+        
+        Memory usage: ~16-32 bytes per handler slot
+        
+        Set based on your SoC's interrupt controller capabilities.
+        Check GIC documentation for maximum SPIs (Shared Peripheral Interrupts).
 
 config RT_PIC_ARM_GIC
     bool "ARM GICv2/v1"
     depends on RT_USING_PIC
     select RT_USING_OFW
     default n
+    help
+        Enable ARM Generic Interrupt Controller version 1/2 (GICv1/GICv2).
+        
+        GICv2 features:
+        - Up to 1020 interrupt sources
+        - Support for SGIs (Software Generated Interrupts)
+        - Support for PPIs (Private Peripheral Interrupts)
+        - Support for SPIs (Shared Peripheral Interrupts)
+        - CPU interfaces for each core
+        - Distributor for routing interrupts
+        
+        Used in:
+        - ARM Cortex-A5/A7/A8/A9/A15/A17
+        - Many ARM-based SoCs
+        
+        Requires device tree (OFW) for configuration.
+        
+        Enable for ARM Cortex-A systems with GICv2.
 
 config RT_PIC_ARM_GIC_V2M
     bool "ARM GIC V2M" if RT_PIC_ARM_GIC && RT_PCI_MSI
     depends on RT_USING_OFW
     default n
+    help
+        Enable GICv2m MSI (Message Signaled Interrupts) support.
+        
+        GICv2m provides:
+        - MSI support for GICv2 (which lacks native MSI)
+        - PCIe device interrupt handling
+        - Doorbell-style interrupt delivery
+        
+        Allows PCIe devices to use MSI with GICv2.
+        
+        Requirements:
+        - RT_PIC_ARM_GIC enabled
+        - RT_PCI_MSI for PCI MSI support
+        - Device tree configuration
+        
+        Enable for PCIe systems with GICv2 requiring MSI support.
 
 config RT_PIC_ARM_GIC_V3
     bool "ARM GICv3"
     depends on RT_USING_PIC
     select RT_USING_OFW
     default n
+    help
+        Enable ARM Generic Interrupt Controller version 3 (GICv3).
+        
+        GICv3 enhancements over GICv2:
+        - Better scalability (supports more cores)
+        - System register access (no memory-mapped CPU interface)
+        - Affinity routing for flexible interrupt routing
+        - Locality-specific peripheral interrupts (LPI)
+        - ITS (Interrupt Translation Service) for MSI
+        - Support for GICv4 virtualization extensions
+        
+        Used in:
+        - ARM Cortex-A53/A55/A57/A72/A73/A76
+        - ARMv8 and ARMv9 systems
+        - Modern ARM SoCs
+        
+        Requires device tree (OFW) for configuration.
+        
+        Enable for ARM Cortex-A systems with GICv3.
 
 config RT_PIC_ARM_GIC_V3_ITS
     bool "ARM GICv3 ITS (Interrupt Translation Service)" if RT_PIC_ARM_GIC_V3 && RT_PCI_MSI
     depends on RT_USING_OFW
     select RT_USING_ADT_REF
     default n
+    help
+        Enable GICv3 ITS for MSI/MSI-X support.
+        
+        ITS (Interrupt Translation Service) provides:
+        - Native MSI support for PCIe and other devices
+        - LPI (Locality-specific Peripheral Interrupts) management
+        - Efficient interrupt routing for thousands of devices
+        - Scalable to large systems
+        
+        Features:
+        - Translates MSI writes to LPIs
+        - Device and interrupt ID management
+        - Interrupt collection for CPU targeting
+        
+        Required for:
+        - PCIe MSI/MSI-X on GICv3
+        - Large-scale systems with many devices
+        - Modern ARM servers and complex SoCs
+        
+        Memory overhead:
+        - ITS tables for device/interrupt mapping
+        - LPI configuration tables
+        
+        Enable for GICv3 systems with PCIe requiring MSI support.
 
 config RT_PIC_ARM_GIC_V3_ITS_IRQ_MAX
     int "IRQ maximum used"
     depends on RT_PIC_ARM_GIC_V3_ITS
     default 127 if ARCH_CPU_64BIT
     default 63
     help
-      Recommended to be based on the bit length (full bits) of maximum usage.
+        Maximum number of ITS-managed LPIs (Locality-specific Peripheral Interrupts).
+        
+        Recommended to be based on the bit length (full bits) of maximum usage.
+        
+        Default values:
+        - 64-bit systems: 127 (uses 7 bits)
+        - 32-bit systems: 63 (uses 6 bits)
+        
+        LPI IDs typically start from 8192 and can go very high.
+        This setting affects ITS table allocation.
+        
+        Increase for:
+        - Systems with many PCIe devices
+        - MSI-X devices using multiple vectors
+        
+        Each LPI uses memory in ITS configuration tables.
+        Set based on actual device count to balance memory usage.
 
 config RT_PIC_ARM_GIC_MAX_NR
     int
     depends on RT_USING_PIC
     depends on RT_PIC_ARM_GIC
     default 2 if SOC_REALVIEW
     default 1
+    help
+        Maximum number of GIC instances in the system.
+        
+        Most systems have 1 GIC.
+        Some systems may have cascaded GICs or multiple interrupt controllers.
+        
+        Automatically configured based on SoC type.
+        Users typically don't need to modify this.
 
 if RT_USING_PIC
     osource "$(SOC_DM_PIC_DIR)/Kconfig"