KVDB: combined field vs. "single KV must fit in one sector" limitation

[vmut0228]

### Question: `combined` field exists but single KV cannot span sectors

Hi maintainer,

I’m reading the KVDB implementation and noticed a possible mismatch between the `combined` design and the actual behavior when writing a large KV (blob).

#### What I found

In KVDB sector information:

```c
/* KVDB section information */
struct kvdb_sec_info {
    bool check_ok;                               /**< sector header check is OK */
    struct {
        fdb_sector_store_status_t store;         /**< sector store status */
        fdb_sector_dirty_status_t dirty;         /**< sector dirty status */
    } status;
    uint32_t addr;                               /**< sector start address */
    uint32_t magic;                              /**< magic word */
    uint32_t combined;                           /**< the combined next sector number, 0xFFFFFFFF: not combined */
    size_t remain;                               /**< remain size */
    uint32_t empty_kv;                           /**< the next empty KV node start address */
};

The combined field is documented as “the combined next sector number”, which sounds like a sector-chaining mechanism.

However, in create_kv_blob(...), a single KV is explicitly required to fit into one sector:

kv_hdr.len = KV_HDR_DATA_SIZE
           + FDB_WG_ALIGN(kv_hdr.name_len)
           + FDB_WG_ALIGN(kv_hdr.value_len);

/* single KV must fit in one sector, currently no spanning-sector KV support */
if (kv_hdr.len > db_sec_size(db) - SECTOR_HDR_DATA_SIZE) {
    FDB_INFO("Error: The KV size is too big\n");
    return FDB_SAVED_FULL;
}

So when a blob is larger than one sector (minus sector header), the operation fails instead of spanning multiple sectors.

Questions

1. What is the original purpose of the combined field in KVDB?

   • Is it intended only for GC / sector migration / wear-leveling bookkeeping rather than for a single KV spanning multiple sectors?

2. Is support for spanning a single KV across multiple sectors planned, or available in another branch/version?

3. If spanning is not planned, would it make sense to clarify the meaning of combined (comment or documentation) to avoid confusion?

Context

My use case is a single KVDB instance on a dedicated flash bank.
For blobs larger than one sector, the current behavior (FDB_SAVED_FULL) is clear from the code, but the combined naming/comment initially suggested that sector chaining might be supported.

Thanks for your time and clarification.

[armink]

1. What is the original purpose of the combined field in KVDB?

• Is it intended only for GC / sector migration / wear-leveling bookkeeping rather than for a single KV spanning multiple sectors?

The combined field was originally reserved for a planned “combined mode” feature, which was intended for future extension.

However, this feature is currently on hold and has not been implemented.

---

2. Is support for spanning a single KV across multiple sectors planned, or available in another branch/version?

Currently, this capability is not supported.

Unless the above-mentioned combined mode is implemented in the future, a single KV cannot span multiple sectors.

As a workaround, it is possible to increase the logical sector size before initializing KVDB, for example:

fdb_kvdb_control(&kvdb, FDB_KVDB_CTRL_SET_SEC_SIZE, &sec_size);

By increasing the sector size, larger KV entries can be stored within a single sector.

---

3. If spanning is not planned, would it make sense to clarify the meaning of combined (comment or documentation) to avoid confusion?

There should already be a TODO comment in the code indicating the intended purpose of the combined field.

If it is not clear enough, we would appreciate your help in improving or refining the documentation/comment to avoid potential confusion for future users.