[Feature] Add an extensible NVMe namespace information API #34

Background

PR #33 adds namespace-capacity querying for LMCache initialization. A follow-up API should expose the distinct NVMe namespace size, capacity, utilization, and LBA size while preserving room for future ABI-compatible extension.

Proposed API

uGDSError_t uGDSGetDeviceSize(
    uGDSHandle_t fh,
    uint64_t* size_bytes);         /* NSZE */

uGDSError_t uGDSGetDeviceCapacity(
    uGDSHandle_t fh,
    uint64_t* capacity_bytes);     /* NCAP */

Add an extensible namespace information structure:

#define UGDS_NAMESPACE_INFO_VERSION 1

typedef struct uGDSNamespaceInfo {
    uint32_t struct_size;
    uint32_t version;

    uint64_t size_bytes;           /* NSZE × LBA size */
    uint64_t capacity_bytes;       /* NCAP × LBA size */
    uint64_t utilization_bytes;    /* NUSE × LBA size */

    uint32_t lba_size_bytes;
    uint32_t reserved0;

    uint64_t reserved[4];
} uGDSNamespaceInfo_t;

uGDSError_t uGDSGetNamespaceInfo(
    uGDSHandle_t fh,
    uGDSNamespaceInfo_t* info);

ABI requirements

• The caller sets struct_size to sizeof(uGDSNamespaceInfo_t).
• The library must not write beyond the caller-provided struct_size.
• New fields may only consume reserved space or be appended to the structure.
• Existing field offsets, types, and semantics must not change.
• An older caller used with a newer library must not receive an out-of-bounds write.
• A newer caller used with an older library should zero-initialize the structure so unsupported fields remain zero.

Semantics

• size_bytes is NSZE × lba_size and represents the legal byte-address range.
• capacity_bytes is NCAP × lba_size and represents the maximum allocatable namespace capacity.
• utilization_bytes is NUSE × lba_size.
• NSZE, NCAP, and LBA size may use the Identify Namespace data cached during handle registration.
• NUSE is dynamic. uGDSGetNamespaceInfo() should issue a fresh Identify Namespace command and serialize access to the shared Admin Queue instead of returning the registration-time snapshot.

Testing

• Verify NSZE, NCAP, NUSE, and LBA-to-byte conversion with deterministic unit tests.
• Cover zero values and multiplication overflow.
• Cover callers using smaller and larger struct_size values.
• Add a concurrent namespace-query/handle-deregister test.
• Include a synthetic thin-provisioning case where NSZE > NCAP.