rbd: add support for rbd_diff_iterate3 api

This commit adds support for rbd_diff_iterate3
through DiffIterateByID() which performs
diff interate using snapshot id instead of
snapshot name.

This is useful in cases such as when rbd snapshot is
in trash or rbd(group) snapshot in in group namespace.

refer:
- https://tracker.ceph.com/issues/65720

Signed-off-by: Rakshith R <rar@redhat.com>

Author: Rakshith-R

docs/api-status.json

@@ -1963,6 +1963,12 @@
         "comment": "EncryptionLoad2 enables IO on an open encrypted image. Multiple encryption\noption values can be passed to this call in a slice. For more information\nabout how items in the slice are applied to images, and possibly ancestor\nimages refer to the documentation in the C api for rbd_encryption_load2.\n\nImplements:\n\n\tint rbd_encryption_load2(rbd_image_t image,\n\t                         const rbd_encryption_spec_t *specs,\n\t                         size_t spec_count);\n",
         "added_in_version": "v0.32.0",
         "expected_stable_version": "v0.34.0"
+      },
+      {
+        "name": "Image.DiffIterateByID",
+        "comment": "DiffIterateByID calls a callback on changed extents of an image.\n\nCalling DiffIterateByID will cause the callback specified in the\nDiffIterateByIDConfig to be called as many times as there are changed\nregions in the image (controlled by the parameters as passed to librbd).\n\nSee the documentation of DiffIterateCallback for a description of the\narguments to the callback and the return behavior.\n\nImplements:\n\n\tint rbd_diff_iterate3(rbd_image_t image,\n\t                      uint64_t from_snap_id,\n\t                      uint64_t ofs, uint64_t len,\n\t                      uint32_t flags,\n\t                      int (*cb)(uint64_t, size_t, int, void *),\n\t                      void *arg);\n",
+        "added_in_version": "$NEXT_RELEASE",
+        "expected_stable_version": "$NEXT_RELEASE_STABLE"
       }
     ]
   },

docs/api-status.md

@@ -25,6 +25,7 @@ Conn.GetAddrs | v0.31.0 | v0.33.0 |
 Name | Added in Version | Expected Stable Version | 
 ---- | ---------------- | ----------------------- | 
 Image.EncryptionLoad2 | v0.32.0 | v0.34.0 | 
+Image.DiffIterateByID | $NEXT_RELEASE | $NEXT_RELEASE_STABLE | 
 
 ### Deprecated APIs
 

rbd/diff_iterate_by_id.go

