// PciBus.c - PciBus.efi Driver Stub
// Source: e:\hs\AmiModulePkg\PCI\PciBus\PciBus.c
// Libraries used:
//   AmiPciExpressLib    (e:\hs\AmiModulePkg\Library\AmiPciExpressLib)
//   AmiPciExpressGen2Lib(e:\hs\AmiModulePkg\Library\AmiPciExpressGen2Lib)
//   AmiPciExpressGen3Lib(e:\hs\AmiModulePkg\Library\AmiPciExpressGen3Lib)
//   AmiSriovLib         (e:\hs\AmiModulePkg\Library\AmiSriovLib)
//   AmiPciBusLib        (e:\hs\AmiModulePkg\Library\AmiPciBusLib)
//   PiDxeS3BootScriptLib(e:\hs\MdeModulePkg\Library\PiDxeS3BootScriptLib)
//   SbPciHotPlugLib     (e:\hs\AmiCRBPkg\Chipset\SB\SbPciHotPlugLib)
// AutoGen:             e:\hs\Build\HR6N0XMLK\DEBUG_VS2015\X64\AmiModulePkg\PCI\PciBus\DEBUG\AutoGen.c

// Module layout:
// 0x0002C0 - 0x001DCC: Driver Entry, Protocol Registration
// 0x001DCC - 0x00599C: Device Enumeration, Bridge Setup
// 0x00599C - 0x00B944: BAR Handling, SDL, Resource Allocation
// 0x00B944 - 0x00E5E0: Bus Scan, PciIo Installation, Option ROM
// 0x00E5E0 - 0x010C10: Option ROM, Platform Policy, Reset
// 0x010C10 - 0x018B58: PCI Express (Gen2/Gen3/Gen4 Link & Device Config)
// 0x018B58 - 0x01A84C: PciInitProtocol, IOMMU/DMA
// 0x01A84C - 0x01D0E0: S3 Boot Script
// 0x01D1A0 - 0x024B00: String table (.rdata)

// =========================================================================
// DRIVER ENTRY POINT
// =========================================================================

EFI_STATUS
EFIAPI
PciBusEntryPoint (
  IN EFI_HANDLE        ImageHandle,
  IN EFI_SYSTEM_TABLE  *SystemTable
  )
{
  // Calls ProcessDriverInit() for DXE protocol init
  // Calls PciBusDriverBindingSupported() to install driver binding
  // Calls PciBusUnload() on failure
}

// =========================================================================
// PROCESSOR INITIALIZATION
// =========================================================================

VOID
ProcessDriverInit (
  IN UINT64  ImageHandle,
  IN UINT64  SystemTable
  )
{
  // Stores gImageHandle, gST, gBS, gRT
  // Calls PciBusInitDmaProtection()
  // Configures CPU flags, cache control
  // Waits for APs to finish initialization
}

// =========================================================================
// DRIVER BINDING PROTOCOL
// =========================================================================

EFI_STATUS
PciBusDriverBindingSupported (
  IN EFI_DRIVER_BINDING_PROTOCOL  *This,
  IN EFI_HANDLE                    ControllerHandle,
  IN EFI_DEVICE_PATH_PROTOCOL     *RemainingDevicePath
  )
{
  // Validates PCI root bridge I/O protocol on controller
  // Checks for ACPI device path
  // Discovers cache line size from CPU info HOB
}

EFI_STATUS
PciBusDriverBindingStart (
  IN EFI_DRIVER_BINDING_PROTOCOL  *This,
  IN EFI_HANDLE                    ControllerHandle,
  IN EFI_DEVICE_PATH_PROTOCOL     *RemainingDevicePath
  )
{
  // Installs PciRootBridgeIo protocol
  // Initializes root bridge instance
  // Calls PciBusEnumerateBus() to scan devices
}

EFI_STATUS
PciBusDriverBindingStop (
  IN EFI_DRIVER_BINDING_PROTOCOL  *This,
  IN EFI_HANDLE                    ControllerHandle,
  IN UINTN                         NumberOfChildren,
  IN EFI_HANDLE                   *ChildHandleBuffer
  )
{
  // Stops and uninstalls protocols for all child devices
}

// =========================================================================
// BUS ENUMERATION
// =========================================================================

EFI_STATUS
PciBusEnumerateBus (
  VOID
  )
{
  // Scans all PCI buses starting from bus 0
  // Discovers PCI devices and bridges
  // Assigns bus numbers to bridges (Bus OOR = Out Of Range handling)
  // Calls PciBusEnumerateDevice() for each discovered device
  // Installs gEfiPciEnumerationCompleteProtocolGuid at end
}

EFI_STATUS
PciBusEnumerateDevice (
  IN UINT64  PciDeviceHandle
  )
{
  // Reads VID/DID, checks vendor/device presence
  // Calls PciBusCreatePciDeviceNode() to allocate device struct
  // Calls PciBusGetPciDeviceData() to read config space
  // Calls PciBusGetDeviceCapability() to parse capabilities
  // Calls PciBusLocateSdlData() for SDL slot mapping
  // Calls PciBusProbeDeviceBar() to read BARs
  // Reports discovered device via PciBusReportDevice()
}

