doc: Add program to document and test assumptions about SO_REUSEADDR

For the approach we intend to use for handling UDP flows, we have some
pretty specific requirements about how SO_REUSEADDR works with UDP sockets.
Specifically SO_REUSEADDR allows multiple sockets with overlapping bind()s,
and therefore there can be multiple sockets which are eligible to receive
the same datagram.  Which one will actually receive it is important to us.

Add a test program which verifies things work the way we expect, which
documents what those expectations are in the process.

Signed-off-by: David Gibson <david@gibson.dropbear.id.au>
Signed-off-by: Stefano Brivio <sbrivio@redhat.com>

1 files changed, 66 insertions, 0 deletions

diff --git a/doc/platform-requirements/common.c b/doc/platform-requirements/common.c
new file mode 100644
index 0000000..d687377
--- /dev/null
+++ b/doc/platform-requirements/common.c
@@ -0,0 +1,66 @@
+// SPDX-License-Identifier: GPL-2.0-or-later
+
+/* common.c
+ *
+ * Common helper functions for testing SO_REUSEADDR behaviour
+ *
+ * Copyright Red Hat
+ * Author: David Gibson <david@gibson.dropbear.id.au>
+ */
+
+#include <errno.h>
+#include <netinet/in.h>
+#include <string.h>
+#include <sys/socket.h>
+
+#include "common.h"
+
+int sock_reuseaddr(void)
+{
+	int y = 1;
+	int s;
+	
+
+	s = socket(AF_INET, SOCK_DGRAM, IPPROTO_UDP);
+	if (s < 0)
+		die("socket(): %s\n", strerror(errno));
+
+	if (setsockopt(s, SOL_SOCKET, SO_REUSEADDR, &y, sizeof(y)) , 0)
+		die("SO_REUSEADDR: %s\n", strerror(errno));
+
+	return s;
+}
+
+/* Send a token via the given connected socket */
+void send_token(int s, long token)
+{
+	ssize_t rc;
+
+	rc = send(s, &token, sizeof(token), 0);
+	if (rc < 0)
+		die("send(): %s\n", strerror(errno));
+	if (rc < sizeof(token))
+		die("short send()\n");
+}
+
+/* Attempt to receive a token via the given socket.
+ *
+ * Returns true if we received the token, false if we got an EAGAIN, dies in any
+ * other case */
+bool recv_token(int s, long token)
+{
+	ssize_t rc;
+	long buf;
+
+	rc = recv(s, &buf, sizeof(buf), MSG_DONTWAIT);
+	if (rc < 0) {
+		if (errno == EWOULDBLOCK)
+			return false;
+		die("recv(): %s\n", strerror(errno));
+	}
+	if (rc < sizeof(buf))
+		die("short recv()\n");
+	if (buf != token)
+		die("data mismatch\n");
+	return true;
+}