Implement libbpf ringbuf synchronous API.

Author: Michael Agun

docs/RingBuffer.md

@@ -14,15 +14,15 @@ This proposal adds support for synchronous callbacks (like libbpf on linux) and
 
 Asynchronous callback consumer:
 
-1. Call `ring_buffer__new` to set up callback with RINGBUF_FLAG_AUTO_CALLBACK specified.
-    - On Linux synchronous callbacks are always used, so the new AUTO_CALLBACK flags are Windows-specific.
-    - Note: automatic callbacks are the current default behavior, but eventually
-      this will change with [#4142](https://github.com/microsoft/ebpf-for-windows/issues/4142) to match the linux behavior so should always be specified.
+1. Call `ebpf_ring_buffer__new` to set up callback with `EBPF_RINGBUF_FLAG_AUTO_CALLBACK` specified.
+    - On Linux synchronous callbacks are always used, so the `EBPF_RINGBUF_FLAG_AUTO_CALLBACK` flag is Windows-specific.
+    - Note: automatic callbacks were the original default behavior, but the default has been changed to be source-compatible with Linux.
 2. The callback will be invoked for each record written to the ring buffer.
 
 Synchronous callback consumer:
 
-1. Call `ring_buffer__new` to set up callback with RINGBUF_FLAG_NO_AUTO_CALLBACK specified.
+1. Call `ring_buffer__new` to set up callback (uses synchronous mode by default to match Linux).
+   - Or call `ebpf_ring_buffer__new` with `EBPF_RINGBUF_FLAG_NO_AUTO_CALLBACK` for explicit synchronous mode.
 2. Call `ring_buffer__poll()` to wait for data if needed and invoke the callback on all available records.
 
 Mapped memory consumer:
@@ -41,35 +41,28 @@ On linux `ring_buffer__poll()` and `ring_buffer__consume()` are used to invoke t
 `poll()` waits for available data (or until timeout), then consume all available records.
 `consume()` consumes all available records (without waiting).
 
-Windows will initially only support `ring_buffer__poll()`, which can be called with a timeout of zero
-to get the same behaviour as `ring_buffer__consume()`.
+Windows now supports both `ring_buffer__poll()` and `ring_buffer__consume()`, with Linux-compatible behavior.
+`ring_buffer__consume()` is equivalent to calling `ring_buffer__poll()` with a timeout of zero.
 
 #### Asynchronous callbacks
 
-On Linux ring buffers currently support only synchronous callbacks (using poll/consume).
-In contrast, Windows eBPF currently supports only asynchronous ring buffer callbacks,
-where the callback is automatically invoked when data is available.
+On Linux ring buffers support only synchronous callbacks (using poll/consume).
+Windows eBPF now supports both synchronous callbacks (default, matching Linux) and asynchronous ring buffer callbacks.
 
-This proposal adds support for synchronous consumers by setting the `RINGBUF_FLAG_NO_AUTO_CALLBACK` flag.
-With the flag set, callbacks will not automatically be called.
-To invoke the callback and `ring_buffer__poll()`
-should be called to poll for available data and invoke the callback.
-On Windows a timeout of zero can be passed to `ring_buffer__poll()` to get the same behaviour as `ring_buffer__consume()` (consume available records without waiting).
-
-When #4142 is resolved the default behaviour will be changed from asynchronous (automatic) to synchronous callbacks,
-so `RINGBUF_FLAG_AUTO_CALLBACK` should always be specified for asynchronous callbacks for forward-compatibility.
+For synchronous callbacks (Linux-compatible), use the default behavior with `ring_buffer__new()`.
+For asynchronous callbacks (Windows-specific), use `ebpf_ring_buffer__new()` with the `EBPF_RINGBUF_FLAG_AUTO_CALLBACK` flag.
 
 #### Memory mapped consumers
 
 As an alternative to callbacks, Linux ring buffer consumers can directly access the
 ring buffer data by calling `mmap()` on a ring_buffer map fd to map the data into user space.
 `ring_buffer__epoll_fd()` is used on Linux to get an fd to use with epoll to wait for data.
 
-Windows doesn't have directly compatible APIs to Linux mmap and epoll, so instead we will perfom the mapping
+Windows doesn't have directly compatible APIs to Linux mmap and epoll, so instead we perform the mapping
 in the eBPF core and use a KEVENT to signal for new data.
 
-For direct memory mapped consumers on Windows, use `ebpf_ring_buffer_get_buffer` to get pointers to the producer and consumer
-pages mapped into user space, and `ebpf_ring_buffer_get_wait_handle()` to get the SynchronizationEvent (auto-reset) KEVENT
+For direct memory mapped consumers on Windows, use `ebpf_ring_buffer_map_map_buffer` to get pointers to the producer and consumer
+pages mapped into user space, and `ebpf_map_set_wait_handle()` to set a HANDLE
 to use with `WaitForSingleObject`/`WaitForMultipleObject`.
 
 Similar to the linux memory layout, the first pages of the shared ring buffer memory are the "producer page" and "consumer page",
@@ -97,53 +90,95 @@ ebpf_result_t
 ebpf_ring_buffer_output(_Inout_ ebpf_ring_buffer_t* ring, _In_reads_bytes_(length) uint8_t* data, size_t length, size_t flags)
 ```
 
-_Note:_ The currently internal `ebpf_ring_buffer_record.h` with helpers for working with raw records will also be made public.
+**Note:** The currently internal `ebpf_ring_buffer_record.h` with helpers for working with raw records will also be made public.
 
 #### Updated libbpf API for callback consumer
 
-The default behaviour of these functions will be unchanged for now.
+The default behaviour of these functions has been updated to use synchronous callbacks to match Linux libbpf behavior.
+
+Use `ring_buffer__new()` (defaults to synchronous mode) or `ebpf_ring_buffer__new()` with `EBPF_RINGBUF_FLAG_AUTO_CALLBACK` to set up automatic callbacks for each record.
+Use `ring_buffer__new()` (default behavior) or `ebpf_ring_buffer__new()` with `EBPF_RINGBUF_FLAG_NO_AUTO_CALLBACK` to set up synchronous callbacks that are invoked via `ring_buffer__poll()` or `ring_buffer__consume()`.
 
-Use the existing `ring_buffer__new()` to set up automatic callbacks for each record.
-Call `ebpf_ring_buffer_get_buffer()` ([New eBPF APIs](#new-ebpf-apis-for-mapped-memory-consumer))
+Call `ebpf_ring_buffer_map_map_buffer()` ([New eBPF APIs](#new-ebpf-apis-for-mapped-memory-consumer))
 to get direct access to the mapped ring buffer memory.
 
+For Windows-specific functionality, use the `ebpf_ring_buffer__*` variants which accept `ebpf_ring_buffer_opts` with flags.
+
 ```c
 struct ring_buffer;
 
 typedef int (*ring_buffer_sample_fn)(_Inout_ void *ctx, _In_reads_bytes_(size) void *data, size_t size);
 
 struct ring_buffer_opts {
   size_t sz; /* size of this struct, for forward/backward compatiblity */
+};
+
+/* Windows-specific extended options */
+struct ebpf_ring_buffer_opts {
+  size_t sz; /* size of this struct, for forward/backward compatiblity */
   uint64_t flags; /* ring buffer option flags */
 };
 
-// Ring buffer manager options.
-// - The default behaviour is currently automatic callbacks, but may change in the future per #4142.
+// Ring buffer manager options (Windows-specific).
+// - The default behaviour is now synchronous callbacks to match Linux libbpf.
 // - Only specify one of AUTO_CALLBACKS or NO_AUTO_CALLBACKS - specifying both is not allowed.
-enum ring_buffer_flags {
-  RINGBUF_FLAG_AUTO_CALLBACK = (uint64_t)1 << 0 /* Automatically invoke callback for each record */
-  RINGBUF_FLAG_NO_AUTO_CALLBACK = (uint64_t)2 << 0 /* Don't automatically invoke callback for each record */
+enum ebpf_ring_buffer_flags {
+  EBPF_RINGBUF_FLAG_AUTO_CALLBACK = (uint64_t)1 << 0, /* Automatically invoke callback for each record */
+  EBPF_RINGBUF_FLAG_NO_AUTO_CALLBACK = (uint64_t)1 << 1, /* Don't automatically invoke callback for each record */
 };
 
 #define ring_buffer_opts__last_field sz
+#define ebpf_ring_buffer_opts__last_field flags
 
 /**
- * @brief Creates a new ring buffer manager.
+ * @brief Creates a new ring buffer manager (Linux-compatible).
  *
+ * Uses synchronous callbacks by default (matching Linux libbpf behavior).
  * Only one consumer can be attached at a time, so it should not be called multiple times on an fd.
  *
  * If the return value is NULL the error will be returned in errno.
  *
  * @param[in] map_fd File descriptor to ring buffer map.
  * @param[in] sample_cb Pointer to ring buffer notification callback function (if used).
  * @param[in] ctx Pointer to sample_cb callback function context.
- * @param[in] opts Ring buffer options.
+ * @param[in] opts Ring buffer options (currently unused, should be NULL).
  *
  * @returns Pointer to ring buffer manager.
  */
 struct ring_buffer *
 ring_buffer__new(int map_fd, ring_buffer_sample_fn sample_cb, _Inout_ void *ctx,
-		 _In_ const struct ring_buffer_opts *opts);
+                 _In_opt_ const struct ring_buffer_opts *opts);
+
+/**
+ * @brief Creates a new ring buffer manager (Windows-specific with flags).
+ *
+ * Only one consumer can be attached at a time, so it should not be called multiple times on an fd.
+ *
+ * If the return value is NULL the error will be returned in errno.
+ *
+ * @param[in] map_fd File descriptor to ring buffer map.
+ * @param[in] sample_cb Pointer to ring buffer notification callback function (if used).
+ * @param[in] ctx Pointer to sample_cb callback function context.
+ * @param[in] opts Ring buffer options with Windows-specific flags.
+ *
+ * @returns Pointer to ring buffer manager.
+ */
+struct ring_buffer *
+ebpf_ring_buffer__new(int map_fd, ring_buffer_sample_fn sample_cb, _Inout_ void *ctx,
+                      _In_opt_ const struct ebpf_ring_buffer_opts *opts);
+
+/**
+ * @brief Add another ring buffer map to the ring buffer manager.
+ *
+ * @param[in] rb Ring buffer manager.
+ * @param[in] map_fd File descriptor to ring buffer map.
+ * @param[in] sample_cb Pointer to ring buffer notification callback function.
+ * @param[in] ctx Pointer to sample_cb callback function context.
+ *
+ * @retval 0 Success.
+ * @retval <0 Error.
+ */
+int ring_buffer__add(struct ring_buffer *rb, int map_fd, ring_buffer_sample_fn sample_cb, void *ctx);
 
 /**
  * @brief poll ringbuf for new data
@@ -152,15 +187,26 @@ ring_buffer__new(int map_fd, ring_buffer_sample_fn sample_cb, _Inout_ void *ctx,
  * If timeout_ms is zero, poll will not wait but only invoke the callback on records that are ready.
  * If timeout_ms is -1, poll will wait until data is ready (no timeout).
  *
- * This function is only supported when automatic callbacks are disabled (see RINGBUF_FLAG_NO_AUTO_CALLBACK).
+ * This function is only supported when automatic callbacks are disabled.
  *
  * @param[in] rb Pointer to ring buffer manager.
  * @param[in] timeout_ms Maximum time to wait for (in milliseconds).
  *
- * @returns Number of records consumed, INT_MAX, or a negative number on error
+ * @returns Number of records consumed, or a negative number on error
  */
 int ring_buffer__poll(_In_ struct ring_buffer *rb, int timeout_ms);
 
+/**
+ * @brief consume available records without waiting
+ *
+ * Equivalent to ring_buffer__poll() with timeout_ms=0.
+ *
+ * @param[in] rb Pointer to ring buffer manager.
+ *
+ * @returns Number of records consumed, or a negative number on error
+ */
+int ring_buffer__consume(_In_ struct ring_buffer *rb);
+
 /**
  * @brief Frees a ring buffer manager.
  *
@@ -219,6 +265,7 @@ typedef struct _ebpf_ring_buffer_producer_page
  * Multiple calls will return the same pointers, as the ring buffer manager only maps the ring once.
  *
  * @param[in] rb Pointer to ring buffer manager.
+ * @param[in] index Index of the map in the ring buffer manager (0-based).
  * @param[out] producer_page Pointer to start of read-only mapped producer page.
  * @param[out] consumer_page Pointer to start of read-write mapped consumer page.
  * @param[out] data Pointer to start of read-only double-mapped data pages.
@@ -229,6 +276,7 @@ typedef struct _ebpf_ring_buffer_producer_page
  */
 ebpf_result_t ebpf_ring_buffer_get_buffer(
     _In_ struct ring_buffer *rb,
+    _In_ uint32_t index,
     _Out_ ebpf_ring_buffer_consumer_page_t **consumer_page,
     _Out_ const ebpf_ring_buffer_producer_page_t **producer_page,
     _Outptr_result_buffer_(*data_size) const uint8_t **data,
@@ -399,23 +447,20 @@ For(;;) {
 Exit:
 ```
 
-#### Polling ring buffer consumer (using ringbuf manager)
+#### Polling ring buffer consumer (using ringbuf manager, matches Linux code)
 
 ```c
 // sample callback
 int ring_buffer_sample_fn(void *ctx, void *data, size_t size) {
   // … business logic to handle record …
+  return 0;
 }
 
 // consumer code
-struct ring_buffer_opts opts;
-opts.sz = sizeof(opts);
-opts.flags = RINGBUF_FLAG_NO_AUTO_CALLBACK; //no automatic callbacks
-
 fd_t map_fd = bpf_obj_get(rb_map_name.c_str());
 if (map_fd == ebpf_fd_invalid) return 1;
 
-struct ring_buffer *rb = ring_buffer__new(map_fd, ring_buffer_sample_fn sample_cb, &opts);
+struct ring_buffer *rb = ring_buffer__new(map_fd, ring_buffer_sample_fn, nullptr, nullptr);
 if (rb == NULL) return 1;
 
 // now loop as long as there isn't an error
@@ -426,10 +471,40 @@ while(ring_buffer__poll(rb, -1) >= 0) {
 ring_buffer__free(rb);
 ```
 
+#### Asynchronous ring buffer consumer (Windows-specific)
+
+```c
+// sample callback - this will be called automatically for each record
+int ring_buffer_sample_fn(void *ctx, void *data, size_t size) {
+  // … business logic to handle record …
+  return 0;
+}
+
+// consumer code
+fd_t map_fd = bpf_obj_get(rb_map_name.c_str());
+if (map_fd == ebpf_fd_invalid) return 1;
 
-### Linux consumer examples (for comparison)
+// Set up Windows-specific ring buffer options for automatic callbacks
+struct ebpf_ring_buffer_opts opts = {};
+opts.sz = sizeof(opts);
+opts.flags = EBPF_RINGBUF_FLAG_AUTO_CALLBACK; // Enable automatic callbacks
 
-#### Linux direct mmap consumer
+struct ring_buffer *rb = ebpf_ring_buffer__new(map_fd, ring_buffer_sample_fn, nullptr, &opts);
+if (rb == NULL) return 1;
+
+// With automatic callbacks, the callback function is invoked immediately
+// when each record is written to the ring buffer. No polling is needed.
+// The ring buffer manager handles the processing automatically.
+
+// Keep the application running while callbacks are processed
+// (actual application logic would determine when to exit)
+Sleep(60000); // Sleep for 60 seconds or until application should exit
+
+ring_buffer__free(rb);
+```
+
+
+### Linux direct mmap consumer example (for comparison)
 
 ```c
 size_t page_size = 4096;
@@ -538,28 +613,6 @@ munmap(producer, mmap_sz);
 close(map_fd);
 ```
 
-#### Linux ring buffer manager consumer
-
-```c
-// sample callback
-int ring_buffer_sample_fn(void *ctx, void *data, size_t size) {
-  // … business logic to handle record …
-}
-
-fd_t map_fd = bpf_obj_get(rb_map_name.c_str());
-if (map_fd == ebpf_fd_invalid) return 1;
-
-struct ring_buffer *rb = ring_buffer__new(map_fd, ring_buffer_sample_fn sample_cb, NULL);
-if (rb == NULL) return 1;
-
-// now loop as long as there isn't an error
-while(ring_buffer__poll(rb, -1) >= 0) {
-  // data processed by event callback
-}
-
-ring_buffer__free(rb);
-```
-
 *Below implementation details of the internal ring buffer data structure are discussed.*
 
 ## Internal Ring Buffer

ebpfapi/Source.def

@@ -142,6 +142,8 @@ EXPORTS
     ebpf_program_query_info
     ebpf_program_synchronize
     ebpf_ring_buffer__new
+    ebpf_ring_buffer_get_buffer
+    ebpf_ring_buffer_get_wait_handle
     ebpf_ring_buffer_map_map_buffer
     ebpf_ring_buffer_map_unmap_buffer
     ebpf_ring_buffer_map_write
@@ -160,5 +162,8 @@ EXPORTS
     libbpf_strerror
     perf_buffer__free
     perf_buffer__new
+    ring_buffer__add
+    ring_buffer__consume
     ring_buffer__free
     ring_buffer__new
+    ring_buffer__poll