EFI_STATUS
PciBusInitDevice (
  IN UINT64          PciDeviceHandle,
  IN UINT64          Attributes,
  IN UINT8           Phase
  )
{
  // Overrides device attributes from SDL configuration
  // Sets PCI attributes via PciBusPciRead/PciBusPciWrite
  // Handles device-specific initialization phases
}

// =========================================================================
// BAR HANDLING
// =========================================================================

EFI_STATUS
PciBusParseBar (
  IN UINT64  PciDeviceHandle
  )
{
  // Iterates through 6 standard PCI BARs
  // Determines BAR type (IO, MMIO32, MMIO64, PMEM32, PMEM64)
  // Calculates BAR size and alignment
  // Handles 64-bit BARs spanning two registers
}

EFI_STATUS
PciBusParseExpBar (
  IN UINT64  PciDeviceHandle
  )
{
  // Parses Extended BARs (PCI Express capability)
  // Handles >4GB MMIO BARs
}

// =========================================================================
// RESOURCE ALLOCATION
// =========================================================================

EFI_STATUS
PciBusCalculateBrgResources (
  IN UINT64  RootBridgeHandle
  )
{
  // Calculates resource requirements per bridge
  // Processes IO, MMIO32, MMIO64, PMEM32, PMEM64 per bridge
  // Calls PciBusSortBridgeResources() for ordering
  // Calls PciBusOptimizeBrgResources() for bridge resource optimization
  // Calls PciBusInsertSortedBar() for sorted resource insertion
}

EFI_STATUS
PciBusOptimizeBrgResources (
  IN UINT64  BridgeHandle,
  IN UINT32  ResourceType
  )
{
  // Optimizes bridge resource windows
  // Sorts device and bridge BARs by type
  // Merges adjacent resources when possible
}

EFI_STATUS
PciBusArrangeFixResources (
  IN UINT64  BridgeHandle,
  IN INT32   ResourceIndex
  )
{
  // Handles FIXED resources (pre-assigned by platform)
  // Validates alignment (IO min 4K, MMIO min 1MB)
  // Processes fixed bridge resource requirements
}

EFI_STATUS
PciBusAllocateResource (
  IN UINT64  RootBridgeHandle
  )
{
  // Allocates IO and memory space to all bridges
  // Handles non-contiguous resource allocation
  // Uses AllocateIoSpace / AllocateMemorySpace primitives
  // Probes each PCI device for resource requirements
  // Prints "Probing PCI Device" + current resource state
}

// =========================================================================
// PCI EXPRESS LINK TRAINING & CONFIGURATION (Gen1/Gen2/Gen3/Gen4)
// =========================================================================

EFI_STATUS
PcieSetLinkProperties (
  IN UINT64  PciDeviceHandle
  )
{
  // Configures PCIe link capabilities via LINK_CAP/LINK_CTRL2
  // Reads LNK_CNT register and applies settings
  // Updates link control register with new values
  // Displays LNK_CNT field breakdown:
  //   BwI (Bandwidth Init), BwMI, AuWi (Auto Width), CkPM, ExS (Extended Sync),
  //   CCk (Clock Common), Rtr (Retrain), LDis (Link Disable),
  //   RCB (Read Completion Boundary), ASPM
}

EFI_STATUS
PcieSetDeviceProperties (
  IN UINT64  PciDeviceHandle
  )
{
  // Configures PCIe device capabilities (MaxPayload, MRRS, etc.)
  // Reads DEV_CNT register, applies new settings
  // Configures: Function Level Reset, MRR, NoSnoop, Phantom Functions,
  //   Extended Tag, MaxPayload, Relaxed Ordering
  // Displays DEV_CNT field breakdown
}

EFI_STATUS
PcieInitLink (
  IN UINT64  PciDeviceHandle
  )
{
  // Initializes link for downstream ports
  // Handles ARI (Alternative Routing ID) configuration
  // Gen2 enable/disable based on platform policy
  // Disables link as needed
}

EFI_STATUS
PcieLinkTraining (
  IN UINT64  PciDeviceHandle
  )
{
  // Performs PCIe link training (recovery state handling)
  // Two-phase: loop 1 (wait for link up), loop 2 (retrain)
  // Configurable timeout per retry
  // Reports EQ_STS (equalization status)
  // Disables link on training failure
}

EFI_STATUS
PcieCollectCaps (
  IN UINT64  PciDeviceHandle
  )
{
  // Collects and displays all PCIe capabilities:
  //   PCIE_CAP (capability version, port type, slot)
  //   DEV_CAP (device capabilities including R2, FR, PowerS, etc.)
  //   LNK_CAP (link capabilities: speed, width, ASPM)
  //   SLT_CAP (slot capabilities)
  //   ROOT_CAP (root complex capabilities)
}

EFI_STATUS
PcieSetAspm (
  IN UINT64  PciDeviceHandle
  )
{
  // Configures ASPM (Active State Power Management)
  // Compares upstream/downstream port latency
  // Respects PCI_SETUP_DONT_TOUCH for ASPM
  // Calculates best ASPM state for the link
}