@@ -0,0 +1,127 @@
+//go:build ceph_preview
+
+package rbd
+
+/*
+#cgo LDFLAGS: -lrbd
+#undef _GNU_SOURCE
+#include <errno.h>
+#include <stdlib.h>
+#include <rbd/librbd.h>
+
+#ifndef LIBRBD_SUPPORTS_DIFF_ITERATE3
+#define RBD_DIFF_ITERATE_FLAG_INCLUDE_PARENT (1U<<0) // SHOULD MATCH THE VALUE IN librbd.h
+#define RBD_DIFF_ITERATE_FLAG_WHOLE_OBJECT (1U<<1) // SHOULD MATCH THE VALUE IN librbd.h
+#endif
+
+extern int diffIterateByIDCallback(uint64_t, size_t, int, uintptr_t);
+
+// rbd_diff_iterate3_fn matches the rbd_diff_iterate3 function signature.
+typedef int(*rbd_diff_iterate3_fn)(rbd_image_t image, uint64_t from_snap_id,
+	uint64_t ofs, uint64_t len, uint32_t flags,
+	int (*cb)(uint64_t, size_t, int, void *), void *arg);
+
+// rbd_diff_iterate3_dlsym take *fn as rbd_diff_iterate3_fn and calls the dynamically loaded
+// rbd_diff_iterate3 function passed as 1st argument.
+static inline int rbd_diff_iterate3_dlsym(void *fn, rbd_image_t image,
+	uint64_t from_snap_id, uint64_t ofs, uint64_t len, uint32_t flags, uintptr_t arg) {
+	// cast function pointer fn to rbd_diff_iterate3 and call the function
+	return ((rbd_diff_iterate3_fn) fn)(image, from_snap_id, ofs, len, flags, (void*)diffIterateByIDCallback, (void*)arg);
+}
+*/
+import "C"
+
+import (
+	"fmt"
+	"sync"
+	"unsafe"
+
+	"github.com/ceph/go-ceph/internal/callbacks"
+	"github.com/ceph/go-ceph/internal/dlsym"
+)
+
+var (
+	diffIterateByIDCallbacks = callbacks.New()
+	diffIterateByIDOnce      sync.Once
+	diffIterateById          unsafe.Pointer
+	diffIterateByIdErr       error
+)
+
+// DiffIterateByIDConfig is used to define the parameters of a DiffIterateByID call.
+// Callback, Offset, and Length should always be specified when passed to
+// DiffIterateByID. The other values are optional.
+type DiffIterateByIDConfig struct {
+	FromSnapID    uint64
+	Offset        uint64
+	Length        uint64
+	IncludeParent DiffIncludeParent
+	WholeObject   DiffWholeObject
+	Callback      DiffIterateCallback
+	Data          interface{}
+}
+
+// DiffIterateByID calls a callback on changed extents of an image.
+//
+// Calling DiffIterateByID will cause the callback specified in the
+// DiffIterateByIDConfig to be called as many times as there are changed
+// regions in the image (controlled by the parameters as passed to librbd).
+//
+// See the documentation of DiffIterateCallback for a description of the
+// arguments to the callback and the return behavior.
+//
+// Implements:
+//
+//	int rbd_diff_iterate3(rbd_image_t image,
+//	                      uint64_t from_snap_id,
+//	                      uint64_t ofs, uint64_t len,
+//	                      uint32_t flags,
+//	                      int (*cb)(uint64_t, size_t, int, void *),
+//	                      void *arg);
+func (image *Image) DiffIterateByID(config DiffIterateByIDConfig) error {
+	if err := image.validate(imageIsOpen); err != nil {
+		return err
+	}
+	if config.Callback == nil {
+		return getError(C.EINVAL)
+	}
+
+	diffIterateByIDOnce.Do(func() {
+		diffIterateById, diffIterateByIdErr = dlsym.LookupSymbol("rbd_diff_iterate3")
+	})
+
+	if diffIterateByIdErr != nil {
+		return fmt.Errorf("%w: %w", ErrNotImplemented, diffIterateByIdErr)
+	}
+
+	cbIndex := diffIterateByIDCallbacks.Add(config)
+	defer diffIterateByIDCallbacks.Remove(cbIndex)
+
+	flags := C.uint32_t(0)
+	if config.IncludeParent == IncludeParent {
+		flags |= C.RBD_DIFF_ITERATE_FLAG_INCLUDE_PARENT
+	}
+	if config.WholeObject == EnableWholeObject {
+		flags |= C.RBD_DIFF_ITERATE_FLAG_WHOLE_OBJECT
+	}
+
+	ret := C.rbd_diff_iterate3_dlsym(
+		diffIterateById,
+		image.image,
+		C.uint64_t(config.FromSnapID),
+		C.uint64_t(config.Offset),
+		C.uint64_t(config.Length),
+		flags,
+		C.uintptr_t(cbIndex))
+
+	return getError(ret)
+}
+
+//export diffIterateByIDCallback
+func diffIterateByIDCallback(
+	offset C.uint64_t, length C.size_t, exists C.int, index uintptr) C.int {
+
+	v := diffIterateByIDCallbacks.Lookup(index)
+	config := v.(DiffIterateByIDConfig)
+	return C.int(config.Callback(
+		uint64(offset), uint64(length), int(exists), config.Data))
+}