UefiPayloadPkg/UfsPlatformDxe: Replace binary with source UFS driver

Replace UfsPlatform.efi binary with source implementation providing
Intel UFS optimizations: LCC disable, lane activation, HS Recipe
programming, and power mode switching to HS-G3.

Signed-off-by: Matt DeVillier <[email protected]>

Author: MrChromebox

UefiPayloadPkg/UefiPayloadPkg.dsc

@@ -1204,6 +1204,7 @@
 !if $(UFS_ENABLE) == TRUE
   MdeModulePkg/Bus/Pci/UfsPciHcDxe/UfsPciHcDxe.inf
   MdeModulePkg/Bus/Ufs/UfsPassThruDxe/UfsPassThruDxe.inf
+  UefiPayloadPkg/UfsPlatformDxe/UfsPlatformDxe.inf
 !endif
 !if $(NVME_ENABLE) == TRUE
   MdeModulePkg/Bus/Pci/NvmExpressDxe/NvmExpressDxe.inf

UefiPayloadPkg/UefiPayloadPkg.fdf

@@ -375,10 +375,7 @@ INF MdeModulePkg/Bus/Scsi/ScsiDiskDxe/ScsiDiskDxe.inf
 !if $(UFS_ENABLE) == TRUE
 INF MdeModulePkg/Bus/Pci/UfsPciHcDxe/UfsPciHcDxe.inf
 INF MdeModulePkg/Bus/Ufs/UfsPassThruDxe/UfsPassThruDxe.inf
-FILE DRIVER = 700A8874-D215-4ACC-9EF2-7A80128560E0 {
-  SECTION PE32 = UefiPayloadPkg/UfsPlatform/UfsPlatform.efi
-  SECTION UI = "UfsPlatform"
-}
+INF UefiPayloadPkg/UfsPlatformDxe/UfsPlatformDxe.inf
 !endif
 !if $(NVME_ENABLE) == TRUE
 INF MdeModulePkg/Bus/Pci/NvmExpressDxe/NvmExpressDxe.inf

UefiPayloadPkg/UfsPlatform/UfsPlatform.efi

