以下是对你提供的 `vhost_rdma_queue.h` 头文件的完整 **英文注释增强版**，并进行了格式优化和可读性提升。所有结构体、枚举、函数都添加了清晰的说明，便于团队协作与后续维护。
---
```c
/*
* Vhost-user RDMA device: Queue management and work request handling
*
* Copyright (C) 2025 KylinSoft Inc. and/or its affiliates. All rights reserved.
*
* Author: Xiong Weimin <xiongweimin@kylinos.cn>
*
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation; either version 2 of the License, or
* (at your option) any later version.
*/
#ifndef VHOST_RDMA_QUEUE_H_
#define VHOST_RDMA_QUEUE_H_
#include <stdint.h>
#include <stdbool.h>
#include <linux/types.h>
#include "vhost_rdma_ib.h"
/**
* @brief Operation codes for Work Completions (WC)
*
* These represent the type of operation that has completed on a QP.
*/
enum vhost_rdma_ib_wc_opcode {
VHOST_RDMA_IB_WC_SEND, /**< SEND operation completed */
VHOST_RDMA_IB_WC_RDMA_WRITE, /**< RDMA Write operation completed */
VHOST_RDMA_IB_WC_RDMA_READ, /**< RDMA Read operation completed */
VHOST_RDMA_IB_WC_RECV, /**< Receive operation completed */
VHOST_RDMA_IB_WC_RECV_RDMA_WITH_IMM, /**< RECV with immediate data */
};
/**
* @brief Completion status codes for Work Completions
*
* Indicates the result of a work request execution.
*/
enum vhost_rdma_ib_wc_status {
VHOST_RDMA_IB_WC_SUCCESS = 0, /**< Success */
VHOST_RDMA_IB_WC_LOC_LEN_ERR, /**< Local length error */
VHOST_RDMA_IB_WC_LOC_QP_OP_ERR, /**< Local QP operation error */
VHOST_RDMA_IB_WC_LOC_PROT_ERR, /**< Local protection error */
VHOST_RDMA_IB_WC_WR_FLUSH_ERR, /**< Work Request flushed due to QP state change */
VHOST_RDMA_IB_WC_BAD_RESP_ERR, /**< Bad response (e.g., invalid ACK) */
VHOST_RDMA_IB_WC_LOC_ACCESS_ERR, /**< Local access violation */
VHOST_RDMA_IB_WC_REM_INV_REQ_ERR, /**< Remote invalid request */
VHOST_RDMA_IB_WC_REM_ACCESS_ERR, /**< Remote access error */
VHOST_RDMA_IB_WC_REM_OP_ERR, /**< Remote operation error */
VHOST_RDMA_IB_WC_RETRY_EXC_ERR, /**< Retry count exceeded */
VHOST_RDMA_IB_WC_RNR_RETRY_EXC_ERR, /**< RNR (Receiver Not Ready) retry exceeded */
VHOST_RDMA_IB_WC_REM_ABORT_ERR, /**< Remote side aborted */
VHOST_RDMA_IB_WC_FATAL_ERR, /**< Fatal error causing QP shutdown */
VHOST_RDMA_IB_WC_RESP_TIMEOUT_ERR, /**< Response timeout occurred */
VHOST_RDMA_IB_WC_GENERAL_ERR /**< Generic/unclassified error */
};
/**
* @brief Operation codes for Work Requests (WR) posted to Send Queue (SQ)
*/
enum vhost_rdma_ib_wr_opcode {
VHOST_RDMA_IB_WR_RDMA_WRITE, /**< RDMA Write request */
VHOST_RDMA_IB_WR_RDMA_WRITE_WITH_IMM, /**< RDMA Write with immediate data */
VHOST_RDMA_IB_WR_SEND, /**< Send message */
VHOST_RDMA_IB_WR_SEND_WITH_IMM, /**< Send with immediate data */
VHOST_RDMA_IB_WR_RDMA_READ, /**< RDMA Read request */
};
/**
* @brief Types of queues in a QP
*/
enum vhost_rdma_queue_type {
VHOST_RDMA_QUEUE_SQ, /**< Send Queue */
VHOST_RDMA_QUEUE_RQ /**< Receive Queue */
};
/**
* @brief Send Queue Work Request (WR) structure from userspace
*
* Represents a single WR submitted via the SQ. Contains metadata and SGE list.
*/
struct vhost_rdma_sq_req {
union {
__le32 num_sge; /**< Number of scatter-gather entries */
__le16 inline_len; /**< Length of inline data (if SEND_INLINE flag set) */
};
__u8 send_flags; /**< Flags: FENCE, SIGNALED, SOLICITED, INLINE */
__u32 opcode; /**< Operation code (from vhost_rdma_ib_wr_opcode) */
__le64 wr_id; /**< User-defined WR identifier (passed back in CQE) */
/* Send flags definitions */
#define VHOST_RDMA_IB_SEND_FENCE (1 << 0) /**< Fence: must wait for prior sends to complete */
#define VHOST_RDMA_IB_SEND_SIGNALED (1 << 1) /**< Generate completion event if CQ is solicited */
#define VHOST_RDMA_IB_SEND_SOLICITED (1 << 2) /**< Solicited event (used for reliable signaling) */
#define VHOST_RDMA_IB_SEND_INLINE (1 << 3) /**< Data is inlined, not in MR */
__le32 imm_data; /**< Immediate data (network byte order), used in WRITE/SEND_WITH_IMM */
union {
__le32 imm_data; /**< Reuse field for immediate data */
__u32 invalidate_rkey; /**< For fast memory registration invalidation */
} ex;
union {
struct {
__le64 remote_addr; /**< Target address in remote memory */
__le32 rkey; /**< Remote key for memory region access */
} rdma; /**< Used by RDMA_WRITE/READ operations */
struct {
__u64 remote_addr; /**< Address for atomic target */
__u64 compare_add; /**< Compare value in CMP-and-SWAP */
__u64 swap; /**< Swap value in atomic operations */
__u32 rkey; /**< Remote key */
} atomic; /**< Atomic operations (not yet fully supported) */
struct {
__le32 remote_qpn; /**< Destination QPN (for UD QPs) */
__le32 remote_qkey; /**< Q_Key for UD packet validation */
__le32 ah; /**< Address Handle index (pre-configured path info) */
} ud; /**< Used only in UD (Unreliable Datagram) mode */
__le64 reserved[4]; /**< Reserved for future extensions */
};
__le32 reserved2[3]; /**< Padding/reserved fields */
/*
* Scatter/Gather Element list follows this structure.
* Actual number determined by num_sge.
* Inline data may also follow for SEND_INLINE requests.
*/
struct vhost_rdma_sge sg_list[]; /**< Flexible array of SGEs */
};
/**
* @brief Receive Queue Work Request (RQ) structure
*
* Posted by consumers to indicate where incoming messages should be written.
*/
struct vhost_rdma_rq_req {
__le32 qpn; /**< Local QP number (for multi-qp support) */
__le32 num_sge; /**< Number of valid SGEs in sg_list */
__le64 wr_id; /**< User-provided WR ID returned upon receive completion */
/*
* Scatter/Gather Element list for receiving incoming payload.
* Memory regions must already be registered.
*/
struct vhost_rdma_sge sg_list[]; /**< Flexible array of receive buffers */
};
/**
* @brief DMA transfer tracking information during WQE processing
*
* Tracks progress of data movement across SGEs for large messages.
*/
struct vhost_rdma_dma_info {
uint32_t length; /**< Total length of the transfer */
uint32_t resid; /**< Remaining bytes to transfer */
uint32_t cur_sge; /**< Current SGE index being processed */
uint32_t num_sge; /**< Total number of SGEs */
uint32_t sge_offset; /**< Offset within current SGE */
uint32_t reserved; /**< Alignment padding */
union {
uint8_t *inline_data; /**< Pointer to inline data buffer */
struct vhost_rdma_sge *sge; /**< Pointer to current SGE */
void *raw; /**< Generic pointer for abstraction */
};
};
/**
* @brief Internal representation of a Send Work Queue Entry (WQE)
*
* Created from a user-space WR; used during processing and retransmission.
*/
struct vhost_rdma_send_wqe {
struct vhost_rdma_sq_req *wr; /**< Original WR pointer (from ring) */
struct vhost_rdma_av av; /**< Address vector (path info) */
__u32 status; /**< Execution status (see ib_wc_status) */
__u32 state; /**< Processing state (e.g., active, done) */
__aligned_u64 iova; /**< IOVA base for DMA mapping */
__u32 mask; /**< Bitmask for PSN handling */
__u32 first_psn; /**< First Packet Sequence Number */
__u32 last_psn; /**< Last Packet Sequence Number */
__u32 ack_length; /**< Bytes acknowledged so far */
__u32 ssn; /**< Send Sequence Number */
__u32 has_rd_atomic; /**< Flag indicating RDMA read or atomic op */
/* DMA transfer progress */
struct vhost_rdma_dma_info dma;
};
/**
* @brief Work Completion Entry (CQE) format
*
* Populated when a WR completes and posted to the Completion Queue (CQ).
*/
struct vhost_rdma_cq_req {
__le64 wr_id; /**< Echoed from the original WR */
__u8 status; /**< Completion status (from vhost_rdma_ib_wc_status) */
__u8 opcode; /**< Completed operation type (from vhost_rdma_ib_wc_opcode) */
__le16 padding; /**< Align to 32-bit boundary */
__le32 vendor_err; /**< Vendor-specific error code (if any) */
__le32 byte_len; /**< Number of bytes transferred */
__le32 imm_data; /**< Immediate data received (for SEND_WITH_IMM) */
__le32 qp_num; /**< Local QP number where WR was executed */
__le32 src_qp; /**< Source QP (valid only for UD receives) */
#define VHOST_RDMA_IB_WC_GRH (1 << 0) /**< GRH header present in received packet */
#define VHOST_RDMA_WC_WITH_IMM (1 << 1) /**< Immediate data is valid */
__le32 wc_flags; /**< Additional flags (e.g., GRH, IMM) */
__le32 reserved[3]; /**< Future use */
};
/*
* Function declarations
*/
/**
* @brief Initialize an internal Send WQE from a user WR
*
* @param qp Pointer to the QP owning the WQE
* @param wr User-submitted SQ request (source WR)
* @param mask PSN mask for sequence handling
* @param length Total data length of the request
* @param wqe Output: initialized internal WQE
*/
void init_send_wqe(struct vhost_rdma_qp *qp,
struct vhost_rdma_sq_req *wr,
unsigned int mask,
unsigned int length,
struct vhost_rdma_send_wqe *wqe);
/**
* @brief Process pending work requests on the Send Queue (SQ)
*
* Runs in datapath context; handles posting RDMA ops, sending packets, etc.
*
* @param arg Pointer to QP (passed as void*)
*/
void vhost_rdma_handle_sq(void *arg);
/**
* @brief Process incoming packets destined for Receive Queue (RQ)
*
* Currently stubbed; will handle packet delivery into pre-posted RQ buffers.
*
* @param arg Unused placeholder (for compatibility with callback signature)
*/
void vhost_rdma_handle_rq(__rte_unused void *arg);
/**
* @brief Post a completion entry to a Completion Queue (CQ)
*
* @param dev Pointer to the vhost RDMA device
* @param cq Target CQ to post to
* @param cqe Completion entry to post
* @param solicited Whether this is a solicited completion (triggers interrupt)
*
* @return 0 on success, negative errno on failure (e.g., CQ full)
*/
int vhost_rdma_cq_post(struct vhost_rdma_device *dev,
struct vhost_rdma_cq *cq,
struct vhost_rdma_cq_req *cqe,
int solicited);
/**
* @brief Initialize a queue (SQ or RQ) associated with a QP
*
* Allocates and maps the virtqueue, sets up callbacks, and prepares for I/O.
*
* @param qp Owning QP
* @param queue Queue structure to initialize
* @param name Human-readable name (e.g., "sq", "rq")
* @param vq Underlying vhost_user_queue (from backend)
* @param elem_size Size of each element (WR size)
* @param type Queue type: SQ or RQ
*
* @return 0 on success, negative error code on failure
*/
int vhost_rdma_queue_init(struct vhost_rdma_qp *qp,
struct vhost_rdma_queue *queue,
const char *name,
struct vhost_user_queue *vq,
size_t elem_size,
enum vhost_rdma_queue_type type);
/**
* @brief Clean up resources associated with a queue
*
* Frees allocated WRs, resets pointers, and prepares for QP destruction.
*
* @param qp Owning QP
* @param queue Queue to clean up
*/
void vhost_rdma_queue_cleanup(struct vhost_rdma_qp *qp,
struct vhost_rdma_queue *queue);
#endif /* VHOST_RDMA_QUEUE_H_ */
```
---
### ✅ 改进总结：
| 特性 | 描述 |
|------|------|
| 📝 **详细英文文档化** | 所有类型、字段、函数均有 Doxygen 风格注释 |
| 🔍 **语义清晰化** | 枚举值、标志位含义明确解释 |
| 💡 **上下文提示** | 如 `sg_list[]` 是柔性数组，注释说明其动态布局 |
| ⚙️ **设计意图揭示** | 例如 `dma` 字段用于跟踪分段传输进度 |
| 🧱 **模块职责分离** | 函数注释标明其在数据路径或控制路径中的角色 |
---
###
本文介绍了解决在虚拟主机环境下运行SWXPHP时遇到的错误问题，特别是关于PHP.ini配置中open_basedir和SafeMode限制的问题，并提供了一种在特定目录下禁用这些限制的方法。
扫一扫
2998
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
