Re: [RFC] net: New API for applications to send and receive data


Jukka Rissanen
 

Hi Ivan,

On Wed, 2016-04-27 at 11:59 -0300, Iván Briano wrote:
On Wed, 27 Apr 2016 11:59:50 +0300, Jukka Rissanen wrote:

Signed-off-by: Jukka Rissanen <jukka.rissanen(a)linux.intel.com>
---
Hi,

current network application APIs in Zephyr are synchronous and a
bit of awkward to use in TCP. Because of these things, I propose
couple of new functions that are asynchronous and easier to use
by the application. These APIs require net_buf fragmentation
support
that I sent earlier.

Cheers,
Jukka


include/net/net_socket.h | 141
+++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 141 insertions(+)

diff --git a/include/net/net_socket.h b/include/net/net_socket.h
index 88073b1..2451de3 100644
--- a/include/net/net_socket.h
+++ b/include/net/net_socket.h
@@ -143,6 +143,147 @@ int net_reply(struct net_context *context,
struct net_buf *buf);
 struct simple_udp_connection *
  net_context_get_udp_connection(struct net_context
*context);
 
+/**
+ * @brief Callback that is called when there is something received
from
+ * the network.
+ *
+ * @details It is callback responsibility to release the net_buf
when the
+ * data is no longer needed. The callback is called in fiber
context.
+ *
+ * @param context Network context
+ * @param status 0 if ok, <0 if there is an error
+ * @param iov List of net_buf that contain data
+ * @param user_data User supplied data
+ */
+typedef void (*net_readv_cb_t)(struct net_context *context,
+        int status,
+        struct net_buf *iov,
+        void *user_data);
I receive a list of net_buf, based on what criteria? A list of
packets
or a single packet split in several buffers? If the latter, then you
The latter, the app would receive list of buffers. This complicates the
application a bit but some API could be used to retrieve the data so
that app would not need to know much about the individual fragments.

are
relegating to the application developer the job of putting it all
together, which in many cases will be required. Unless we expect that
every single higher level protocol will work with non-continuous
chunks
of memory.


+
+/**
+ * @brief Register a receiver to get data from network.
+ *
+ * @details Application uses this to get data from network
connection.
+ * Caller needs to specify a callback function that is called when
data
+ * is received by the socket. When the IP stack has received data,
it then
+ * calls user specified callback and it is callback responsibility
to
+ * release the net_buf when the data is no longer needed.
+ * This function will return immediately as it only sets a
callback to be
+ * called when new data is received. Application can remove the
registered
+ * callback by calling the function with same context and setting
cb to NULL.
+ *
+ * @param context Network context
+ * @param cb User supplied callback function
+ * @param user_data User supplied data
+ *
+ * @return 0 if cb registration was ok, <0 otherwise
+ */
+int net_readv(struct net_context *context,
+       net_readv_cb_t cb,
+       void *user_data);
+
+/**
+ * @brief Callback that is called when user can send
+ * data to the network.
+ *
+ * @details The first call to this function will set *status to 0
and
+ * bytes_sent to 0. Application can then prepare the data to be
sent
+ * in net_buf fragment list. The data to be sent is returned to
the
+ * caller of the function. If application does not wish to send
anything
+ * it can just return NULL. In this case the caller will
deallocate the
+ * iov list. Application should set the *status to <0 to indicate
more
+ * detailed reason for the error if NULL is returned.
+ *
+ * For successfully sent UDP data, the IP stack will call this
+ * callback again with status set to 0 and bytes_sent telling how
many bytes
+ * were sent. If the UDP data was not sent for some reason, then
*status
+ * will have value < 0 and bytes_sent is set to 0.
+ *
+ * For TCP, the callback is called when the network connection has
been
+ * established. In this case the *status is 0 and bytes_sent is 0.
+ * If there is a connection timeout, the status code will be
-ETIMEDOUT
+ * and bytes_sent is set to 0. Other error codes are also possible
in
+ * which case the *status < 0 and bytes_sent will tell how many
bytes were
+ * successfully sent. If the *status is set to 0 then bytes_sent
will tell
+ * how many bytes were sent to the peer.
+ *
+ * The iov fragment list does not contain data that has been
successfully
+ * sent. Also the iov->frags->data of the first data fragment will
point to
+ * first byte that has not yet been sent. If all the data was sent
+ * successfully, then the first item of iov list will have its
frags pointer
+ * set to NULL. Application can send more data if it wishes by
returning
+ * a new list of data fragments.
+ *
+ * The callback is called in fiber context.
+ *
+ * @param context Network context
+ * @param status 0 if ok, <0 if there is an error in stack side
+ * Application can return error code if needed via this pointer.
+ * @param bytes_sent How many bytes were sent.
+ * @param iov List of net_buf that contain data. If this is NULL,
then
+ * allocate the buf and fill it with data. If non-NULL, then the
protocol
+ * headers are already there and you can append the data.
+ * @param user_data User supplied data
+ *
+ * @return A valid net_buf that needs to be sent,
+ * NULL if user is not able to send anything.
+ */
+typedef struct net_buf *(*net_writev_cb_t)(struct net_context
*context,
+    int *status,
+    int bytes_sent,
+    struct net_buf *iov,
+    void *user_data);
So the way to use this is:
 - I have data to send, I call net_writev() and set my callback.
 - When data can be sent, callback is called, *status and bytes_sent