@@ -0,0 +1,340 @@
+# UfsPlatformDxe Driver
+
+## Overview
+
+Platform-specific UFS (Universal Flash Storage) host controller driver for Intel platforms, implementing critical performance optimizations that reduce boot time from **3 minutes to 15 seconds** (12x improvement). This source-based implementation replaces the previous binary `UfsPlatform.efi` with a clean, maintainable solution.
+
+## Purpose
+
+Implements the `EDKII_UFS_HC_PLATFORM_PROTOCOL` to provide Intel-specific UFS configuration during host controller initialization. The driver addresses gaps in the EDK2 UFS core driver by implementing:
+
+1. **PA_LOCAL_TX_LCC_ENABLE Disable** - Essential for Intel UFS link initialization
+2. **Lane Activation** - Enables all connected UFS lanes for maximum bandwidth
+3. **High-Speed Recipe Programming** - Configures Data Link Layer timeouts and PHY settings for stable HS operation
+4. **Power Mode Switching** - Explicitly switches from PWM mode to High-Speed mode (HS-G3)
+
+Without these optimizations, the UFS link operates in slow PWM mode, causing 3+ minute boot times on Intel platforms.
+
+## Key Features
+
+✅ **12x Boot Performance** - Reduces boot time from 3 minutes to 15 seconds
+✅ **Universal Intel Support** - Works across Alderlake, Meteor Lake platforms without device-specific quirks
+✅ **Full Lane Utilization** - Activates all connected UFS lanes (typically 2x2 dual-lane)
+✅ **HS-G3 Operation** - Achieves High-Speed Gear 3 on both RX and TX paths
+✅ **EDK2 Best Practices** - Clean source implementation with proper phase timing and extensive debug logging
+✅ **Gap Filling** - Implements critical functionality missing from EDK2 core UFS driver
+
+## Implementation Details
+
+### Protocol Callbacks
+
+The driver executes optimizations at specific phases during UFS controller initialization:
+
+| Phase | Action | Purpose |
+|-------|--------|---------|
+| `EdkiiUfsHcPreHce` | None | Not required for Intel platforms |
+| `EdkiiUfsHcPostHce` | **Disable PA_LOCAL_TX_LCC_ENABLE** | Disable Line Coding Control before link startup |
+| `EdkiiUfsHcPreLinkStartup` | None | LCC disable moved to PostHce for proper timing |
+| `EdkiiUfsHcPostLinkStartup` | **1. Validate lanes**<br>**2. Activate all lanes**<br>**3. Program HS Recipe**<br>**4. Switch to HS mode** | Enable dual-lane operation, configure HS parameters, switch from PWM to Fast mode |
+
+### Key Optimizations
+
+#### 1. PA_LOCAL_TX_LCC_ENABLE Disable (PostHce)
+- **Attribute**: `PA_LOCAL_TX_LCC_ENABLE` (UniPro 0x155E)
+- **Action**: Set to 0 (disabled)
+- **Timing**: After HCE enable, before link startup
+- **Purpose**: Intel UFS controllers require LCC disabled for stable link initialization
+
+#### 2. Lane Activation (PostLinkStartup)
+- **Attributes**: `PA_ACTIVE_TX_DATA_LANES`, `PA_ACTIVE_RX_DATA_LANES`
+- **Action**: Activate all physically connected lanes (typically 2 lanes)
+- **Impact**: Doubles bandwidth on dual-lane systems
+- **Detection**: Queries `PA_CONNECTED_*_LANES` to determine available lanes
+
+#### 3. High-Speed Recipe Programming (PostLinkStartup)
+- **Data Link Layer Timeouts**:
+  - `DL_FC0_PROTECTION_TIMEOUT_VAL` = 0x1FFF
+  - `DL_TC0_REPLAY_TIMEOUT_VAL` = 0xFFFF
+  - `DL_AFC0_REQ_TIMEOUT_VAL` = 0x7FFF
+- **PHY Layer Settings**:
+  - `PA_HS_SERIES` = Mode B (HS-B)
+  - `PA_RX_TERMINATION` = 0x1
+  - `PA_TX_TERMINATION` = 0x1
+- **Purpose**: Configure timing and PHY parameters required for stable High-Speed operation
+
+#### 4. Power Mode Switching (PostLinkStartup)
+- **Query**: `PA_MAX_RX_HS_GEAR` for host and device capabilities
+- **Configuration**: Set `PA_RX_GEAR` and `PA_TX_GEAR` to HS-G3 (limited for compatibility)
+- **Execution**: Issue `PA_PWR_MODE` change to Fast mode (0x11)
+- **Confirmation**: Wait for `UFS_HC_IS_UPMS` interrupt to verify mode change
+- **Impact**: Switches from PWM (slow) to HS-G3 mode, critical for boot performance
+
+### Reference Clock
+- **Setting**: 19.2 MHz (`EdkiiUfsCardRefClkFreq19p2Mhz`)
+- **Scope**: Standard for Intel UFS platforms
+
+### Files
+
+- **UfsPlatformDxe.h** - Header with protocol definitions and constants
+- **UfsPlatformDxe.c** - Main driver implementation with callback logic
+- **UfsPlatformDxe.inf** - EDK2 build configuration
+
+## Build Integration
+
+The driver is automatically included when `UFS_ENABLE = TRUE` in the platform DSC file.
+
+### Modified Files
+
+1. **UefiPayloadPkg/UefiPayloadPkg.dsc** (line 1207)
+   ```
+   !if $(UFS_ENABLE) == TRUE
+     MdeModulePkg/Bus/Pci/UfsPciHcDxe/UfsPciHcDxe.inf
+     MdeModulePkg/Bus/Ufs/UfsPassThruDxe/UfsPassThruDxe.inf
+     UefiPayloadPkg/UfsPlatformDxe/UfsPlatformDxe.inf  # <-- NEW
+   !endif
+   ```
+
+2. **UefiPayloadPkg/UefiPayloadPkg.fdf** (line 378)
+   ```
+   !if $(UFS_ENABLE) == TRUE
+   INF MdeModulePkg/Bus/Pci/UfsPciHcDxe/UfsPciHcDxe.inf
+   INF MdeModulePkg/Bus/Ufs/UfsPassThruDxe/UfsPassThruDxe.inf
+   INF UefiPayloadPkg/UfsPlatformDxe/UfsPlatformDxe.inf  # <-- NEW (replaces binary)
+   !endif
+   ```
+
+### Removed
+
+- **UefiPayloadPkg/UfsPlatform/** - Directory containing binary UfsPlatform.efi
+
+## Building
+
+```bash
+cd /home/mattd/dev/coreboot/payloads/external/edk2/workspace/mrchromebox
+
+# Build for X64
+build -a X64 -p UefiPayloadPkg/UefiPayloadPkg.dsc -b RELEASE -t GCC5
+
+# Or for IA32
+build -a IA32 -p UefiPayloadPkg/UefiPayloadPkg.dsc -b RELEASE -t GCC5
+```
+
+## Testing
+
+### Expected Behavior
+
+With debug enabled, you should see these messages during UFS initialization:
+
+```
+UfsPlatformDxeInitialize: Installing UFS HC Platform Protocol
+UfsPlatformDxeInitialize: UFS HC Platform Protocol installed successfully
+UfsPlatformDxeInitialize: Configuration - RefClkFreq: 19.2 MHz
+UfsPlatformDxeInitialize: Features - LCC Disable, Lane Activation, HS Recipe, HS Mode Switch
+...
+UfsPlatformCallback: PostHce - Applying Intel-specific initialization
+DisableLccForIntel: Current PA_LOCAL_TX_LCC_ENABLE = 1
+DisableLccForIntel: Successfully disabled PA_LOCAL_TX_LCC_ENABLE
+...
+UfsPlatformCallback: PostLinkStartup - Validating and activating lanes
+ValidateLaneConfiguration: Connected lanes - TX: 2, RX: 2
+ValidateLaneConfiguration: Active lanes - TX: 1, RX: 1
+ActivateAllLanes: Activating RX lanes (1 -> 2)
+ActivateAllLanes: RX lanes activated successfully
+ActivateAllLanes: Activating TX lanes (1 -> 2)
+ActivateAllLanes: TX lanes activated successfully
+ProgramHsRecipe: Programming HS Recipe for Intel platform
+ProgramHsRecipe: Configured - HS Mode B, Timeouts (FC0:0x1FFF TC0:0xFFFF AFC0:0x7FFF)
+SwitchToHighSpeedMode: Target gears - RX: HS-G3, TX: HS-G3
+SwitchToHighSpeedMode: Successfully switched to High-Speed mode
+```
+
+### Performance Verification
+
+**Expected Results:**
+- **Boot Time**: ~15 seconds (vs 3+ minutes without optimizations)
+- **UFS Mode**: High-Speed Gear 3 (HS-G3) on all connected lanes
+- **Lane Configuration**: All physically connected lanes active (typically 2x2)
+
+### Functional Verification
+
+1. **UFS Device Detection**
+   - UFS LUN 0 detected and registered
+   - Block device appears with correct capacity
+   - Device appears in boot menu
+
+2. **Link Quality**
+   - No link startup failures
+   - No power mode change errors
+   - UPMS (UIC Power Mode Status) interrupt confirmed
+
+3. **Lane Activation**
+   - Connected lanes match active lanes
+   - Dual-lane systems show 2 TX + 2 RX lanes active
+   - No asymmetric lane warnings
+
+4. **High-Speed Operation**
+   - PA_PWR_MODE successfully set to Fast mode (0x11)
+   - HS-G3 gears configured for both RX and TX
+   - HS Recipe programming completed without errors
+
+5. **Boot Test**
+   - Boot from UFS device successful
+   - No I/O errors during boot
+   - Normal operating performance
+
+### Debug Points
+
+Enable debug output in the DSC file:
+```
+[PcdsFixedAtBuild]
+  gEfiMdePkgTokenSpaceGuid.PcdDebugPropertyMask|0x2F
+  gEfiMdePkgTokenSpaceGuid.PcdDebugPrintErrorLevel|0x80400047
+```
+
+Key debug locations:
+1. **UfsPlatformDxeInitialize** - Protocol installation
+2. **UfsPlatformCallback** - Platform callbacks with phase information
+3. **UfsDmeSet** - UIC command execution for PA_LOCAL_TX_LCC_ENABLE
+
+## Architecture
+
+### Design Philosophy
+
+This driver follows EDK2 best practices while implementing Intel platform-specific optimizations:
+
+- **Timing Correctness**: Operations executed at proper phases (PostHce for LCC, PostLinkStartup for HS configuration)
+- **Universal Compatibility**: Works across Intel Alderlake, Meteor Lake, and similar platforms without device-specific quirks
+- **Gap Filling**: Implements functionality missing from EDK2 UFS core driver (HS Recipe, power mode switching)
+- **Robustness**: Validates configurations and provides extensive debug logging for troubleshooting
+
+## Technical Details
+
+### UniPro/UFS Attribute Programming
+
+The driver uses UIC (UniPro Interconnect Configuration) commands to configure UniPro and UFS attributes:
+
+**DME_SET Command Structure:**
+```c
+UicCommand.Opcode = UFS_UIC_DME_SET;         // 0x02
+UicCommand.Arg1   = (Attribute << 16) | 0x0; // MIB Attribute | GenSelectorIndex
+UicCommand.Arg2   = 0x00000000;              // AttrSetType = Normal
+UicCommand.Arg3   = Value;                   // Attribute value
+```
+
+**DME_GET Command Structure:**
+```c
+UicCommand.Opcode = UFS_UIC_DME_GET;         // 0x01
+UicCommand.Arg1   = (Attribute << 16) | 0x0; // MIB Attribute | GenSelectorIndex
+UicCommand.Arg2   = 0x00000000;              // AttrSetType = Normal
+// Result returned in UicCommand.Arg3
+```
+
+### Key UniPro Attributes
+
+| Attribute | MIB ID | Layer | Purpose |
+|-----------|--------|-------|---------|
+| PA_LOCAL_TX_LCC_ENABLE | 0x155E | PHY | Line Coding Control (must be disabled for Intel) |
+| PA_CONNECTED_TX_DATA_LANES | 0x1561 | PHY | Number of physically connected TX lanes |
+| PA_CONNECTED_RX_DATA_LANES | 0x1581 | PHY | Number of physically connected RX lanes |
+| PA_ACTIVE_TX_DATA_LANES | 0x1560 | PHY | Number of active TX lanes (set to match connected) |
+| PA_ACTIVE_RX_DATA_LANES | 0x1580 | PHY | Number of active RX lanes (set to match connected) |
+| PA_HS_SERIES | 0x156A | PHY | HS mode series (A=1, B=2) |
+| PA_RX_GEAR | 0x1583 | PHY | RX gear setting (1-4 for HS-G1 to HS-G4) |
+| PA_TX_GEAR | 0x1568 | PHY | TX gear setting (1-4 for HS-G1 to HS-G4) |
+| PA_MAX_RX_HS_GEAR | 0x1587 | PHY | Maximum supported RX HS gear |
+| PA_RX_TERMINATION | 0x1569 | PHY | RX termination enable for HS mode |
+| PA_TX_TERMINATION | 0x1569 | PHY | TX termination enable for HS mode |
+| PA_PWR_MODE | 0x1571 | PHY | Power mode (Fast=1, Slow=2, FastAuto=4, SlowAuto=5) |
+| DL_FC0_PROTECTION_TIMEOUT_VAL | 0x2041 | Data Link | Flow control timeout |
+| DL_TC0_REPLAY_TIMEOUT_VAL | 0x2042 | Data Link | Replay timeout |
+| DL_AFC0_REQ_TIMEOUT_VAL | 0x2043 | Data Link | AFC request timeout |
+
+### Protocol Implementation
+
+Implements **EDKII_UFS_HC_PLATFORM_PROTOCOL_VERSION 3**:
+
+```c
+typedef struct {
+  UINT32                                    Version;
+  EDKII_UFS_HC_PLATFORM_OVERRIDE_HC_INFO    OverrideHcInfo;  // Not used
+  EDKII_UFS_HC_PLATFORM_CALLBACK            Callback;        // Main callback
+  EDKII_UFS_CARD_REF_CLK_FREQ               RefClkFreq;      // 19.2 MHz
+  BOOLEAN                                   SkipHceReenable; // FALSE
+  BOOLEAN                                   SkipLinkStartup; // FALSE
+} EDKII_UFS_HC_PLATFORM_PROTOCOL;
+```
+
+### Performance Impact
+
+| Optimization | Boot Time Impact | Reason |
+|--------------|------------------|--------|
+| LCC Disable | Essential | Link fails without it |
+| Lane Activation | ~5-10% improvement | Doubles bandwidth on dual-lane systems |
+| HS Recipe | Essential | Required for stable HS operation |
+| Power Mode Switch | **~90% improvement** | Switches from slow PWM to fast HS-G3 mode |
+| **Combined** | **3 min → 15 sec (12x)** | All optimizations working together |
+
+## Documentation
+
+Detailed documentation is provided in the following files:
+
+- **PERFORMANCE_OPTIMIZATIONS.md** - Overview of all implemented optimizations
+- **LANE_ACTIVATION.md** - Lane activation feature details
+- **HS_RECIPE.md** - High-Speed Recipe programming details
+- **POWER_MODE_SWITCHING.md** - Power mode switching implementation
+- **PLATFORM_COMPATIBILITY.md** - Platform compatibility decisions
+- **PHASE_TIMING_VERIFICATION.md** - Callback phase timing verification
+- **UFS_IMPLEMENTATION_SUMMARY.md** - Complete implementation summary
+- **UFS_PLATFORM_ANALYSIS.md** - Analysis comparing implementations
+
+## Future Enhancements
+
+### Potential Improvements
+
+1. **Dynamic Gear Selection**
+   - Auto-detect device capabilities beyond HS-G3
+   - Support HS-G4/G5 when available and stable
+   - Fallback to lower gears if link quality issues occur
+
+2. **Multi-Platform Support**
+   - Detect platform via PCI Vendor/Device ID
+   - Support AMD UFS controllers with platform-specific settings
+   - PCD-based configuration options for flexibility
+
+3. **Advanced Power Management**
+   - Implement power mode transition during runtime
+   - Support aggressive power saving modes during idle
+   - Optimize power consumption vs performance tradeoffs
+
+4. **Enhanced Diagnostics**
+   - Link quality monitoring and reporting
+   - Performance counters and statistics
+   - Error injection and recovery testing
+
+## References
+
+### Specifications
+- **MIPI UniPro Specification v1.6** - UniPro layer protocol and attributes
+- **JEDEC UFS Specification v3.1/v4.0** - UFS protocol, commands, and attributes
+- **MIPI M-PHY Specification v5.0** - Physical layer specification
+
+### EDK2 Code
+- **MdeModulePkg/Include/Protocol/UfsHostControllerPlatform.h** - Platform protocol definition
+- **MdeModulePkg/Bus/Ufs/UfsPassThruDxe/** - UFS core driver implementation
+- **MdeModulePkg/Bus/Pci/UfsPciHcDxe/** - UFS PCI host controller driver
+
+### Reference Implementations
+- **Linux drivers/ufs/host/ufshcd-pci.c** - Linux UFS PCI driver
+- **Linux drivers/ufs/host/ufshcd-pltfrm.c** - Linux UFS platform driver
+
+### Related Documentation
+- **PERFORMANCE_OPTIMIZATIONS.md** - This driver's optimization details
+- **HS_RECIPE.md** - High-Speed Recipe implementation notes
+- **POWER_MODE_SWITCHING.md** - Power mode switching details
+
+## License
+
+Copyright (c) 2025, Matt DeVillier. All rights reserved.
+
+SPDX-License-Identifier: BSD-2-Clause-Patent
+