# xnvmf

**Repository Path**: cdevel/xnvmf

## Basic Information

- **Project Name**: xnvmf
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-05
- **Last Updated**: 2026-04-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# libxnvmf

A high-performance, generic SPDK-based NVMe-oF initiator library with multipath support.

## Features

- **Multipath Support**: Active-passive and active-active modes with round-robin or min-queue-depth selectors
- **ANA Support**: Full Asymmetric Namespace Access support for intelligent path selection
- **Zero-Copy I/O**: DMA buffer pools and scatter-gather list I/O for maximum performance
- **Per-Thread Channels**: Lock-free I/O channels for thread-safe, high-performance operation
- **SPDK-Based**: Built on top of SPDK's proven NVMe library

## Requirements

- CMake 3.16+
- GCC or Clang with C11 support
- OpenSSL development headers
- CUnit (for unit tests)
- Linux system (required by SPDK)

## Building

### Prerequisites

- CMake 3.16+
- GCC or Clang with C11 support
- OpenSSL development headers
- CUnit (for unit tests)
- Linux system (required by SPDK)

### Quick Build

```bash
# Clone with submodules
git clone --recursive https://gitee.com/cdevel/xnvmf.git
cd xnvmf

# Build (SPDK will be compiled automatically on first build)
mkdir build && cd build
cmake ..
make -j$(nproc)
```

### Build Options

| Option | Default | Description |
|--------|---------|-------------|
| `XNVMF_BUILD_SHARED` | ON | Build shared library |
| `XNVMF_BUILD_STATIC` | ON | Build static library |
| `XNVMF_BUILD_TESTS` | ON | Build unit tests |
| `XNVMF_SPDK_REBUILD` | OFF | Force SPDK rebuild |

### Build Artifacts

After successful build:

- `lib/libxnvmf.a` - Static library (no external dependencies)
- `lib/libxnvmf.so` - Shared library (no external SPDK/DPDK dependencies)
- `include/xnvmf/` - Public headers

### Using libxnvmf

```bash
# Static linking
gcc myapp.c -I/path/to/xnvmf/include -L/path/to/xnvmf/lib -lxnvmf -lpthread -ldl

# Dynamic linking
gcc myapp.c -I/path/to/xnvmf/include -L/path/to/xnvmf/lib -lxnvmf
```

Note: No SPDK or DPDK installation required - they are embedded in libxnvmf.

## Debian Package

### Build DEB Package

```bash
# Install build dependencies
sudo apt install debhelper cmake libssl-dev libcunit1-dev pkg-config

# Build the package
dpkg-buildpackage -us -uc -b

# The packages will be in the parent directory:
# - libxnvmf1_1.0.0-1_amd64.deb  (runtime library)
# - libxnvmf-dev_1.0.0-1_amd64.deb (development files)
```

### Install DEB Package

```bash
# Install runtime library
sudo dpkg -i libxnvmf1_1.0.0-1_amd64.deb

# Install development files (for building applications)
sudo dpkg -i libxnvmf-dev_1.0.0-1_amd64.deb
```

### Use in Your Project

After installing the dev package:

```bash
# Compile your application
gcc myapp.c -lxnvmf -lpthread -ldl

# Or use pkg-config
gcc myapp.c $(pkg-config --cflags --libs xnvmf)
```

## Running Tests

```bash
cd build
ctest --output-on-failure
```

## Usage Example

```c
#include <xnvmf/xnvmf.h>
#include <spdk/nvme.h>

int main(void) {
    // Initialize environment
    xnvmf_env_init(NULL);
    
    // Create subsystem with multipath
    xnvmfSubsystemOpts opts = {
        .name = "nvme-of-ssd",
        .mpPolicy = XNVMF_MP_POLICY_ACTIVE_ACTIVE,
        .mpSelector = XNVMF_MP_SELECTOR_ROUND_ROBIN,
    };
    xnvmfSubsystem *subsys = xnvmf_subsystem_create(&opts);
    
    // Add paths (multiple connections to same target)
    struct spdk_nvme_transport_id trid1 = {
        .trtype = SPDK_NVME_TRANSPORT_TCP,
        .adrfam = SPDK_NVMF_ADRFAM_IPV4,
    };
    strcpy(trid1.traddr, "192.168.1.10");
    strcpy(trid1.trsvcid, "4420");
    strcpy(trid1.subnqn, "nqn.2016-06.io.spdk:cnode1");
    
    xnvmf_subsystem_add_path(subsys, &trid1);
    
    // Create I/O channel (per thread)
    xnvmfIoChannel *channel = xnvmf_io_channel_create(subsys);
    
    // Get namespace
    xnvmfNamespace *ns = xnvmf_subsystem_get_namespace(subsys, 1);
    
    // Perform I/O
    struct iovec iov = {
        .iov_base = buffer,
        .iov_len = 4096,
    };
    
    xnvmf_namespace_read(ns, channel, &iov, 1, 0, 1, completion_cb, NULL);
    
    // Process completions
    xnvmf_io_channel_process_completions(channel, 0);
    
    // Cleanup
    xnvmf_io_channel_destroy(channel);
    xnvmf_subsystem_destroy(subsys);
    xnvmf_env_fini();
    
    return 0;
}
```

## API Overview

### Environment

- `xnvmf_env_init()` - Initialize library
- `xnvmf_env_fini()` - Cleanup library

### Subsystem (Multipath Connection)

- `xnvmf_subsystem_create()` - Create a logical NVMe-oF subsystem
- `xnvmf_subsystem_destroy()` - Destroy subsystem
- `xnvmf_subsystem_add_path()` - Add a connection path
- `xnvmf_subsystem_remove_path()` - Remove a path
- `xnvmf_subsystem_set_mp_policy()` - Set multipath policy

### I/O Channel (Per-Thread)

- `xnvmf_io_channel_create()` - Create I/O channel
- `xnvmf_io_channel_destroy()` - Destroy channel
- `xnvmf_io_channel_process_completions()` - Process I/O completions

### I/O Operations

- `xnvmf_namespace_read()` - Submit read with SGL
- `xnvmf_namespace_write()` - Submit write with SGL
- `xnvmf_namespace_flush()` - Submit flush
- `xnvmf_namespace_write_zeroes()` - Submit write zeroes

### Buffer Pool

- `xnvmf_buffer_pool_create()` - Create DMA buffer pool
- `xnvmf_buffer_pool_get()` - Get buffer from pool
- `xnvmf_buffer_pool_put()` - Return buffer to pool

## License

BSD-3-Clause