Document the slirp API

1 files changed, 55 insertions, 9 deletions

diff --git a/src/libslirp.h b/src/libslirp.h
index 280d3d0..8862259 100644
--- a/src/libslirp.h
+++ b/src/libslirp.h
@@ -20,8 +20,10 @@
 extern "C" {
 #endif
 
+/* Opaque structure containing the slirp state */
 typedef struct Slirp Slirp;
 
+/* Flags passed to SlirpAddPollCb and to be returned by SlirpGetREventsCb. */
 enum {
     SLIRP_POLL_IN = 1 << 0,
     SLIRP_POLL_OUT = 1 << 1,
@@ -37,7 +39,10 @@ typedef int (*SlirpAddPollCb)(int fd, int events, void *opaque);
 typedef int (*SlirpGetREventsCb)(int idx, void *opaque);
 
 /*
- * Callbacks from slirp
+ * Callbacks from slirp, to be set by the application.
+ *
+ * The opaque parameter is set to the opaque pointer given in the slirp_new /
+ * slirp_init call.
  */
 typedef struct SlirpCb {
     /*
@@ -115,6 +120,7 @@ typedef struct SlirpConfig {
     bool disable_dns;  /* slirp will not redirect/serve any DNS packet */
 } SlirpConfig;
 
+/* Create a new instance of a slirp stack */
 Slirp *slirp_new(const SlirpConfig *cfg, const SlirpCb *callbacks,
                  void *opaque);
 /* slirp_init is deprecated in favor of slirp_new */
@@ -128,16 +134,34 @@ Slirp *slirp_init(int restricted, bool in_enabled, struct in_addr vnetwork,
                   struct in6_addr vnameserver6, const char **vdnssearch,
                   const char *vdomainname, const SlirpCb *callbacks,
                   void *opaque);
+/* Shut down an instance of a slirp stack */
 void slirp_cleanup(Slirp *slirp);
 
+/* This is called by the application when it is about to sleep through poll().
+ * *timeout is set to the amount of virtual time that the application intends to
+ * wait (UINT32_MAX if infinite). slirp_pollfds_fill updates it according to
+ * e.g. TCP timers, so the application knows it should sleep a smaller amount of
+ * time. slirp_pollfds_fill calls add_poll for each file descriptor
+ * that should be monitored along the sleep. The opaque pointer is passed as
+ * such to add_poll, and add_poll returns an index. */
 void slirp_pollfds_fill(Slirp *slirp, uint32_t *timeout,
                         SlirpAddPollCb add_poll, void *opaque);
 
+/* This is called by the application after sleeping, to report which file
+ * descriptors are available. slirp_pollfds_poll calls get_revents on each file
+ * descriptor, giving it the index that add_poll returned during the
+ * slirp_pollfds_fill call, to know whether the descriptor is available for
+ * read/write/etc. (SLIRP_POLL_*)
+ * select_error should be passed 1 if poll() returned an error. */
 void slirp_pollfds_poll(Slirp *slirp, int select_error,
                         SlirpGetREventsCb get_revents, void *opaque);
 
+/* This is called by the application when the guest emits a packet on the
+ * guest network, to be interpreted by slirp. */
 void slirp_input(Slirp *slirp, const uint8_t *pkt, int pkt_len);
 
+/* These set up / remove port forwarding between a host port in the real world
+ * and the guest network. */
 int slirp_add_hostfwd(Slirp *slirp, int is_udp, struct in_addr host_addr,
                       int host_port, struct in_addr guest_addr, int guest_port);
 int slirp_remove_hostfwd(Slirp *slirp, int is_udp, struct in_addr host_addr,
@@ -148,30 +172,52 @@ int slirp_add_ipv6_hostfwd(Slirp *slirp, int is_udp,
 int slirp_remove_ipv6_hostfwd(Slirp *slirp, int is_udp,
                               struct in6_addr host_addr, int host_port);
 
+/* Set up port forwarding between a port in the guest network and a
+ * command running on the host */
 int slirp_add_exec(Slirp *slirp, const char *cmdline,
                    struct in_addr *guest_addr, int guest_port);
+/* Set up port forwarding between a port in the guest network and a
+ * Unix port on the host */
 int slirp_add_unix(Slirp *slirp, const char *unixsock,
                    struct in_addr *guest_addr, int guest_port);
+/* Set up port forwarding between a port in the guest network and a
+ * callback that will receive the data coming from the port */
 int slirp_add_guestfwd(Slirp *slirp, SlirpWriteCb write_cb, void *opaque,
                        struct in_addr *guest_addr, int guest_port);
-/* remove entries added by slirp_add_exec, slirp_add_unix or slirp_add_guestfwd */
-int slirp_remove_guestfwd(Slirp *slirp, struct in_addr guest_addr,
-                          int guest_port);
 
-char *slirp_connection_info(Slirp *slirp);
+/* TODO: rather identify a guestfwd through an opaque pointer instead of through
+ * the guest_addr */
 
-void slirp_socket_recv(Slirp *slirp, struct in_addr guest_addr, int guest_port,
-                       const uint8_t *buf, int size);
+/* This is called by the application for a guestfwd, to determine how much data
+ * can be received by the forwarded port through a call to slirp_socket_recv. */
 size_t slirp_socket_can_recv(Slirp *slirp, struct in_addr guest_addr,
                              int guest_port);
+/* This is called by the application for a guestfwd, to provide the data to be
+ * sent on the forwarded port */
+void slirp_socket_recv(Slirp *slirp, struct in_addr guest_addr, int guest_port,
+                       const uint8_t *buf, int size);
+
+/* Remove entries added by slirp_add_exec, slirp_add_unix or slirp_add_guestfwd */
+int slirp_remove_guestfwd(Slirp *slirp, struct in_addr guest_addr,
+                          int guest_port);
+
+/* Return a human-readable state of the slirp stack */
+char *slirp_connection_info(Slirp *slirp);
 
+/* Save the slirp state through the write_cb. The opaque pointer is passed as
+ * such to the write_cb. */
 void slirp_state_save(Slirp *s, SlirpWriteCb write_cb, void *opaque);
 
+/* Returns the version of the slirp state, to be saved along the state */
+int slirp_state_version(void);
+
+/* Load the slirp state through the read_cb. The opaque pointer is passed as
+ * such to the read_cb. The version should be given as it was obtained from
+ * slirp_state_version when slirp_state_save was called. */
 int slirp_state_load(Slirp *s, int version_id, SlirpReadCb read_cb,
                      void *opaque);
 
-int slirp_state_version(void);
-
+/* Return the version of the slirp implementation */
 const char *slirp_version_string(void);
 
 #ifdef __cplusplus