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
- ceph/ceph#60844

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

Author: Rakshith-R

docs/api-status.json

@@ -1953,6 +1953,12 @@
         "comment": "GroupSnapGetInfo returns a slice of RBD image snapshots that are part of a\ngroup snapshot.\n\nImplements:\n\n\tint rbd_group_snap_get_info(rados_ioctx_t group_p,\n\t                        const char *group_name,\n\t                        const char *snap_name,\n\t                        rbd_group_snap_info2_t *snaps);\n",
         "added_in_version": "v0.30.0",
         "expected_stable_version": "v0.32.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\nDiffIterateConfig 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                      uint8_t include_parent, uint8_t whole_object,\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 | 
 ---- | ---------------- | ----------------------- | 
 GroupSnapGetInfo | v0.30.0 | v0.32.0 | 
+Image.DiffIterateByID | $NEXT_RELEASE | $NEXT_RELEASE_STABLE | 
 
 ### Deprecated APIs
 

rbd/diff_iterate_by_id.go

@@ -0,0 +1,93 @@
+//go:build ceph_preview
+
+package rbd
+
+/*
+#cgo LDFLAGS: -lrbd
+#undef _GNU_SOURCE
+#include <errno.h>
+#include <stdlib.h>
+#include <rbd/librbd.h>
+
+// inline wrapper to cast uintptr_t to void*
+static inline int wrap_rbd_diff_iterate3(rbd_image_t image,
+	uint64_t from_snap_id, uint64_t ofs, uint64_t len, uint8_t include_parent,
+	uint8_t whole_object, uintptr_t arg) {
+		return rbd_diff_iterate3(image, from_snap_id, ofs, len, include_parent,
+			whole_object, (void*)diffIterateCallback, (void*)arg);
+};
+*/
+import "C"
+
+import (
+	"fmt"
+	"sync"
+
+	"github.com/ceph/go-ceph/internal/dlsym"
+)
+
+var (
+	diffIterateByIDOnce sync.Once
+	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
+// DiffIterateConfig 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,
+//	                      uint8_t include_parent, uint8_t whole_object,
+//	                      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() {
+		_, diffIterateByIdErr = dlsym.LookupSymbol("rbd_diff_iterate3")
+	})
+
+	if diffIterateByIdErr != nil {
+		return fmt.Errorf("%w: %w", ErrNotImplemented, diffIterateByIdErr)
+	}
+
+	cbIndex := diffIterateCallbacks.Add(config)
+	defer diffIterateCallbacks.Remove(cbIndex)
+
+	ret := C.wrap_rbd_diff_iterate3(
+		image.image,
+		C.uint64_t(config.FromSnapID),
+		C.uint64_t(config.Offset),
+		C.uint64_t(config.Length),
+		C.uint8_t(config.IncludeParent),
+		C.uint8_t(config.WholeObject),
+		C.uintptr_t(cbIndex))
+
+	return getError(ret)
+}