os: introduce C-API to Genode services

This commit introduces a C-API to the Uplink session, as well as to
serve as a Block service. It can be used by drivers ported from
C-only projects, like the Linux kernel, or BSD kernels for instance.

Fix #4226

repos/os/include/genode_c_api/uplink.h

@@ -0,0 +1,107 @@
+/*
+ * \brief  C interface to Genode's uplink session
+ * \author Norman Feske
+ * \date   2021-07-06
+ */
+
+/*
+ * Copyright (C) 2006-2017 Genode Labs GmbH
+ *
+ * This file is part of the Genode OS framework, which is distributed
+ * under the terms of the GNU Affero General Public License version 3.
+ */
+
+#ifndef _INCLUDE__GENODE_C_API__UPLINK_H_
+#define _INCLUDE__GENODE_C_API__UPLINK_H_
+
+#include <genode_c_api/base.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * Initialize uplink handling
+ *
+ * \param sigh  signal handler to be installed at the uplink connection
+ */
+void genode_uplink_init(struct genode_env *,
+                        struct genode_allocator *,
+                        struct genode_signal_handler *);
+
+/**
+ * Wake up uplink server if progress can be made at the server side
+ *
+ * This function should be called whenever the component becomes idle.
+ */
+void genode_uplink_notify_peers(void);
+
+
+
+struct genode_uplink;  /* definition is private to the implementation */
+
+
+/*********************
+ ** Uplink lifetime **
+ *********************/
+
+struct genode_uplink_args
+{
+	unsigned char mac_address[6];
+	char const *label;
+};
+
+struct genode_uplink *genode_uplink_create(struct genode_uplink_args const *);
+
+void genode_uplink_destroy(struct genode_uplink *);
+
+
+/*************************************************
+ ** Transmit packets towards the uplink session **
+ *************************************************/
+
+struct genode_uplink_tx_packet_context;
+
+/**
+ * Callback called by 'genode_uplink_tx_packet' to provide the content
+ */
+typedef unsigned long (*genode_uplink_tx_packet_content_t)
+	(struct genode_uplink_tx_packet_context *, char *dst, unsigned long dst_len);
+
+/**
+ * Process packet transmission
+ *
+ * \return true if progress was made
+ */
+bool genode_uplink_tx_packet(struct genode_uplink *,
+                             genode_uplink_tx_packet_content_t,
+                             struct genode_uplink_tx_packet_context *);
+
+
+/*********************************************
+ ** Receive packets from the uplink session **
+ *********************************************/
+
+struct genode_uplink_rx_context;
+
+typedef enum { GENODE_UPLINK_RX_REJECTED,
+               GENODE_UPLINK_RX_ACCEPTED,
+               GENODE_UPLINK_RX_RETRY } genode_uplink_rx_result_t;
+
+typedef genode_uplink_rx_result_t (*genode_uplink_rx_one_packet_t)
+	(struct genode_uplink_rx_context *, char const *ptr, unsigned long len);
+
+/**
+ * Process packet reception
+ *
+ * \return true if progress was made
+ */
+bool genode_uplink_rx(struct genode_uplink *,
+                      genode_uplink_rx_one_packet_t rx_one_packet,
+                      struct genode_uplink_rx_context *);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* _INCLUDE__GENODE_C_API__UPLINK_H_ */