libxdp: Doc and test adaptation for XSk umem opts-creation

Change documentation and test codes for creating XSk umem
by opts, with minor format fix.

Signed-off-by: Muyang Tian <[email protected]>

lib/libxdp/README.org

@@ -267,10 +267,14 @@ BPF maps which is a must if users want to add their own XDP program.
 
 If there is already a socket created with socket(AF_XDP, SOCK_RAW, 0)
 not bound and not tied to any umem, file descriptor of this socket can
-be used in an xsk_umem__create_with_fd() variant of the umem creation
-function.
+be used in param opts of xsk_umem__create_opts(), which is a recommended
+way of umem creation.
 
 #+begin_src C
+struct xsk_umem *xsk_umem__create_opts(void *umem_area,
+				       struct xsk_ring_prod *fill,
+				       struct xsk_ring_cons *comp,
+				       struct xsk_umem_opts *opts);
 int xsk_umem__create(struct xsk_umem **umem,
 		     void *umem_area, __u64 size,
 		     struct xsk_ring_prod *fill,
@@ -324,8 +328,8 @@ int xsk_socket__update_xskmap(struct xsk_socket *xsk, int xsks_map_fd);
 
 To further reduce required level of privileges, an AF_XDP socket can be created
 beforehand with socket(AF_XDP, SOCK_RAW, 0) and passed to a non-privileged
-process.  This socket can be used in xsk_umem__create_with_fd() and later
-in xsk_socket__create() with created umem.  xsk_socket__create_shared() would
+process.  This socket can be used in xsk_umem__create_opts() and later in
+xsk_socket__create() with created umem.  xsk_socket__create_shared() would
 still require privileges for AF_XDP socket creation.
 
 ** Data path

lib/libxdp/libxdp.3

@@ -301,12 +301,16 @@ BPF maps which is a must if users want to add their own XDP program.
 .PP
 If there is already a socket created with socket(AF_XDP, SOCK_RAW, 0)
 not bound and not tied to any umem, file descriptor of this socket can
-be used in an xsk_umem__create_with_fd() variant of the umem creation
-function.
+be used in param opts of xsk_umem__create_opts(), which is a recommended
+way of umem creation.
 
 .RS
 .nf
-\fCint xsk_umem__create(struct xsk_umem **umem,
+\fCstruct xsk_umem *xsk_umem__create_opts(void *umem_area,
+				       struct xsk_ring_prod *fill,
+				       struct xsk_ring_cons *comp,
+				       struct xsk_umem_opts *opts);
+int xsk_umem__create(struct xsk_umem **umem,
                      void *umem_area, __u64 size,
                      struct xsk_ring_prod *fill,
                      struct xsk_ring_cons *comp,
@@ -370,8 +374,8 @@ int xsk_socket__update_xskmap(struct xsk_socket *xsk, int xsks_map_fd);
 .PP
 To further reduce required level of privileges, an AF_XDP socket can be created
 beforehand with socket(AF_XDP, SOCK_RAW, 0) and passed to a non-privileged
-process.  This socket can be used in xsk_umem__create_with_fd() and later
-in xsk_socket__create() with created umem.  xsk_socket__create_shared() would
+process.  This socket can be used in xsk_umem__create_opts() and later in
+xsk_socket__create() with created umem.  xsk_socket__create_shared() would
 still require privileges for AF_XDP socket creation.
 
 .SS "Data path"

lib/libxdp/tests/test_xsk_non_privileged.c

@@ -123,6 +123,46 @@ static struct xsk_umem *create_umem_non_privileged(int sock_fd)
 	return umem;
 }
 
+/* Should use this to replace create_umem_non_privileged() once 
+ * xsk_umem__create() and xsk_umem__create_with_fd() are deprecated.
+ */
+static struct xsk_umem *create_umem_non_privileged_by_opts(int sock_fd)
+{
+	struct xsk_ring_cons cq;
+	struct xsk_ring_prod fq;
+	struct xsk_umem *umem;
+	void *b;
+
+	if (posix_memalign(&b, getpagesize(), UMEM_SIZE)) {
+		perror("posix_memalign failed");
+		exit(EXIT_FAILURE);
+	}
+
+	/* Opts initialized with fd unset */
+	DECLARE_LIBXDP_OPTS(xsk_umem_opts, opts,
+		.size = UMEM_SIZE,
+		.fill_size = XSK_RING_PROD__DEFAULT_NUM_DESCS,
+		.comp_size = XSK_RING_CONS__DEFAULT_NUM_DESCS,
+		.frame_size = XSK_UMEM__DEFAULT_FRAME_SIZE,
+	);
+	/* This variant requires CAP_NET_RAW, so should fail. */
+	umem = xsk_umem__create_opts(b, &fq, &cq, &opts);
+	if (umem) {
+		perror("xsk_umem__create_opts succeeded");
+		exit(EXIT_FAILURE);
+	}
+
+	/* This variant shouldn't need any capabilities, so should pass. */
+	opts.fd = sock_fd;
+	umem = xsk_umem__create_opts(b, &fq, &cq, &opts);
+	if (!umem) {
+		perror("xsk_umem__create_opts failed");
+		exit(EXIT_FAILURE);
+	}
+
+	return umem;
+}
+
 static struct xsk_socket *create_xsk_non_privileged(const char *ifname,
 						    struct xsk_umem *umem,
 						    int queue_id)

lib/libxdp/tests/test_xsk_refcnt.c

@@ -107,16 +107,17 @@ static struct xsk_socket_info *xsks[MAX_NUM_QUEUES];
 static struct xsk_umem_info *xsk_configure_umem(void *buffer, u64 size)
 {
 	struct xsk_umem_info *umem;
-	int ret;
 
 	umem = calloc(1, sizeof(*umem));
 	if (!umem)
 		exit(EXIT_FAILURE);
 
-	ret = xsk_umem__create(&umem->umem, buffer, size, &umem->fq, &umem->cq,
-			       NULL);
-	if (ret)
-		exit(ret);
+	DECLARE_LIBXDP_OPTS(xsk_umem_opts, opts,
+		.size = size,
+	);
+	umem->umem = xsk_umem__create_opts(buffer, &umem->fq, &umem->cq, &opts);
+	if (!umem->umem)
+		exit(errno);
 
 	umem->buffer = buffer;
 	return umem;

lib/libxdp/xsk.c

@@ -350,7 +350,7 @@ struct xsk_umem *xsk_umem__create_opts(void *umem_area,
 
 	mr_size = sizeof(mr);
 	/* Older kernels don't support tx_metadata_len, skip if we are not setting a value */
-	if(!mr.tx_metadata_len)
+	if (!mr.tx_metadata_len)
 		mr_size = offsetof(struct xdp_umem_reg, tx_metadata_len);
 	err = setsockopt(umem->fd, SOL_XDP, XDP_UMEM_REG, &mr, mr_size);
 	if (err) {
@@ -381,7 +381,7 @@ int xsk_umem__create_with_fd(struct xsk_umem **umem_ptr, int fd,
 {
 	struct xsk_umem *umem;
 
-	if(!umem_ptr)
+	if (!umem_ptr)
 		return -EFAULT;
 
 	DECLARE_LIBXDP_OPTS(xsk_umem_opts, opts,
@@ -396,7 +396,7 @@ int xsk_umem__create_with_fd(struct xsk_umem **umem_ptr, int fd,
 		opts.flags = usr_config->flags;
 	}
 	umem = xsk_umem__create_opts(umem_area, fill, comp, &opts);
-	if(!umem)
+	if (!umem)
 		return errno;
 
 	*umem_ptr = umem;