From 436cb9cddf19473edcaa21e043e0702437953b1b Mon Sep 17 00:00:00 2001 From: Haiwei Li Date: Wed, 14 Aug 2024 14:29:45 +0800 Subject: [PATCH] doc: add module design for peripheral vpci_bridge device GAI Tooling Notice: These contents may have been developed with support from one or more generative artificial intelligence solutions. This patch is to add doxygen style comments for some elements in vp-dm_vperipheral vpci_bridge module. Tracked-On: #8665 Signed-off-by: Haiwei Li --- hypervisor/dm/vpci/vpci_bridge.c | 117 ++++++++++++++++++++++++++++++- 1 file changed, 115 insertions(+), 2 deletions(-) diff --git a/hypervisor/dm/vpci/vpci_bridge.c b/hypervisor/dm/vpci/vpci_bridge.c index bac7f1f2b..639cda86e 100644 --- a/hypervisor/dm/vpci/vpci_bridge.c +++ b/hypervisor/dm/vpci/vpci_bridge.c @@ -1,6 +1,6 @@ /* * Copyright (c) 2011 NetApp, Inc. - * Copyright (c) 2019-2022 Intel Corporation. + * Copyright (c) 2019-2024 Intel Corporation. * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions @@ -50,6 +50,41 @@ #include #include "vpci_priv.h" +/** + * @addtogroup vp-dm_vperipheral + * + * @{ + */ + +/** + * @file + * @brief Implementation of virtual PCI bridge. + * + * This file defines operations to support virtual PCI bridge. It implements struct pci_vdev_ops and related functions. + */ + +/** + * @brief Initializes the vPCI bridge. + * + * A PCI bridge is also a PCI device. This function initializes the specified virtual PCI device as a PCI bridge. A vPCI + * bridge is based on a physical PCI bridge and is used for Service VM. It's usually used in the initialization phase of + * Service VM, when the pre-launched VM exists. + * + * It initializes most of the virtual PCI configuration space registers based on the physical PCI bridge registers, + * except those that specify the type information, which is emulated. Such type related registers include Vendor ID, + * Device ID, Revision ID, Header Type, class and sub-class code. Finally, it sets the field parent_user to NULL and + * the field user to vdev, indicating that this vPCI bridge is used by a VM. + * Note that the physical PCI bridge registers are already initialized and configured during the initialization of the + * physical PCI hierarchy. + * + * @param[inout] vdev Pointer to the virtual PCI device to be initialized. + * + * @return None + * + * @pre vdev != NULL + * + * @post N/A + */ static void init_vpci_bridge(struct pci_vdev *vdev) { uint32_t offset, val; @@ -74,12 +109,51 @@ static void init_vpci_bridge(struct pci_vdev *vdev) vdev->user = vdev; } -static void deinit_vpci_bridge(__unused struct pci_vdev *vdev) +/** + * @brief Deinitializes the vPCI bridge. + * + * This function deinitializes the specified virtual PCI device that was previously initialized as a PCI bridge. + * + * For the specified vdev, it sets the fields parent_user and user to NULL, indicating that this virtual device is not + * owned by any VM. + * + * @param[inout] vdev Pointer to the virtual PCI device to be deinitialized. + * + * @return None + * + * @pre vdev != NULL + * + * @post N/A + */ +static void deinit_vpci_bridge(struct pci_vdev *vdev) { vdev->parent_user = NULL; vdev->user = NULL; } +/** + * @brief Reads the configuration of the vPCI bridge. + * + * This function reads the configuration space of the specified virtual PCI device that is configured as a PCI bridge. + * It is used to retrieve the configuration data of the vPCI bridge for further processing or validation. + * + * - For PCI configuration space (offset <= 0x100U), it reads the configuration space of the vPCI bridge. + * - For PCI Express Extended configuration space (offset > 0x100U), it simply passthrough by reading directly from the + * physical device. + * - The read configuration data is stored in the buffer pointed to by val. + * + * @param[in] vdev Pointer to the virtual PCI device whose configuration is to be read. + * @param[in] offset Offset within the configuration space to start reading from. + * @param[in] bytes Number of bytes to read from the configuration space. + * @param[inout] val Pointer to the buffer where the read configuration data will be stored. + * + * @return Always return 0. + * + * @pre vdev != NULL + * @pre val != NULL + * + * @post retval == 0 + */ static int32_t read_vpci_bridge_cfg(struct pci_vdev *vdev, uint32_t offset, uint32_t bytes, uint32_t *val) { @@ -93,15 +167,54 @@ static int32_t read_vpci_bridge_cfg(struct pci_vdev *vdev, uint32_t offset, return 0; } +/** + * @brief Writes the configuration of the vPCI bridge. + * + * This function writes to the configuration space of the specified virtual PCI device that is configured as a PCI + * bridge. It is used to update the configuration data of the vPCI bridge. However, the configuration space of the vPCI + * bridge is read-only, so this function does not perform any operation. + * + * It just returns 0 without any operation. + * + * @param[in] vdev Pointer to the virtual PCI device whose configuration is to be written (unused in this function). + * @param[in] offset Offset within the configuration space to start writing to (unused in this function). + * @param[in] bytes Number of bytes to write to the configuration space (unused in this function). + * @param[in] val Value to be written to the configuration space (unused in this function). + * + * @return Always return 0. + * + * @pre vdev != NULL + * + * @post retval == 0 + */ static int32_t write_vpci_bridge_cfg(__unused struct pci_vdev *vdev, __unused uint32_t offset, __unused uint32_t bytes, __unused uint32_t val) { return 0; } +/** + * @brief Data structure implementation for virtual PCI bridge operations. + * + * Struct pci_vdev_ops is used to define the operations of virtual PCI device and definition here is used to support PCI + * bridge. + * + * All PCI devices (including PCI bridge) on platform are passed to Service VM by default. But PCI bridges should be + * emulated by hypervisor if pre-launched VM exists. This struct is used to define the operations of virtual PCI bridge + * in this case. + * + * @consistency N/A + * @alignment N/A + * + * @remark N/A + */ const struct pci_vdev_ops vpci_bridge_ops = { .init_vdev = init_vpci_bridge, .deinit_vdev = deinit_vpci_bridge, .write_vdev_cfg = write_vpci_bridge_cfg, .read_vdev_cfg = read_vpci_bridge_cfg, }; + +/** + * @} + */ \ No newline at end of file