= 0
 - I allocate a net_buf, put my data in it, and return it.
   * What's the iov received here? Only for error cases or the
callback
     can be called multiple times to send the remaining data? In that
     case, the idea is that I receive a list of unsent data that I
need
     to return and that's it?
The latter. So the callback would be called again to send the remaining
data.

 - When all data was sent, the callback is called again with *status
0
   and bytes_sent sent to the total of bytes sent... since the last
time
   the function was called? Since the first?
Since the last time the function was called.


The thing with the fragment list, I'm understanding is meant to work
as
an iovec, so let's say I have a CoAP server that wants to notify
three
different clients of a change in a resource, it would make sense to
have
a single buffer with the payload and change the one with the header.
If
I understand this correctly, when data was sent successfully, I will
not
have access to the net_buf with the payload anymore, so I would need
to
recreate it, correct? In this case, there's no gain (and maybe even a
little loss) in doing a list of fragments, when I can just use a
single
buffer and copy both header and payload to it.
The net_buf's have a refcount so the same buffer can be used to send
same data to multiple clients.



+
+/**
+ * @brief Send data to network.
+ *
+ * @details Application uses this to send data to a network
connection.
+ * Caller needs to specify a callback function that is called when
data
+ * is ready to be sent. The function will return immediately, the
timeout
+ * is only used when calling the user callback. For UDP, the
timeout is
+ * ignored. For TCP the callback is called after the TCP
connection is
+ * established and user is able to send data, or if there is an
error
+ * creating a connection or if the connection timeouts.
+ *
This means that every time I call net_writev(), the TCP connection is
established? Or is that only the first time? If it's only the first,
why
not add a connect() function? And if it's established every time,
what's
the point of that?
The connection would be created only once. Adding the connect() is one
option but it is not really necessary.



+ * @param context Network context
+ * @param timeout How long to wait until user can send data. This
is only
+ * used in TCP.
+ * @param cb User supplied callback function
+ * @param user_data User supplied data
+ *
+ * @return 0 if cb registration was ok, <0 otherwise
+ */
+int net_writev(struct net_context *context,
+        int32_t timeout,
+        net_writev_cb_t cb,
+        void *user_data);
+
+/**
+ * @brief Reply data to sender.
+ *
+ * @details This is a helper that will help user to reply data to
the
+ * sender. Application can use this function to reply data it
received
+ * via net_readv().
+ *
+ * @param context Network context
+ * @param timeout How long to wait until user can send data. This
is only
+ * used in TCP.
+ * @param iov Data to be sent
+ * @param cb User supplied callback function
+ * @param user_data User supplied data
+ *
+ * @return 0 if cb registration was ok, <0 otherwise
+ */
+int net_replyv(struct net_context *context,
+        int32_t timeout,
+        struct net_buf *iov,
+        net_writev_cb_t cb,
+        void *user_data);
+
Is there really no way to get rid of this? Why can't we just have a
'send' function that works for all cases? If the problem is getting
the
address to send to, just add a helper function to put this in the
net_buf before sending.
If we are able to put some intelligence to plain send then why not. The
reason for the reply() was that we could have only one context for the
connection (to save some memory). For example in BSD sockets, the
listening socket is accepted by the app in which case when sending one
uses the accepted socket to send data and the addresses in the packet
are set then correctly.
But if the send can figure out itself that it should reverse the
addresses in the sending IP packet, then we can get rid of reply.



 #ifdef __cplusplus
 }
 #endif

Cheers,
Jukka

Join devel@lists.zephyrproject.org to automatically receive all group messages.