[riot-devel] conn f2f (+ remote) meeting

Martine Lenders mail at martine-lenders.eu
Thu Aug 18 08:25:50 CEST 2016


Hi,

2016-08-17 19:28 GMT+02:00 Oleg Hahm <oliver.hahm at inria.fr>:

> Hey folks,
>
> On Mon, Aug 15, 2016 at 04:11:48PM +0200, Martine Lenders wrote:
> > as promised: here is the agenda for the meeting next Wednesday:
> > http://yourpart.eu/p/netapp-api-riot
>
> thanks for the protocol, but is a bit hard to follow as a non-attendee.
> Could
> anyone come up with a short summary and, in case you concluded on a
> particular API, could present how it should look like?


already reworked it to a more readable form (just waited for some comments
by the attendees) [1]

TL;DR:
* reworked API will be called sock not conn to keep them distinguishable
when talking about it / porting it
* UDP/IP will have a somewhat reduced function set (convenience functions
are dropped)
* TCP will have a queue type for listening
* create functions for all will receive a flags parameter so options that
need to be done before binding can be passed

For reference I will adapt #5533 today

[1]
https://github.com/RIOT-OS/RIOT/wiki/Application-Layer-API-Meeting-on-August-17,-2016

Cheers,
Martine

Application Layer API Meeting 1
===============================

Agenda
------
1. Agenda Bashing
2. Goals and Priorities
3. Naming of the API
4. Detailed API-discussion:
    1. IP-based transport layer with datagram-based communication (IP raw /
UDP)
    2. IP-based transport layer with sequence-based communication (TCP)
5. Future extension
    1. Asynchronous event handling: External vs. native support
    2. Options
    3. Per packet configuration

Meeting Details
---------------
### Attendees
* Alexander Aring [eintopf]
* Cenk G├╝ndoghan
* Kaspar Schleiser
* Martine Lenders (Chair)
* Peter Kiezmann
* Simon Brummer

### Protocol
* Peter
* Simon

Goals / Priorities
------------------
1. No need for dynamic memory allocation
2. User friendliness
3. Simplicity
4. Efficiency (at both front- and backend)
5. Easy to implement for network stacks / portability

Naming of the API
-----------------
* Pro `conn:
    - Name was picked to differ from the old sockets because it isn't socket
* Con `conn`:
    - `conn` basically behaves like sockets (just look at the
function-calls)
    - New-comers might search for "something like sockets" anyway
    - Name change would show API change better and ultimately would be less
      confusing for users of `conn`
* Result: `sock` as name for the new API
* Side discussion: Documenting API changes
    - Wiki does not work, because it is forgotten after creation
    - Documentation via a dedicated README file is better

Detailed API-discussion
-----------------------
### IP-based transport layer with datagram-based communication (IP raw /
UDP)
- [Reference API][conn_udp]
- `sock_udp_create`/`sock_udp_close` good as is
- Getter (`sock_udp_get_local`/`sock_udp_get_remote`) stay because they
don't
  hurt and are needed for socket wrapper implementation
- Setter: easier and more convenient to create new `sock` instead
- `sock_udp_recv` and `sock_udp_recvfrom`:
    * Order of parameters of `sock_udp_recvfrom` confusing with that name
    * Static inline in API definition not nice
    * Result:
        + original `sock_udp_recv` should be removed
        + `sock_udp_recvfrom` renamed to `sock_udp_recv`
- `sock_udp_send` and `sock_udp_sendto`:
    * There are three sensible use-cases for `sock_udp_sendto`
        1. `sock != NULL`, `sock` is connected, and `remote == NULL`
        2. `sock != NULL`, `sock` is connected, and `remote != NULL`
        3. `sock == NULL` and `remote != NULL`
    * Currently only convenient function for 1., why not for 3.?
    * Also again: static inline in API definition
    * Result:
        + original `sock_udp_send` should be removed
        + `sock_udp_sendto` renamed to `sock_udp_send`

### IP-based transport layer with sequence-based communication (TCP)
- [Reference API][conn_tcp]
- [Simon wants a `sock_tcp_listen` function][conn_tcp_listen]
- Kaspar: two object types requiered
    - One representing a connection,
    - One representing a listening socket
    - split `sock_tcp_create` and `sock_tcp_close`:

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
{.c}
/* Connections:
 * (Only port required for local; and even that only in special cases) */
sock_tcp_connect(sock_tcp_t *sock, sock_tcp_ep_t *remote, uint16_t
local_port);
sock_tcp_disconnect(sock_tcp_t *sock);

/* Listening Socket / Queue */
sock_tcp_listen(sock_tcp_queue_t *queue, sock_tcp_ep_t *local,
                sock_tcp_t[] queue_array, unsigned queue_len);
sock_tcp_stop_listen(sock_tcp_queue_t *queue);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~


- later additions: something like `tcp_listen_dynamic`, as as passing the
whole
  queue as parameter is not suitable for servers with lots of RAM
(portability)
- `sock_tcp_accept` needs adaptation to new object types:
  `sock_tcp_accept(sock_tcp_queue_t *queue, sock_tcp_t **sock)`
- rename `sock_tcp_send`/`_recv` to `sock_tcp_write`/`_read`; better
suitable
  to semantics of streams

Future extension
----------------
### Asynchronous event handling: External vs. native support
5.1  Asynchronous event handling: External vs. native support
- Callbacks due to questionable context not suitable
- Additional functions for external async event handling are moved to later
  discussion.

### Options
- getter/setter functions added later
- options before bind might need additional parameters for create function
  - only option thinkable at the moment is something like `SO_REUSEADDR`
  - solvable by flag field in create function

### Per packet configuration
* datagram-based stuff needs per packet configuration option (checksum, etc
  because 6Lo-NHC)
* for now, no decision
* possible solutions:
    - could be solved with options setting before sending
    - message based send as proposed in [RFC 3542][rfc3542]

[conn_udp]:
https://github.com/miri64/RIOT/blob/a465926c722a98bc23898c45326eb2af7c6cb9d9/sys/include/net/conn/udp.h
[conn_tcp]:
https://github.com/miri64/RIOT/blob/a465926c722a98bc23898c45326eb2af7c6cb9d9/sys/include/net/conn/tcp.h
[conn_tcp_listen]:
https://github.com/RIOT-OS/RIOT/pull/5533#issuecomment-240105485
[rfc3542]: https://tools.ietf.org/html/rfc3542#section-5
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.riot-os.org/pipermail/devel/attachments/20160818/1a0650f2/attachment.html>


More information about the devel mailing list