EFI_STATUS
Pcie2SetLinkProperties (
  IN UINT64  PciDeviceHandle
  )
{
  // Gen2-specific link properties
  // Reads LNK_CNT2 register (CmDe, CmSOS, ECm, TrM, ...)
  // Applies Gen2 link settings
}

EFI_STATUS
Pcie2SetDeviceProperties (
  IN UINT64  PciDeviceHandle
  )
{
  // Gen2-specific device properties
  // Configures DEV_CNT2 (EEPrB, LTR, IDO, ARI, Completion Timeout)
}

// =========================================================================
// SR-IOV
// =========================================================================

EFI_STATUS
SriovProbeDevice (
  IN UINT64  PciDeviceHandle
  )
{
  // Detects SR-IOV capable devices
  // Reads ARI capability, page size
  // Enumerates Virtual Functions (VFs)
  // Re-scans bus for discovered VFs
  // Updates mMaxBusFound after VF enumeration
}

// =========================================================================
// OPTION ROM
// =========================================================================

EFI_STATUS
PciBusInstallPciIo (
  IN UINT64  PciDeviceHandle
  )
{
  // Installs EFI_PCI_IO_PROTOCOL on device handle
  // Configures OpROM enable/disable
  // Loads and dispatches Option ROM images
  // Handles OEM program devices
  // Installs BusOvr (Bus Override) and LoadFile2 protocols
}

EFI_STATUS
PciBusProcessRomImage (
  IN UINT64  PciDeviceHandle
  )
{
  // Overrides ROM file location from SDL data
  // Loads ROM image from specified location
}

// =========================================================================
// S3 BOOT SCRIPT SUPPORT
// =========================================================================

EFI_STATUS
PciBusS3BootScriptSave (
  VOID
  )
{
  // Saves PCI configuration to S3 boot script
  // Stores IO, memory, PCI CFG operations for S3 resume
}

EFI_STATUS
PciBusS3BootScriptExecute (
  VOID
  )
{
  // Executes S3 boot script entries
  // Processes label, IO write, mem write, PCI CFG write operations
  // Supports dispatch entries for early S3 restore
}

// =========================================================================
// I/O MMU
// =========================================================================

EFI_STATUS
PciBusAllocateDmaBuffer (
  IN  UINTN   Pages,
  OUT VOID    **Buffer
  )
{
  // Allocates DMA-safe buffer via IoMmu protocol
  // Handles DMA remap attributes
}

// =========================================================================
// GPIO / PLATFORM
// =========================================================================

//
// GPIO group/pin error strings indicate platform-specific GPIO configuration
// PCH LPC device ID validation for chipset SKU detection
//

// =========================================================================
// UTILITY FUNCTIONS
// =========================================================================

VOID
PciBusDebugPrint (
  IN UINTN   ErrorLevel,
  IN CHAR8   *Format,
  ...
  )
{
  // Wrapper around DebugPrint()
  // ErrorLevel mask controls output (0x400000=info, 0x80000000=error)
}

VOID
PciBusAssertReport (
  IN CHAR8   *FileName,
  IN UINTN   LineNumber,
  IN CHAR8   *Expression
  )
{
  // Reports assertion failures
  // References file:line triple from UEFI debug infrastructure
}

BOOLEAN
PciBusFindGuidInHob (
  IN EFI_GUID  *Guid,
  OUT VOID     **Hob
  )
{
  // Wraps GetNextGuidHob() for matching GUID in HOB list
}

UINT64
PciBusPciExpressAddr (
  IN UINT8   Bus,
  IN UINT8   Device,
  IN UINT8   Function,
  IN UINT32  Register
  )
{
  // Calculates MMIO address for PCIe configuration access
  // Based on MCFG table base address
}

UINTN
PciBusGetNextFunction (
  IN UINT8   Bus,
  IN UINT8   Device,
  IN UINT8   Function
  )
{
  // Enumerates next PCI function (multi-function device support)
}

BOOLEAN
PciBusIsPciDevicePresent (
  IN UINT8   Bus,
  IN UINT8   Device,
  IN UINT8   Function
  )
{
  // Checks vendor ID != 0xFFFF to detect device presence
}

// =========================================================================
// NETWORK NIC BYPASS (HR650X platform specific)
// =========================================================================

EFI_STATUS
PciBusSkipNicBySlot (
  VOID
  )
{
  // Platform-specific NIC bypass logic
  // Supports multiple Riser configurations:
  //   1U: Riser1 (slots 1-2), Riser2 (slot 3)
  //   2U: Riser1 (slots 1-3), Riser2 (slots 3-4), Riser3 (slot 5), Riser7 (slot 5-6)
  // Root ports: RP 0x1A, 0x2A, 0x3A, 0x3C, 0x1C, 0x2C
  // Skips PXE driver binding on NICs behind specified slots
}

BOOLEAN
PciBusCheckNicDriverBinding (
  IN UINT16  VendorId,
  IN UINT16  DeviceId
  )
{
  // Validates network device before PXE driver binding
  // Skips NICs with >4 ports
}