March 2024 - gerrit-log - lists.osmocom.org

[S] Change in libosmo-netif[master]: docs: jibuf: Prevent internal #defines being documented

by laforge

laforge has submitted this change. ( https://gerrit.osmocom.org/c/libosmo-netif/+/36298?usp=email ) Change subject: docs: jibuf: Prevent internal #defines being documented ...................................................................... docs: jibuf: Prevent internal #defines being documented Change-Id: Ic3c6e32acb52595875de89f6054a62d9565747f9 --- M src/jibuf.c 1 file changed, 14 insertions(+), 4 deletions(-) Approvals: Jenkins Builder: Verified fixeria: Looks good to me, approved pespin: Looks good to me, but someone else must approve diff --git a/src/jibuf.c b/src/jibuf.c index 502f6e5..a351248 100644 --- a/src/jibuf.c +++ b/src/jibuf.c @@ -26,10 +26,6 @@ #include <arpa/inet.h> -/*! \addtogroup jibuf Osmocom Jitter Buffer - * @{ - */ - /*! \file jibuf.c * \brief Osmocom Jitter Buffer helpers */ @@ -290,6 +286,11 @@ } +/*! \addtogroup jibuf Osmocom Jitter Buffer + * @{ + */ + + //---------------------------------- /*! \brief Allocate a new jitter buffer instance -- To view, visit https://gerrit.osmocom.org/c/libosmo-netif/+/36298?usp=email To unsubscribe, or for help writing mail filters, visit https://gerrit.osmocom.org/settings Gerrit-Project: libosmo-netif Gerrit-Branch: master Gerrit-Change-Id: Ic3c6e32acb52595875de89f6054a62d9565747f9 Gerrit-Change-Number: 36298 Gerrit-PatchSet: 2 Gerrit-Owner: laforge <laforge(a)osmocom.org> Gerrit-Reviewer: Jenkins Builder Gerrit-Reviewer: fixeria <vyanitskiy(a)sysmocom.de> Gerrit-Reviewer: laforge <laforge(a)osmocom.org> Gerrit-Reviewer: pespin <pespin(a)sysmocom.de> Gerrit-MessageType: merged

1 year, 5 months

1
0
0 0

[M] Change in libosmo-netif[master]: docs: Split Stream Server and Stream Client into separate groups

by laforge

laforge has submitted this change. ( https://gerrit.osmocom.org/c/libosmo-netif/+/36297?usp=email ) Change subject: docs: Split Stream Server and Stream Client into separate groups ...................................................................... docs: Split Stream Server and Stream Client into separate groups This provides us with proper logical separation between client and server in the documentation. Change-Id: I9e037fedaecb78396f435577b1652284b4951ded --- M include/osmocom/netif/stream.h M include/osmocom/netif/stream_private.h M src/stream.c M src/stream_cli.c M src/stream_srv.c 5 files changed, 110 insertions(+), 104 deletions(-) Approvals: pespin: Looks good to me, but someone else must approve Jenkins Builder: Verified fixeria: Looks good to me, approved diff --git a/include/osmocom/netif/stream.h b/include/osmocom/netif/stream.h index 96633d6..1d97530 100644 --- a/include/osmocom/netif/stream.h +++ b/include/osmocom/netif/stream.h @@ -6,16 +6,7 @@ #include <osmocom/core/msgb.h> -/*! \defgroup stream Osmocom Stream Server/Client - * @{ - * - * This code is intended to abstract any use of stream-type sockets, - * such as TCP and SCTP. It offers both server and client side - * implementations, fully integrated with the libosmocore select loop - * abstraction. - * - * \file stream.h - */ +/*! \file stream.h */ /*! \brief Access SCTP flags from the msgb control buffer */ #define OSMO_STREAM_SCTP_MSG_FLAGS_NOTIFICATION 0x80 /* sctp_recvmsg() flags=MSG_NOTIFICATION, msgb_data() contains "union sctp_notification*" */ @@ -26,6 +17,48 @@ /*! \brief Access the SCTP Stream ID from the msgb control buffer */ #define msgb_sctp_stream(msg) (msg)->cb[4] +/*! \defgroup stream_srv Osmocom Stream Server + * @{ + * + * This code is intended to abstract any server-side use of stream-type sockets, such as TCP and SCTP. + * + * The Osmocom stream socket helper is an abstraction layer for connected SOCK_STREAM/SOCK_SEQPACKET sockets. + * It encapsulates common functionality like binding, accepting client connections, etc. + * + * osmo_stream_srv can operate in two different modes: + * 1. The legacy mode using osmo_fd (from libosmocore) + * 2. The modern (2023) mode using osmo_io (from libosmocore) + * + * For any new applications, you definitely should use the modern mode, as it provides you with a higher + * layer of abstraction and allows you to perform efficient I/O using the io_uring backend of osmo_io. + * + * The two main objects are osmo_stream_srv_link (main server accept()ing incoming connections) and + * osmo_stream_srv (a single given connection from a remote client). + * + * A typical stream_srv usage would look like this: + * + * * create new osmo_stream_srv_link using osmo_stream_srv_link_create() + * * call osmo_stream_srv_link_set_addr() to set local bind address/port + * * call osmo_stream_srv_link_set_accept_cb() to register the accept call-back + * * optionally call further osmo_stream_srv_link_set_*() functions + * * call osmo_stream_srv_link_open() to create socket and start listening + * + * Whenever a client connects to your listening socket, the connection will now be automatically accept()ed + * and the registered accept_cb call-back called. From within that accept_cb, you then + * * call osmo_stream_srv_create() to create a osmo_stream_srv for that specific connection + * * call osmo_stream_srv_set_read_cb() to register the read call-back for incoming data + * * call osmo_stream_srv_set_closed_cb() to register the closed call-back + * * call osmo_stream_srv_set_data() to associate opaque application-layer state + * + * Whenever data from a client arrives on a connection, your registered read_cb will be called together + * with a message buffer containing the received data. Ownership of the message buffer is transferred + * into the call-back, i.e. in your application. It's your responsibility to eventually msgb_free() + * it after usage. + * + * Whenever your application wants to transmit something to a given connection, it uses the + * osmo_stream_srv_send() function. + */ + /*! \brief Osmocom Stream Server Link: A server socket listening/accepting */ struct osmo_stream_srv_link; @@ -89,6 +122,40 @@ void osmo_stream_srv_clear_tx_queue(struct osmo_stream_srv *conn); +/*! @} */ + +/*! \defgroup stream_cli Osmocom Stream Client + * @{ + * + * This code is intended to abstract any client use of stream-type sockets, such as TCP and SCTP + * + * An osmo_stream_cli represents a client implementation of a SOCK_STREAM or SOCK_SEQPACKET socket. It + * contains all the common logic like non-blocking outbound connect to a remote server, re-connecting after + * disconnect or connect failure, etc. + * + * osmo_stream_cli can operate in two different modes: + * 1. The legacy mode using osmo_fd (from libosmocore) + * 2. The modern (2023) mode using osmo_io_fd (from libosmocore) + * + * For any new applications, you definitely should use the modern mode, as it provides you with a higher + * layer of abstraction and allows you to perform efficient I/O using the io_uring backend of osmo_io. + * + * A typical usage of osmo_stream_cli would look as follows: + * + * * call osmo_stream_cli_create() to create a new osmo_stream_cli + * * call osmo_stream_cli_set_addr() / osmo_stream_cli_set_port() to specify the remote address/port to connect to + * * optionally call further functions of the osmo_stream_cli_set_*() family + * * call osmo_stream_cli_set_connect_cb() to register the call-back called on completion of outbound connect() + * * call osmo_stream_cli_set_read_cb2() to register the call-back called when incoming data has been read + * * call osmo_stream_cli_open() to open the connection (start outbound connect process) + * + * Once the connection is established, your connect_cb is called to notify you. + * + * You may send data to the connection using osmo_tream_cli_send(). + * + * Any received inbound data on the connection is reported vie the read_cb. + */ + /*! \brief Osmocom Stream Client: Single client connection */ struct osmo_stream_cli; diff --git a/include/osmocom/netif/stream_private.h b/include/osmocom/netif/stream_private.h index 106b017..dc7506d 100644 --- a/include/osmocom/netif/stream_private.h +++ b/include/osmocom/netif/stream_private.h @@ -21,9 +21,7 @@ #define OSMO_STREAM_MAX_ADDRS 1 #endif -/*! \addtogroup stream - * @{ - */ +/*! \cond private */ enum osmo_stream_mode { OSMO_STREAM_MODE_UNKNOWN, @@ -41,4 +39,4 @@ int stream_iofd_sctp_send_msgb(struct osmo_io_fd *iofd, struct msgb *msg, int sendmsg_flags); int stream_iofd_sctp_recvmsg_trailer(struct osmo_io_fd *iofd, struct msgb *msg, int ret, const struct msghdr *msgh); -/*! @} */ +/*! \endcond */ diff --git a/src/stream.c b/src/stream.c index 60a7623..f8cbed6 100644 --- a/src/stream.c +++ b/src/stream.c @@ -51,14 +51,7 @@ #include <osmocom/netif/sctp.h> - -/*! \addtogroup stream - * @{ - */ - -/*! \file stream.c - * \brief Osmocom stream socket helpers - */ +/*! \cond private */ #ifdef HAVE_LIBSCTP @@ -344,5 +337,4 @@ } #endif - -/*! @} */ +/*! \endccond */ diff --git a/src/stream_cli.c b/src/stream_cli.c index ed81932..ca60e25 100644 --- a/src/stream_cli.c +++ b/src/stream_cli.c @@ -51,41 +51,7 @@ #include <osmocom/netif/sctp.h> - -/*! \addtogroup stream - * @{ - */ - -/*! \file stream_cli.c - * Osmocom stream socket helpers (client side) - * - * An osmo_stream_cli represents a client implementation of a SOCK_STREAM or SOCK_SEQPACKET socket. It - * contains all the common logic like non-blocking outbound connect to a remote server, re-connecting after - * disconnect or connect failure, etc. - * - * osmo_stream_cli can operate in two different modes: - * 1. The legacy mode using osmo_fd (from libosmocore) - * 2. The modern (2023) mode using osmo_io_fd (from libosmocore) - * - * For any new applications, you definitely should use the modern mode, as it provides you with a higher - * layer of abstraction and allows you to perform efficient I/O using the io_uring backend of osmo_io. - * - * A typical usage of osmo_stream_cli would look as follows: - * - * * call osmo_stream_cli_create() to create a new osmo_stream_cli - * * call osmo_stream_cli_set_addr() / osmo_stream_cli_set_port() to specify the remote address/port to connect to - * * optionally call further functions of the osmo_stream_cli_set_*() family - * * call osmo_stream_cli_set_connect_cb() to register the call-back called on completion of outbound connect() - * * call osmo_stream_cli_set_read_cb2() to register the call-back called when incoming data has been read - * * call osmo_stream_cli_open() to open the connection (start outbound connect process) - * - * Once the connection is established, your connect_cb is called to notify you. - * - * You may send data to the connection using osmo_tream_cli_send(). - * - * Any received inbound data on the connection is reported vie the read_cb. - * - */ +/*! \file stream_cli.c */ #define LOGSCLI(cli, level, fmt, args...) \ LOGP(DLINP, level, "CLICONN(%s,%s){%s} " fmt, \ @@ -151,6 +117,10 @@ void osmo_stream_cli_close(struct osmo_stream_cli *cli); +/*! \addtogroup stream_cli + * @{ + */ + /*! Re-connect an Osmocom Stream Client. * If re-connection is enabled for this client * (which is the case unless negative timeout was explicitly set via osmo_stream_cli_set_reconnect_timeout() call), diff --git a/src/stream_srv.c b/src/stream_srv.c index 8837105..3220b9e 100644 --- a/src/stream_srv.c +++ b/src/stream_srv.c @@ -52,51 +52,7 @@ #include <osmocom/netif/sctp.h> - -/*! \addtogroup stream - * @{ - */ - -/*! \file stream_srv.c - * Osmocom stream socket helpers (server side) - * - * The Osmocom stream socket helper is an abstraction layer for connected SOCK_STREAM/SOCK_SEQPACKET sockets. - * It encapsulates common functionality like binding, accepting client connections, etc. - * - * osmo_stream_srv can operate in two different modes: - * 1. The legacy mode using osmo_fd (from libosmocore) - * 2. The modern (2023) mode using osmo_io (from libosmocore) - * - * For any new applications, you definitely should use the modern mode, as it provides you with a higher - * layer of abstraction and allows you to perform efficient I/O using the io_uring backend of osmo_io. - * - * The two main objects are osmo_stream_srv_link (main server accept()ing incoming connections) and - * osmo_stream_srv (a single given connection from a remote client). - * - * A typical stream_srv usage would look like this: - * - * * create new osmo_stream_srv_link using osmo_stream_srv_link_create() - * * call osmo_stream_srv_link_set_addr() to set local bind address/port - * * call osmo_stream_srv_link_set_accept_cb() to register the accept call-back - * * optionally call further osmo_stream_srv_link_set_*() functions - * * call osmo_stream_srv_link_open() to create socket and start listening - * - * Whenever a client connects to your listening socket, the connection will now be automatically accept()ed - * and the registered accept_cb call-back called. From within that accept_cb, you then - * * call osmo_stream_srv_create() to create a osmo_stream_srv for that specific connection - * * call osmo_stream_srv_set_read_cb() to register the read call-back for incoming data - * * call osmo_stream_srv_set_closed_cb() to register the closed call-back - * * call osmo_stream_srv_set_data() to associate opaque application-layer state - * - * Whenever data from a client arrives on a connection, your registered read_cb will be called together - * with a message buffer containing the received data. Ownership of the message buffer is transferred - * into the call-back, i.e. in your application. It's your responsibility to eventually msgb_free() - * it after usage. - * - * Whenever your application wants to transmit something to a given connection, it uses the - * osmo_stream_srv_send() function. - * - */ +/*! \file stream_srv.c */ #define LOGSLNK(link, level, fmt, args...) \ LOGP(DLINP, level, "SRV(%s,%s) " fmt, \ @@ -207,6 +163,10 @@ return ret; } +/*! \addtogroup stream_srv + * @{ + */ + /*! Create an Osmocom Stream Server Link. * A Stream Server Link is the listen()+accept() "parent" to individual connections from remote clients. * \param[in] ctx talloc allocation context @@ -623,6 +583,8 @@ return 0; } +/*! @} */ + #define OSMO_STREAM_SRV_F_FLUSH_DESTROY (1 << 0) struct osmo_stream_srv { @@ -642,6 +604,10 @@ int flags; }; +/*! \addtogroup stream_srv + * @{ + */ + static void stream_srv_iofd_read_cb(struct osmo_io_fd *iofd, int res, struct msgb *msg) { struct osmo_stream_srv *conn = osmo_iofd_get_data(iofd); @@ -827,6 +793,7 @@ return rc; } + /*! Create a legacy osmo_fd mode Stream Server inside the specified link. * * This is the function an application traditionally calls from within the -- To view, visit https://gerrit.osmocom.org/c/libosmo-netif/+/36297?usp=email To unsubscribe, or for help writing mail filters, visit https://gerrit.osmocom.org/settings Gerrit-Project: libosmo-netif Gerrit-Branch: master Gerrit-Change-Id: I9e037fedaecb78396f435577b1652284b4951ded Gerrit-Change-Number: 36297 Gerrit-PatchSet: 2 Gerrit-Owner: laforge <laforge(a)osmocom.org> Gerrit-Reviewer: Jenkins Builder Gerrit-Reviewer: fixeria <vyanitskiy(a)sysmocom.de> Gerrit-Reviewer: laforge <laforge(a)osmocom.org> Gerrit-Reviewer: pespin <pespin(a)sysmocom.de> Gerrit-MessageType: merged

1 year, 5 months

1
0
0 0

[S] Change in libosmo-netif[master]: docs: Don't export internal structs declared in src files

by laforge

laforge has submitted this change. ( https://gerrit.osmocom.org/c/libosmo-netif/+/36296?usp=email ) Change subject: docs: Don't export internal structs declared in src files ...................................................................... docs: Don't export internal structs declared in src files Change-Id: I5db8ce90c1e1e393195c9a146ba617ab980a9390 --- M Doxyfile.in 1 file changed, 10 insertions(+), 1 deletion(-) Approvals: fixeria: Looks good to me, approved pespin: Looks good to me, but someone else must approve Jenkins Builder: Verified diff --git a/Doxyfile.in b/Doxyfile.in index 001a085..bdd70e3 100644 --- a/Doxyfile.in +++ b/Doxyfile.in @@ -334,7 +334,7 @@ # defined locally in source files will be included in the documentation. # If set to NO only classes defined in header files are included. -EXTRACT_LOCAL_CLASSES = YES +EXTRACT_LOCAL_CLASSES = NO # This flag is only useful for Objective-C code. When set to YES local # methods, which are defined in the implementation section but not in -- To view, visit https://gerrit.osmocom.org/c/libosmo-netif/+/36296?usp=email To unsubscribe, or for help writing mail filters, visit https://gerrit.osmocom.org/settings Gerrit-Project: libosmo-netif Gerrit-Branch: master Gerrit-Change-Id: I5db8ce90c1e1e393195c9a146ba617ab980a9390 Gerrit-Change-Number: 36296 Gerrit-PatchSet: 2 Gerrit-Owner: laforge <laforge(a)osmocom.org> Gerrit-Reviewer: Jenkins Builder Gerrit-Reviewer: fixeria <vyanitskiy(a)sysmocom.de> Gerrit-Reviewer: laforge <laforge(a)osmocom.org> Gerrit-Reviewer: pespin <pespin(a)sysmocom.de> Gerrit-MessageType: merged

1 year, 5 months

1
0
0 0

[L] Change in libosmo-netif[master]: docs: More verbose stream_{cli,srv} API documentation/manual

by laforge

laforge has submitted this change. ( https://gerrit.osmocom.org/c/libosmo-netif/+/36294?usp=email ) Change subject: docs: More verbose stream_{cli,srv} API documentation/manual ...................................................................... docs: More verbose stream_{cli,srv} API documentation/manual Change-Id: Iae3c3af6533be408e5755ceeda0067606a3b0ca1 --- M src/stream_cli.c M src/stream_srv.c 2 files changed, 240 insertions(+), 88 deletions(-) Approvals: laforge: Looks good to me, approved pespin: Looks good to me, but someone else must approve Jenkins Builder: Verified diff --git a/src/stream_cli.c b/src/stream_cli.c index f19bf98..ed81932 100644 --- a/src/stream_cli.c +++ b/src/stream_cli.c @@ -57,7 +57,34 @@ */ /*! \file stream_cli.c - * \brief Osmocom stream socket helpers (client side) + * Osmocom stream socket helpers (client side) + * + * An osmo_stream_cli represents a client implementation of a SOCK_STREAM or SOCK_SEQPACKET socket. It + * contains all the common logic like non-blocking outbound connect to a remote server, re-connecting after + * disconnect or connect failure, etc. + * + * osmo_stream_cli can operate in two different modes: + * 1. The legacy mode using osmo_fd (from libosmocore) + * 2. The modern (2023) mode using osmo_io_fd (from libosmocore) + * + * For any new applications, you definitely should use the modern mode, as it provides you with a higher + * layer of abstraction and allows you to perform efficient I/O using the io_uring backend of osmo_io. + * + * A typical usage of osmo_stream_cli would look as follows: + * + * * call osmo_stream_cli_create() to create a new osmo_stream_cli + * * call osmo_stream_cli_set_addr() / osmo_stream_cli_set_port() to specify the remote address/port to connect to + * * optionally call further functions of the osmo_stream_cli_set_*() family + * * call osmo_stream_cli_set_connect_cb() to register the call-back called on completion of outbound connect() + * * call osmo_stream_cli_set_read_cb2() to register the call-back called when incoming data has been read + * * call osmo_stream_cli_open() to open the connection (start outbound connect process) + * + * Once the connection is established, your connect_cb is called to notify you. + * + * You may send data to the connection using osmo_tream_cli_send(). + * + * Any received inbound data on the connection is reported vie the read_cb. + * */ #define LOGSCLI(cli, level, fmt, args...) \ @@ -124,7 +151,7 @@ void osmo_stream_cli_close(struct osmo_stream_cli *cli); -/*! \brief Re-connect an Osmocom Stream Client +/*! Re-connect an Osmocom Stream Client. * If re-connection is enabled for this client * (which is the case unless negative timeout was explicitly set via osmo_stream_cli_set_reconnect_timeout() call), * we close any existing connection (if any) and schedule a re-connect timer */ @@ -143,7 +170,7 @@ osmo_timer_schedule(&cli->timer, cli->reconnect_timeout, 0); } -/*! \brief Check if Osmocom Stream Client is in connected state +/*! Check if Osmocom Stream Client is in connected state. * \param[in] cli Osmocom Stream Client * \return true if connected, false otherwise */ @@ -170,7 +197,7 @@ cli->ofd.fd = -1; } -/*! \brief Close an Osmocom Stream Client +/*! Close an Osmocom Stream Client. * \param[in] cli Osmocom Stream Client to be closed * We unregister the socket fd from the osmocom select() loop * abstraction and close the socket */ @@ -207,7 +234,7 @@ } } -/*! \brief Get file descriptor of the stream client socket +/*! Retrieve file descriptor of the stream client socket. * \param[in] cli Stream Client of which we want to obtain the file descriptor * \returns File descriptor or negative in case of error */ int @@ -400,7 +427,7 @@ static void cli_timer_cb(void *data); -/*! \brief Create an Osmocom stream client +/*! Create an Osmocom stream client. * \param[in] ctx talloc context from which to allocate memory * This function allocates a new \ref osmo_stream_cli and initializes * it with default values (5s reconnect timer, TCP protocol) @@ -513,7 +540,7 @@ #endif -/*! \brief Set a name on the cli object (used during logging) +/*! Set a name on the cli object (used during logging). * \param[in] cli stream_cli whose name is to be set * \param[in] name the name to be set on cli */ @@ -524,7 +551,7 @@ osmo_iofd_set_name(cli->iofd, name); } -/*! \brief Retrieve name previously set on the cli object (see osmo_stream_cli_set_name()) +/*! Retrieve name previously set on the cli object (see osmo_stream_cli_set_name()). * \param[in] cli stream_cli whose name is to be retrieved * \returns The name to be set on cli; NULL if never set */ @@ -533,7 +560,8 @@ return cli->name; } -/*! \brief Set the remote address to which we connect +/*! Set the remote address to which we connect. + * Any changes to this setting will only become active upon next (re)connect. * \param[in] cli Stream Client to modify * \param[in] addr Remote IP address */ @@ -543,8 +571,9 @@ osmo_stream_cli_set_addrs(cli, &addr, 1); } -/*! \brief Set the remote address set to which we connect. +/*! Set the remote address set to which we connect. * Useful for protocols allowing connecting to more than one address (such as SCTP) + * Any changes to this setting will only become active upon next (re)connect. * \param[in] cli Stream Client to modify * \param[in] addr Remote IP address set * \return negative on error, 0 on success @@ -568,7 +597,8 @@ return 0; } -/*! \brief Set the remote port number to which we connect +/*! Set the remote port number to which we connect. + * Any changes to this setting will only become active upon next (re)connect. * \param[in] cli Stream Client to modify * \param[in] port Remote port number */ @@ -579,7 +609,8 @@ cli->flags |= OSMO_STREAM_CLI_F_RECONF; } -/*! \brief Set the local port number for the socket (to be bound to) +/*! Set the local port number for the socket (to be bound to). + * Any changes to this setting will only become active upon next (re)connect. * \param[in] cli Stream Client to modify * \param[in] port Local port number */ @@ -590,7 +621,8 @@ cli->flags |= OSMO_STREAM_CLI_F_RECONF; } -/*! \brief Set the local address for the socket (to be bound to) +/*! Set the local address for the socket (to be bound to). + * Any changes to this setting will only become active upon next (re)connect. * \param[in] cli Stream Client to modify * \param[in] port Local host name */ @@ -600,8 +632,9 @@ osmo_stream_cli_set_local_addrs(cli, &addr, 1); } -/*! \brief Set the local address set to which we connect. +/*! Set the local address set to which we bind. * Useful for protocols allowing bind to more than one address (such as SCTP) + * Any changes to this setting will only become active upon next (re)connect. * \param[in] cli Stream Client to modify * \param[in] addr Local IP address set * \return negative on error, 0 on success @@ -625,7 +658,8 @@ return 0; } -/*! \brief Set the protocol for the stream client socket +/*! Set the protocol for the stream client socket. + * Any changes to this setting will only become active upon next (re)connect. * \param[in] cli Stream Client to modify * \param[in] proto Protocol (like IPPROTO_TCP (default), IPPROTO_SCTP, ...) */ @@ -648,7 +682,7 @@ osmo_iofd_set_ioops(cli->iofd, &client_ops); } -/*! \brief Set the segmentation callback for the client +/*! Set the segmentation callback for the client. * \param[in,out] cli Stream Client to modify * \param[in] segmentation_cb Target segmentation callback */ @@ -660,10 +694,11 @@ configure_cli_segmentation_cb(cli, segmentation_cb); } -/*! \brief Set the socket type for the stream server link +/*! Set the socket type for the stream server link. + * Any changes to this setting will only become active upon next (re)connect. * \param[in] cli Stream Client to modify * \param[in] type Socket Type (like SOCK_STREAM (default), SOCK_SEQPACKET, ...) - * \returns zero on success, negative on error. + * \returns zero on success, negative -errno on error. */ int osmo_stream_cli_set_type(struct osmo_stream_cli *cli, int type) { @@ -679,10 +714,11 @@ return 0; } -/*! \brief Set the socket type for the stream server link +/*! Set the socket type for the stream server link. + * Any changes to this setting will only become active upon next (re)connect. * \param[in] cli Stream Client to modify * \param[in] type Socket Domain (like AF_UNSPEC (default for IP), AF_UNIX, AF_INET, ...) - * \returns zero on success, negative on error. + * \returns zero on success, negative -errno on error. */ int osmo_stream_cli_set_domain(struct osmo_stream_cli *cli, int domain) { @@ -700,7 +736,7 @@ return 0; } -/*! \brief Set the reconnect time of the stream client socket +/*! Set the reconnect time of the stream client socket. * \param[in] cli Stream Client to modify * \param[in] timeout Re-connect timeout in seconds or negative value to disable auto-reconnection */ void @@ -709,7 +745,7 @@ cli->reconnect_timeout = timeout; } -/*! \brief Set application private data of the stream client socket +/*! Set application private data of the stream client socket. * \param[in] cli Stream Client to modify * \param[in] data User-specific data (available in call-back functions) */ void @@ -718,7 +754,7 @@ cli->data = data; } -/*! \brief Get application private data of the stream client socket +/*! Retrieve application private data of the stream client socket. * \param[in] cli Stream Client to modify * \returns Application private data, as set by \ref osmo_stream_cli_set_data() */ void *osmo_stream_cli_get_data(struct osmo_stream_cli *cli) @@ -726,7 +762,9 @@ return cli->data; } -/*! \brief Get the stream client socket description. +/*! Retrieve the stream client socket description. + * Calling this function will build a string that describes the socket in terms of its local/remote + * address/port. The returned name is stored in a static buffer; it is hence not re-entrant or thread-safe. * \param[in] cli Stream Client to examine * \returns Socket description or NULL in case of error */ char *osmo_stream_cli_get_sockname(const struct osmo_stream_cli *cli) @@ -739,7 +777,8 @@ return buf; } -/*! \brief Get Osmocom File Descriptor of the stream client socket +/*! Retrieve Osmocom File Descriptor of the stream client socket. + * This function only works in case you operate osmo_stream_cli in osmo_fd mode! * \param[in] cli Stream Client to modify * \returns Pointer to \ref osmo_fd */ struct osmo_fd * @@ -749,7 +788,9 @@ return &cli->ofd; } -/*! \brief Set the call-back function called on connect of the stream client socket +/*! Set the call-back function called on connect of the stream client socket. + * The call-back function registered via this function will be called upon completion of the non-blocking + * outbound connect operation. * \param[in] cli Stream Client to modify * \param[in] connect_cb Call-back function to be called upon connect */ void @@ -759,7 +800,7 @@ cli->connect_cb = connect_cb; } -/*! \brief Set the call-back function called on disconnect of the stream client socket +/*! Set the call-back function called on disconnect of the stream client socket. * \param[in] cli Stream Client to modify * \param[in] disconnect_cb Call-back function to be called upon disconnect */ void osmo_stream_cli_set_disconnect_cb(struct osmo_stream_cli *cli, @@ -768,8 +809,8 @@ cli->disconnect_cb = disconnect_cb; } -/*! \brief Set the call-back function called to read from the stream client socket - * This function will configure osmo_stream_cli to use osmo_ofd internally. +/*! Set the call-back function called to read from the stream client socket. + * This function will implicitly configure osmo_stream_cli to use legacy osmo_ofd mode. * \param[in] cli Stream Client to modify * \param[in] read_cb Call-back function to be called when we want to read */ void @@ -781,8 +822,8 @@ cli->read_cb = read_cb; } -/*! \brief Set the call-back function called to read from the stream client socket - * This function will configure osmo_stream_cli to use osmo_iofd internally. +/*! Set the call-back function called to read from the stream client socket. + * This function will implicitly configure osmo_stream_cli to use osmo_iofd mode. * \param[in] cli Stream Client to modify * \param[in] read_cb Call-back function to be called when data was read from the socket */ void @@ -794,7 +835,7 @@ cli->iofd_read_cb = read_cb; } -/*! \brief Destroy a Osmocom stream client (includes close) +/*! Destroy a Osmocom stream client (includes close). * \param[in] cli Stream Client to destroy */ void osmo_stream_cli_destroy(struct osmo_stream_cli *cli) { @@ -804,7 +845,7 @@ talloc_free(cli); } -/*! \brief DEPRECATED: use osmo_stream_cli_set_reconnect_timeout() or osmo_stream_cli_reconnect() instead! +/*! DEPRECATED: use osmo_stream_cli_set_reconnect_timeout() or osmo_stream_cli_reconnect() instead! * Open connection of an Osmocom stream client * \param[in] cli Stream Client to connect * \param[in] reconect 1 if we should not automatically reconnect @@ -862,7 +903,7 @@ return -EIO; } -/*! \brief Set the NODELAY socket option to avoid Nagle-like behavior +/*! Set the NODELAY socket option to avoid Nagle-like behavior. * Setting this to nodelay=true will automatically set the NODELAY * socket option on any socket established via \ref osmo_stream_cli_open * or any re-connect. You have to set this _before_ opening the @@ -878,8 +919,9 @@ cli->flags &= ~OSMO_STREAM_CLI_F_NODELAY; } -/*! \brief Open connection of an Osmocom stream client - * By default the client will automatically reconnect after default timeout. +/*! Open connection of an Osmocom stream client. + * This will initiate an non-blocking outbound connect to the configured destination (server) address. + * By default the client will automatically attempt to reconnect after default timeout. * To disable this, use osmo_stream_cli_set_reconnect_timeout() before calling this function. * \param[in] cli Stream Client to connect * \return negative on error, 0 on success */ @@ -998,7 +1040,8 @@ osmo_stream_cli_open(cli); } -/*! \brief Enqueue data to be sent via an Osmocom stream client +/*! Enqueue data to be sent via an Osmocom stream client.. + * This is the function you use for writing/sending/transmitting data via the osmo_stream_cli. * \param[in] cli Stream Client through which we want to send * \param[in] msg Message buffer to enqueue in transmit queue */ void osmo_stream_cli_send(struct osmo_stream_cli *cli, struct msgb *msg) @@ -1034,11 +1077,15 @@ } } -/*! \brief Receive data via an Osmocom stream client +/*! Receive data via an Osmocom stream client in osmo_fd mode. * \param[in] cli Stream Client through which we want to send * \param msg pre-allocate message buffer to which received data is appended * \returns number of bytes read; <=0 in case of error * + * Application programs using the legacy osmo_fd mode of osmo_stream_cli will use + * this function to read/receive from a stream client socket after they have been notified that + * it is readable (via select/poll). + * * If conn is an SCTP connection, additional specific considerations shall be taken: * - msg->cb is always filled with SCTP ppid, and SCTP stream values, see msgb_sctp_*() APIs. * - If an SCTP notification was received when reading from the SCTP socket, @@ -1100,6 +1147,8 @@ return ret; } +/*! Clear the transmit queue of the stream client. + * Calling this function wil clear (delete) any pending, not-yet transmitted data from the transmit queue. */ void osmo_stream_cli_clear_tx_queue(struct osmo_stream_cli *cli) { switch (cli->mode) { @@ -1118,6 +1167,12 @@ } } +/*! Set given parameter of stream client to given value. + * \param[in] cli stream client on which to set parameter. + * \param[in] par identifier of the parameter to be set. + * \param[in] val value of the parameter to be set. + * \param[in] val_len length of the parameter value. + * \returns 0 in success; negative -errno on error. */ int osmo_stream_cli_set_param(struct osmo_stream_cli *cli, enum osmo_stream_cli_param par, void *val, size_t val_len) { OSMO_ASSERT(cli); diff --git a/src/stream_srv.c b/src/stream_srv.c index b53caab..8837105 100644 --- a/src/stream_srv.c +++ b/src/stream_srv.c @@ -58,7 +58,44 @@ */ /*! \file stream_srv.c - * \brief Osmocom stream socket helpers (server side) + * Osmocom stream socket helpers (server side) + * + * The Osmocom stream socket helper is an abstraction layer for connected SOCK_STREAM/SOCK_SEQPACKET sockets. + * It encapsulates common functionality like binding, accepting client connections, etc. + * + * osmo_stream_srv can operate in two different modes: + * 1. The legacy mode using osmo_fd (from libosmocore) + * 2. The modern (2023) mode using osmo_io (from libosmocore) + * + * For any new applications, you definitely should use the modern mode, as it provides you with a higher + * layer of abstraction and allows you to perform efficient I/O using the io_uring backend of osmo_io. + * + * The two main objects are osmo_stream_srv_link (main server accept()ing incoming connections) and + * osmo_stream_srv (a single given connection from a remote client). + * + * A typical stream_srv usage would look like this: + * + * * create new osmo_stream_srv_link using osmo_stream_srv_link_create() + * * call osmo_stream_srv_link_set_addr() to set local bind address/port + * * call osmo_stream_srv_link_set_accept_cb() to register the accept call-back + * * optionally call further osmo_stream_srv_link_set_*() functions + * * call osmo_stream_srv_link_open() to create socket and start listening + * + * Whenever a client connects to your listening socket, the connection will now be automatically accept()ed + * and the registered accept_cb call-back called. From within that accept_cb, you then + * * call osmo_stream_srv_create() to create a osmo_stream_srv for that specific connection + * * call osmo_stream_srv_set_read_cb() to register the read call-back for incoming data + * * call osmo_stream_srv_set_closed_cb() to register the closed call-back + * * call osmo_stream_srv_set_data() to associate opaque application-layer state + * + * Whenever data from a client arrives on a connection, your registered read_cb will be called together + * with a message buffer containing the received data. Ownership of the message buffer is transferred + * into the call-back, i.e. in your application. It's your responsibility to eventually msgb_free() + * it after usage. + * + * Whenever your application wants to transmit something to a given connection, it uses the + * osmo_stream_srv_send() function. + * */ #define LOGSLNK(link, level, fmt, args...) \ @@ -170,11 +207,10 @@ return ret; } -/*! \brief Create an Osmocom Stream Server Link - * A Stream Server Link is the listen()+accept() "parent" to individual - * Stream Servers +/*! Create an Osmocom Stream Server Link. + * A Stream Server Link is the listen()+accept() "parent" to individual connections from remote clients. * \param[in] ctx talloc allocation context - * \returns Stream Server Link with default values (TCP) + * \returns Stream Server Link with default values (AF_UNSPEC, SOCK_STREAM, IPPROTO_TCP) */ struct osmo_stream_srv_link *osmo_stream_srv_link_create(void *ctx) { @@ -194,8 +230,9 @@ return link; } -/*! \brief Set a name on the srv_link object (used during logging) - * \param[in] link server link whose name is to be set +/*! Set a name on the srv_link object (used during logging). + * \param[in] link server link whose name is to be set. The name is copied into the osmo_stream_srv_link, so + * the caller memory is not required to be valid beyond the call of this function. * \param[in] name the name to be set on link */ void osmo_stream_srv_link_set_name(struct osmo_stream_srv_link *link, const char *name) @@ -203,7 +240,7 @@ osmo_talloc_replace_string(link, &link->name, name); } -/*! \brief Retrieve name previously set on the srv_link object (see osmo_stream_srv_link_set_name()) +/*! Retrieve name previously set on the srv_link object (see osmo_stream_srv_link_set_name()). * \param[in] link server link whose name is to be retrieved * \returns The name to be set on link; NULL if never set */ @@ -212,7 +249,7 @@ return link->name; } -/*! \brief Set the NODELAY socket option to avoid Nagle-like behavior +/*! Set the NODELAY socket option to avoid Nagle-like behavior. * Setting this to nodelay=true will automatically set the NODELAY * socket option on any socket established via this server link, before * calling the accept_cb() @@ -227,7 +264,8 @@ link->flags &= ~OSMO_STREAM_SRV_F_NODELAY; } -/*! \brief Set the local address to which we bind +/*! Set the local address to which we bind. + * Any changes to this setting will only become active upon next (re)connect. * \param[in] link Stream Server Link to modify * \param[in] addr Local IP address */ @@ -237,8 +275,9 @@ osmo_stream_srv_link_set_addrs(link, &addr, 1); } -/*! \brief Set the local address set to which we bind. +/*! Set the local address set to which we bind. * Useful for protocols allowing bind on more than one address (such as SCTP) + * Any changes to this setting will only become active upon next (re)connect. * \param[in] link Stream Server Link to modify * \param[in] addr Local IP address * \return negative on error, 0 on success @@ -262,7 +301,8 @@ return 0; } -/*! \brief Set the local port number to which we bind +/*! Set the local port number to which we bind. + * Any changes to this setting will only become active upon next (re)connect. * \param[in] link Stream Server Link to modify * \param[in] port Local port number */ @@ -273,7 +313,8 @@ link->flags |= OSMO_STREAM_SRV_F_RECONF; } -/*! \brief Set the protocol for the stream server link +/*! Set the protocol for the stream server link. + * Any changes to this setting will only become active upon next (re)connect. * \param[in] link Stream Server Link to modify * \param[in] proto Protocol (like IPPROTO_TCP (default), IPPROTO_SCTP, ...) */ @@ -286,7 +327,8 @@ } -/*! \brief Set the socket type for the stream server link +/*! Set the socket type for the stream server link. + * Any changes to this setting will only become active upon next (re)connect. * \param[in] link Stream Server Link to modify * \param[in] type Socket Type (like SOCK_STREAM (default), SOCK_SEQPACKET, ...) * \returns zero on success, negative on error. @@ -305,7 +347,8 @@ return 0; } -/*! \brief Set the socket type for the stream server link +/*! Set the socket type for the stream server link. + * Any changes to this setting will only become active upon next (re)connect. * \param[in] link Stream Server Link to modify * \param[in] type Socket Domain (like AF_UNSPEC (default for IP), AF_UNIX, AF_INET, ...) * \returns zero on success, negative on error. @@ -326,7 +369,7 @@ return 0; } -/*! \brief Set application private data of the stream server link +/*! Set application private data of the stream server link. * \param[in] link Stream Server Link to modify * \param[in] data User-specific data (available in call-back functions) */ void @@ -336,7 +379,7 @@ link->data = data; } -/*! \brief Get application private data of the stream server link +/*! Retrieve application private data of the stream server link. * \param[in] link Stream Server Link to modify * \returns Application private data, as set by \ref osmo_stream_cli_set_data() */ void *osmo_stream_srv_link_get_data(struct osmo_stream_srv_link *link) @@ -398,7 +441,9 @@ } } -/*! \brief Get description of the stream server link e. g. 127.0.0.1:1234 +/*! Retrieve description of the stream server link e. g. 127.0.0.1:1234. + * Calling this function will build a string that describes the socket in terms of its local/remote + * address/port. The returned name is stored in a static buffer; it is hence not re-entrant or thread-safe. * \param[in] link Stream Server Link to examine * \returns Link description or NULL in case of error */ char *osmo_stream_srv_link_get_sockname(const struct osmo_stream_srv_link *link) @@ -410,7 +455,7 @@ return buf; } -/*! \brief Get Osmocom File Descriptor of the stream server link +/*! Retrieve Osmocom File Descriptor of the stream server link. * \param[in] link Stream Server Link * \returns Pointer to \ref osmo_fd */ struct osmo_fd * @@ -419,7 +464,7 @@ return &link->ofd; } -/*! \brief Get File Descriptor of the stream server link +/*! Retrieve File Descriptor of the stream server link. * \param[in] conn Stream Server Link * \returns file descriptor or negative on error */ int osmo_stream_srv_link_get_fd(const struct osmo_stream_srv_link *link) @@ -427,7 +472,10 @@ return link->ofd.fd; } -/*! \brief Set the accept() call-back of the stream server link +/*! Set the accept() call-back of the stream server link. + * The provided call-back will be called whenever a new inbound connection + * is accept()ed. The call-back then typically creates a new osmo_stream_srv. + * If the call-back returns a negative value, the file descriptor will be closed. * \param[in] link Stream Server Link * \param[in] accept_cb Call-back function executed upon accept() */ void osmo_stream_srv_link_set_accept_cb(struct osmo_stream_srv_link *link, @@ -437,7 +485,7 @@ link->accept_cb = accept_cb; } -/*! \brief Destroy the stream server link. Closes + Releases Memory. +/*! Destroy the stream server link. Closes + Releases Memory. * \param[in] link Stream Server Link */ void osmo_stream_srv_link_destroy(struct osmo_stream_srv_link *link) { @@ -445,8 +493,8 @@ talloc_free(link); } -/*! \brief Open the stream server link. This actually initializes the - * underlying socket and binds it to the configured ip/port +/*! Open the stream server link. This actually initializes the + * underlying socket and binds it to the configured ip/port. * \param[in] link Stream Server Link to open * \return negative on error, 0 on success */ int osmo_stream_srv_link_open(struct osmo_stream_srv_link *link) @@ -500,7 +548,7 @@ return 0; } -/*! \brief Check whether the stream server link is opened +/*! Check whether the stream server link is opened. * \param[in] link Stream Server Link to check */ bool osmo_stream_srv_link_is_opened(const struct osmo_stream_srv_link *link) { @@ -513,7 +561,7 @@ return true; } -/*! \brief Close the stream server link and unregister from select loop +/*! Close the stream server link and unregister from select loop. * Does not destroy the server link, merely closes it! * \param[in] link Stream Server Link to close */ void osmo_stream_srv_link_close(struct osmo_stream_srv_link *link) @@ -526,6 +574,12 @@ link->ofd.fd = -1; } +/*! Set given parameter of stream_srv_link to given value. + * \param[in] cli stream client on which to set parameter. + * \param[in] par identifier of the parameter to be set. + * \param[in] val value of the parameter to be set. + * \param[in] val_len length of the parameter value. + * \returns 0 in success; negative -errno on error. */ int osmo_stream_srv_link_set_param(struct osmo_stream_srv_link *link, enum osmo_stream_srv_link_param par, void *val, size_t val_len) { @@ -773,7 +827,15 @@ return rc; } -/*! \brief Create a Stream Server inside the specified link +/*! Create a legacy osmo_fd mode Stream Server inside the specified link. + * + * This is the function an application traditionally calls from within the + * accept_cb call-back of the osmo_stream_srv_link. It creates a new + * osmo_stream_srv within that link. + * + * New users/programs should use osmo_stream_srv_create2 to operate in osmo_io + * mode instead. + * * \param[in] ctx talloc allocation context from which to allocate * \param[in] link Stream Server Link to which we belong * \param[in] fd system file descriptor of the new connection @@ -813,7 +875,12 @@ return conn; } -/*! \brief Create a Stream Server inside the specified link +/*! Create an osmo_iofd mode Stream Server inside the specified link. + * + * This is the function an application typically calls from within the + * accept_cb call-back of the osmo_stream_srv_link. It creates a new + * osmo_stream_srv in osmo_io mode within that link. + * * \param[in] ctx talloc allocation context from which to allocate * \param[in] link Stream Server Link to which we belong * \param[in] fd system file descriptor of the new connection @@ -859,8 +926,9 @@ return conn; } -/*! \brief Set a name on the srv object (used during logging) - * \param[in] conn server whose name is to be set +/*! Set a name on the srv object (used during logging). + * \param[in] conn server whose name is to be set. The name is copied into the osmo_stream_srv_link, so + * the caller memory is not required to be valid beyond the call of this function. * \param[in] name the name to be set on conn */ void osmo_stream_srv_set_name(struct osmo_stream_srv *conn, const char *name) @@ -870,7 +938,7 @@ osmo_iofd_set_name(conn->iofd, name); } -/*! \brief Retrieve name previously set on the srv object (see osmo_stream_srv_set_name()) +/*! Retrieve name previously set on the srv object (see osmo_stream_srv_set_name()). * \param[in] conn server whose name is to be retrieved * \returns The name to be set on conn; NULL if never set */ @@ -879,8 +947,13 @@ return conn->name; } -/*! \brief Set the call-back function when data was read from the stream server socket - * Only for osmo_stream_srv created with osmo_stream_srv_create2() +/*! Set the call-back function for incoming data on an osmo_io stream_srv. + * + * This function only works with osmo_stream_srv in osmo_io mode, created by osmo_stream_srv_create2()! + * + * Whenever data is received on the osmo_stram_srv, the read_cb call-back function of the user application is + * called. + * * \param[in] conn Stream Server to modify * \param[in] read_cb Call-back function to be called when data was read */ void osmo_stream_srv_set_read_cb(struct osmo_stream_srv *conn, int (*read_cb)(struct osmo_stream_srv *conn, struct msgb *msg)) @@ -889,7 +962,10 @@ conn->iofd_read_cb = read_cb; } -/*! \brief Set the call-back function called when the stream server socket was closed +/*! Set the call-back function called when the stream server socket was closed. + * Whenever the socket was closed (network error, client disconnect, etc.), the user-provided + * call-back function given here is called. This is typically used by the application to clean up any of its + * internal state related to this specific client/connection. * \param[in] conn Stream Server to modify * \param[in] closed_cb Call-back function to be called when the connection was closed */ void osmo_stream_srv_set_closed_cb(struct osmo_stream_srv *conn, int (*closed_cb)(struct osmo_stream_srv *conn)) @@ -898,7 +974,7 @@ conn->closed_cb = closed_cb; } -/*! \brief Prepare to send out all pending messages on the connection's Tx queue +/*! Prepare to send out all pending messages on the connection's Tx queue. * and then automatically destroy the stream with osmo_stream_srv_destroy(). * This function disables queuing of new messages on the connection and also * disables reception of new messages on the connection. @@ -908,7 +984,7 @@ conn->flags |= OSMO_STREAM_SRV_F_FLUSH_DESTROY; } -/*! \brief Set application private data of the stream server +/*! Set application private data of the stream server. * \param[in] conn Stream Server to modify * \param[in] data User-specific data (available in call-back functions) */ void @@ -918,8 +994,16 @@ conn->data = data; } -/*! \brief Set the segmentation callback for target osmo_stream_srv structure. - * The connection has to have been established prior to calling this function. +/*! Set the segmentation callback for target osmo_stream_srv structure. + * + * A segmentation call-back can optionally be used when a packet based protocol (like TCP) is used within a + * STREAM style socket that does not preserve message boundaries within the stream. If a segmentation + * call-back is given, the osmo_stream_srv library code will makes sure that the read_cb called only for + * complete single messages, and not arbitrary segments of the stream. + * + * This function only works with osmo_stream_srv in osmo_io mode, created by osmo_stream_srv_create2()! + * The connection has to have been established prior to calling this function. + * * \param[in,out] conn Target Stream Server to modify * \param[in] segmentation_cb Segmentation callback to be set */ void osmo_stream_srv_set_segmentation_cb(struct osmo_stream_srv *conn, @@ -936,7 +1020,7 @@ osmo_iofd_set_ioops(conn->iofd, &conn_ops); } -/*! \brief Get application private data of the stream server +/*! Retrieve application private data of the stream server * \param[in] conn Stream Server * \returns Application private data, as set by \ref osmo_stream_srv_set_data() */ void *osmo_stream_srv_get_data(struct osmo_stream_srv *conn) @@ -944,7 +1028,8 @@ return conn->data; } -/*! \brief Get the stream server socket description. +/*! Retrieve the stream server socket description. + * The returned name is stored in a static buffer; it is hence not re-entrant or thread-safe! * \param[in] cli Stream Server to examine * \returns Socket description or NULL in case of error */ const char *osmo_stream_srv_get_sockname(const struct osmo_stream_srv *conn) @@ -957,7 +1042,7 @@ return buf; } -/*! \brief Get Osmocom File Descriptor of the stream server +/*! Retrieve Osmocom File Descriptor of a stream server in osmo_fd mode. * \param[in] conn Stream Server * \returns Pointer to \ref osmo_fd */ struct osmo_fd * @@ -967,7 +1052,7 @@ return &conn->ofd; } -/*! \brief Get File Descriptor of the stream server +/*! Retrieve File Descriptor of the stream server * \param[in] conn Stream Server * \returns file descriptor or negative on error */ int @@ -985,7 +1070,7 @@ return -EINVAL; } -/*! \brief Get the master (Link) from a Stream Server +/*! Retrieve the master (Link) from a Stream Server. * \param[in] conn Stream Server of which we want to know the Link * \returns Link through which the given Stream Server is established */ struct osmo_stream_srv_link *osmo_stream_srv_get_master(struct osmo_stream_srv *conn) @@ -993,11 +1078,10 @@ return conn->srv; } -/*! \brief Destroy given Stream Server - * This function closes the Stream Server socket, unregisters from - * select loop, invokes the connection's closed_cb() callback to allow API - * users to clean up any associated state they have for this connection, - * and then de-allocates associated memory. +/*! Destroy given Stream Server. + * This function closes the Stream Server socket, unregisters from the underlying I/O mechanism, invokes the + * connection's closed_cb() callback to allow API users to clean up any associated state they have for this + * connection, and then de-allocates associated memory. * \param[in] conn Stream Server to be destroyed */ void osmo_stream_srv_destroy(struct osmo_stream_srv *conn) { @@ -1020,7 +1104,7 @@ talloc_free(conn); } -/*! \brief Enqueue data to be sent via an Osmocom stream server +/*! Enqueue data to be sent via an Osmocom stream server. * \param[in] conn Stream Server through which we want to send * \param[in] msg Message buffer to enqueue in transmit queue */ void osmo_stream_srv_send(struct osmo_stream_srv *conn, struct msgb *msg) @@ -1053,11 +1137,15 @@ } } -/*! \brief Receive data via Osmocom stream server +/*! Receive data via an Osmocom stream server in osmo_fd mode. * \param[in] conn Stream Server from which to receive * \param msg pre-allocate message buffer to which received data is appended * \returns number of bytes read, negative on error. * + * Application programs using the legacy osmo_fd mode of osmo_stream_srv will use + * this function to read/receive from a stream socket after they have been notified that + * it is readable (via select/poll). + * * If conn is an SCTP connection, additional specific considerations shall be taken: * - msg->cb is always filled with SCTP ppid, and SCTP stream values, see msgb_sctp_*() APIs. * - If an SCTP notification was received when reading from the SCTP socket, -- To view, visit https://gerrit.osmocom.org/c/libosmo-netif/+/36294?usp=email To unsubscribe, or for help writing mail filters, visit https://gerrit.osmocom.org/settings Gerrit-Project: libosmo-netif Gerrit-Branch: master Gerrit-Change-Id: Iae3c3af6533be408e5755ceeda0067606a3b0ca1 Gerrit-Change-Number: 36294 Gerrit-PatchSet: 3 Gerrit-Owner: laforge <laforge(a)osmocom.org> Gerrit-Reviewer: Jenkins Builder Gerrit-Reviewer: laforge <laforge(a)osmocom.org> Gerrit-Reviewer: pespin <pespin(a)sysmocom.de> Gerrit-MessageType: merged

1 year, 5 months

1
0
0 0

[L] Change in libosmo-netif[master]: docs: More verbose stream_{cli,srv} API documentation/manual

by laforge

laforge has posted comments on this change. ( https://gerrit.osmocom.org/c/libosmo-netif/+/36294?usp=email ) Change subject: docs: More verbose stream_{cli,srv} API documentation/manual ...................................................................... Patch Set 3: Code-Review+2 -- To view, visit https://gerrit.osmocom.org/c/libosmo-netif/+/36294?usp=email To unsubscribe, or for help writing mail filters, visit https://gerrit.osmocom.org/settings Gerrit-Project: libosmo-netif Gerrit-Branch: master Gerrit-Change-Id: Iae3c3af6533be408e5755ceeda0067606a3b0ca1 Gerrit-Change-Number: 36294 Gerrit-PatchSet: 3 Gerrit-Owner: laforge <laforge(a)osmocom.org> Gerrit-Reviewer: Jenkins Builder Gerrit-Reviewer: laforge <laforge(a)osmocom.org> Gerrit-Reviewer: pespin <pespin(a)sysmocom.de> Gerrit-Comment-Date: Sat, 16 Mar 2024 09:24:44 +0000 Gerrit-HasComments: No Gerrit-Has-Labels: Yes Gerrit-MessageType: comment

1 year, 5 months

1
0
0 0

[S] Change in libosmo-sccp[master]: Use same msgb allocation size like before osmo_io introduction

by laforge

laforge has uploaded this change for review. ( https://gerrit.osmocom.org/c/libosmo-sccp/+/36315?usp=email ) Change subject: Use same msgb allocation size like before osmo_io introduction ...................................................................... Use same msgb allocation size like before osmo_io introduction In Change-Id Ia1910f3b99d918ec2a34d5304c3f40ba015c25c9 we introduced osmo_io support for xUA + IPA. However, when we did that, the msgb allocation sizes of libosmo-sigtran were neglected, and rather the defaults of osmo_io used. This commit returns libosmo-sigtran to the exact msgb allocation + headroom sizes used before the osmo_io migration. Related: OS#5752 Closes: OS#6403 Depends: libosmo-netif.git Change-Id Ie19c8294ddb12dfe5e0fd44e047c47e6f9cbd384 Change-Id: I0c6dcff4523e4c04aae43a4585b5e0c3617ef1a6 --- M src/m3ua.c M src/osmo_ss7_asp.c M src/osmo_ss7_xua_srv.c M src/xua_internal.h 4 files changed, 29 insertions(+), 3 deletions(-) git pull ssh://gerrit.osmocom.org:29418/libosmo-sccp refs/changes/15/36315/1 diff --git a/src/m3ua.c b/src/m3ua.c index f4dbf76..fcbc759 100644 --- a/src/m3ua.c +++ b/src/m3ua.c @@ -310,9 +310,6 @@ (mdh->ni & 0x3 << 6); } -#define M3UA_MSG_SIZE 2048 -#define M3UA_MSG_HEADROOM 512 - struct msgb *m3ua_msgb_alloc(const char *name) { if (!name) diff --git a/src/osmo_ss7_asp.c b/src/osmo_ss7_asp.c index 92b3a5b..1f45749 100644 --- a/src/osmo_ss7_asp.c +++ b/src/osmo_ss7_asp.c @@ -43,6 +43,7 @@ #include <osmocom/core/msgb.h> #include <osmocom/core/socket.h> #include <osmocom/core/sockaddr_str.h> +#include <osmocom/core/osmo_io.h> #include <osmocom/netif/stream.h> #include <osmocom/netif/ipa.h> @@ -900,6 +901,8 @@ if (fd < 0) return fd; + osmo_iofd_set_alloc_info(osmo_stream_cli_get_iofd(cli), M3UA_MSG_SIZE, M3UA_MSG_HEADROOM); + /* update the socket name */ talloc_free(asp->sock_name); asp->sock_name = osmo_sock_get_name(asp, fd); diff --git a/src/osmo_ss7_xua_srv.c b/src/osmo_ss7_xua_srv.c index eeb6768..473826f 100644 --- a/src/osmo_ss7_xua_srv.c +++ b/src/osmo_ss7_xua_srv.c @@ -43,6 +43,7 @@ #include <osmocom/core/msgb.h> #include <osmocom/core/socket.h> #include <osmocom/core/sockaddr_str.h> +#include <osmocom/core/osmo_io.h> #include <osmocom/netif/stream.h> #include <osmocom/netif/ipa.h> @@ -80,6 +81,8 @@ return -1; } + osmo_iofd_set_alloc_info(osmo_stream_srv_get_iofd(srv), M3UA_MSG_SIZE, M3UA_MSG_HEADROOM); + switch (oxs->cfg.proto) { case OSMO_SS7_ASP_PROT_IPA: osmo_stream_srv_set_read_cb(srv, ss7_asp_ipa_srv_conn_rx_cb); diff --git a/src/xua_internal.h b/src/xua_internal.h index b6b33af..d4b16f9 100644 --- a/src/xua_internal.h +++ b/src/xua_internal.h @@ -4,6 +4,9 @@ #include <osmocom/sigtran/osmo_ss7.h> #include <osmocom/sigtran/xua_msg.h> +#define M3UA_MSG_SIZE 2048 +#define M3UA_MSG_HEADROOM 512 + struct osmo_sccp_addr; struct m3ua_data_hdr; -- To view, visit https://gerrit.osmocom.org/c/libosmo-sccp/+/36315?usp=email To unsubscribe, or for help writing mail filters, visit https://gerrit.osmocom.org/settings Gerrit-Project: libosmo-sccp Gerrit-Branch: master Gerrit-Change-Id: I0c6dcff4523e4c04aae43a4585b5e0c3617ef1a6 Gerrit-Change-Number: 36315 Gerrit-PatchSet: 1 Gerrit-Owner: laforge <laforge(a)osmocom.org> Gerrit-MessageType: newchange

1 year, 5 months

1
0
0 0

[S] Change in libosmo-netif[master]: introduce osmo_stream_cli_get_iofd() API

by laforge

laforge has uploaded this change for review. ( https://gerrit.osmocom.org/c/libosmo-netif/+/36314?usp=email ) Change subject: introduce osmo_stream_cli_get_iofd() API ...................................................................... introduce osmo_stream_cli_get_iofd() API Using this, a user can obtain the osmo_io_fd, for example in order to perform configuration like osmo_iofd_set_alloc_info() or osmo_iofd_set_txqueue_max_length(). Change-Id: Ie19c8294ddb12dfe5e0fd44e047c47e6f9cbd384 --- M include/osmocom/netif/stream.h M src/stream_cli.c M src/stream_srv.c 3 files changed, 37 insertions(+), 0 deletions(-) git pull ssh://gerrit.osmocom.org:29418/libosmo-netif refs/changes/14/36314/1 diff --git a/include/osmocom/netif/stream.h b/include/osmocom/netif/stream.h index 1d97530..61bc1ad 100644 --- a/include/osmocom/netif/stream.h +++ b/include/osmocom/netif/stream.h @@ -109,6 +109,7 @@ const char *osmo_stream_srv_get_sockname(const struct osmo_stream_srv *conn); struct osmo_fd *osmo_stream_srv_get_ofd(struct osmo_stream_srv *srv); int osmo_stream_srv_get_fd(const struct osmo_stream_srv *srv); +struct osmo_io_fd *osmo_stream_srv_get_iofd(const struct osmo_stream_srv *srv); void osmo_stream_srv_destroy(struct osmo_stream_srv *conn); void osmo_stream_srv_set_flush_and_destroy(struct osmo_stream_srv *conn); @@ -177,6 +178,7 @@ char *osmo_stream_cli_get_sockname(const struct osmo_stream_cli *cli); struct osmo_fd *osmo_stream_cli_get_ofd(struct osmo_stream_cli *cli); int osmo_stream_cli_get_fd(const struct osmo_stream_cli *cli); +struct osmo_io_fd *osmo_stream_cli_get_iofd(const struct osmo_stream_cli *cli); void osmo_stream_cli_set_connect_cb(struct osmo_stream_cli *cli, int (*connect_cb)(struct osmo_stream_cli *cli)); void osmo_stream_cli_set_disconnect_cb(struct osmo_stream_cli *cli, int (*disconnect_cb)(struct osmo_stream_cli *cli)); void osmo_stream_cli_set_read_cb(struct osmo_stream_cli *cli, int (*read_cb)(struct osmo_stream_cli *cli)); diff --git a/src/stream_cli.c b/src/stream_cli.c index ca60e25..784aa84 100644 --- a/src/stream_cli.c +++ b/src/stream_cli.c @@ -222,6 +222,17 @@ return -EINVAL; } +/*! Retrieve osmo_io descriptor of the stream client socket. + * This function must not be called on a stream client in legacy osmo_fd mode! + * \param[in] cli Stream Client of which we want to obtain the file descriptor + * \returns osmo_io_fd of stream client. */ +struct osmo_io_fd * +osmo_stream_cli_get_iofd(const struct osmo_stream_cli *cli) +{ + OSMO_ASSERT(cli->mode == OSMO_STREAM_MODE_OSMO_IO); + return cli->iofd; +} + static void osmo_stream_cli_read(struct osmo_stream_cli *cli) { LOGSCLI(cli, LOGL_DEBUG, "message received\n"); diff --git a/src/stream_srv.c b/src/stream_srv.c index 3220b9e..a02c1c2 100644 --- a/src/stream_srv.c +++ b/src/stream_srv.c @@ -1037,6 +1037,17 @@ return -EINVAL; } +/*! Retrieve osmo_io descriptor of the stream server socket. + * This function must not be called on a stream server in legacy osmo_fd mode! + * \param[in] srv Stream Server of which we want to obtain the osmo_io descriptor + * \returns osmo_io_fd of stream server. */ +struct osmo_io_fd * +osmo_stream_srv_get_iofd(const struct osmo_stream_srv *srv) +{ + OSMO_ASSERT(srv->mode == OSMO_STREAM_MODE_OSMO_IO); + return srv->iofd; +} + /*! Retrieve the master (Link) from a Stream Server. * \param[in] conn Stream Server of which we want to know the Link * \returns Link through which the given Stream Server is established */ -- To view, visit https://gerrit.osmocom.org/c/libosmo-netif/+/36314?usp=email To unsubscribe, or for help writing mail filters, visit https://gerrit.osmocom.org/settings Gerrit-Project: libosmo-netif Gerrit-Branch: master Gerrit-Change-Id: Ie19c8294ddb12dfe5e0fd44e047c47e6f9cbd384 Gerrit-Change-Number: 36314 Gerrit-PatchSet: 1 Gerrit-Owner: laforge <laforge(a)osmocom.org> Gerrit-MessageType: newchange

1 year, 5 months

1
0
0 0

[S] Change in osmo-iuh[master]: Add ranap_decode_rab_releaseditemies_fromlist()

by laforge

laforge has submitted this change. ( https://gerrit.osmocom.org/c/osmo-iuh/+/36309?usp=email ) Change subject: Add ranap_decode_rab_releaseditemies_fromlist() ...................................................................... Add ranap_decode_rab_releaseditemies_fromlist() This function is analogous to existing ranap_decode_*_itemies_fromlist() which we already had. This is needed in an upcoming osmo-hnbgw patchset where we need to parse the ReleasedItems in order to track RAB release progess in order to gather KPIs on RAB release. Change-Id: I328819c650fc6cefe735093a846277b4f03e6b29 --- M include/osmocom/ranap/ranap_common.h M src/ranap_common.c 2 files changed, 44 insertions(+), 0 deletions(-) Approvals: pespin: Looks good to me, but someone else must approve Jenkins Builder: Verified laforge: Looks good to me, approved diff --git a/include/osmocom/ranap/ranap_common.h b/include/osmocom/ranap/ranap_common.h index 5727c0d..0da7b10 100644 --- a/include/osmocom/ranap/ranap_common.h +++ b/include/osmocom/ranap/ranap_common.h @@ -661,3 +661,8 @@ int ranap_decode_rab_setupormodifyitemfirst( RANAP_RAB_SetupOrModifyItemFirst_t *raB_SetupOrModifyItemFirst, ANY_t *any_p); + +/* There is no generated decoder available, this is a custom one */ +int ranap_decode_rab_releaseditemies_fromlist( + RANAP_RAB_ReleasedItemIEs_t *raB_ReleasedItemIEs, + ANY_t *any_p); diff --git a/src/ranap_common.c b/src/ranap_common.c index f264ac0..2c99ecd 100644 --- a/src/ranap_common.c +++ b/src/ranap_common.c @@ -628,6 +628,29 @@ return decoded; } +int ranap_decode_rab_releaseditemies_fromlist(RANAP_RAB_ReleasedItemIEs_t *raB_ReleasedItemIEs, ANY_t *any_p) +{ + RANAP_RAB_ReleasedItem_t *ranaP_RABReleasedItem_p = NULL; + int decoded; + + assert(any_p != NULL); + assert(raB_ReleasedItemIEs != NULL); + + memset(raB_ReleasedItemIEs, 0, sizeof(RANAP_RAB_ReleasedItemIEs_t)); + RANAP_DEBUG("Decoding message RANAP_RAB_ReleasedItemIEs (%s:%d)\n", __FILE__, __LINE__); + decoded = ANY_to_type_aper(any_p, &asn_DEF_RANAP_RAB_ReleasedItem, (void **)&ranaP_RABReleasedItem_p); + if (decoded < 0) { + LOGP(DRANAP, LOGL_ERROR, "Decoding of IE raB_ReleasedItem failed\n"); + return -1; + } + if (asn1_xer_print) + xer_fprint(stdout, &asn_DEF_RANAP_RAB_ReleasedItem, ranaP_RABReleasedItem_p); + memcpy(&raB_ReleasedItemIEs->raB_ReleasedItem, ranaP_RABReleasedItem_p, sizeof(RANAP_RAB_ReleasedItem_t)); + FREEMEM(ranaP_RABReleasedItem_p); + + return decoded; +} + int ranap_decode_rab_setupormodifyitemfirst( RANAP_RAB_SetupOrModifyItemFirst_t *raB_SetupOrModifyItemFirst, ANY_t *any_p) -- To view, visit https://gerrit.osmocom.org/c/osmo-iuh/+/36309?usp=email To unsubscribe, or for help writing mail filters, visit https://gerrit.osmocom.org/settings Gerrit-Project: osmo-iuh Gerrit-Branch: master Gerrit-Change-Id: I328819c650fc6cefe735093a846277b4f03e6b29 Gerrit-Change-Number: 36309 Gerrit-PatchSet: 2 Gerrit-Owner: laforge <laforge(a)osmocom.org> Gerrit-Reviewer: Jenkins Builder Gerrit-Reviewer: laforge <laforge(a)osmocom.org> Gerrit-Reviewer: pespin <pespin(a)sysmocom.de> Gerrit-MessageType: merged

1 year, 5 months

1
0
0 0

[S] Change in osmo-iuh[master]: ranap_common: fix pointer type in ranap_decode_rab_releaseitemies_fro...

by laforge

laforge has submitted this change. ( https://gerrit.osmocom.org/c/osmo-iuh/+/36310?usp=email ) Change subject: ranap_common: fix pointer type in ranap_decode_rab_releaseitemies_fromlist() ...................................................................... ranap_common: fix pointer type in ranap_decode_rab_releaseitemies_fromlist() This looked like a copy+paste mistake in Change-Id I4fc88402a863bc1482947985f759d3a26eea4164 Related: OS#5152 Change-Id: I16286c6f13dc4e8d5c6a7f0efacd22bafe04b0a5 --- M src/ranap_common.c 1 file changed, 13 insertions(+), 1 deletion(-) Approvals: laforge: Looks good to me, approved Jenkins Builder: Verified pespin: Looks good to me, but someone else must approve diff --git a/src/ranap_common.c b/src/ranap_common.c index 2c99ecd..68c3d2d 100644 --- a/src/ranap_common.c +++ b/src/ranap_common.c @@ -607,7 +607,7 @@ int ranap_decode_rab_releaseitemies_fromlist(RANAP_RAB_ReleaseItemIEs_t *raB_ReleaseItemIEs, ANY_t *any_p) { - RANAP_RAB_FailedItem_t *ranaP_RABReleaseItem_p = NULL; + RANAP_RAB_ReleaseItem_t *ranaP_RABReleaseItem_p = NULL; int decoded; assert(any_p != NULL); -- To view, visit https://gerrit.osmocom.org/c/osmo-iuh/+/36310?usp=email To unsubscribe, or for help writing mail filters, visit https://gerrit.osmocom.org/settings Gerrit-Project: osmo-iuh Gerrit-Branch: master Gerrit-Change-Id: I16286c6f13dc4e8d5c6a7f0efacd22bafe04b0a5 Gerrit-Change-Number: 36310 Gerrit-PatchSet: 2 Gerrit-Owner: laforge <laforge(a)osmocom.org> Gerrit-Reviewer: Jenkins Builder Gerrit-Reviewer: laforge <laforge(a)osmocom.org> Gerrit-Reviewer: pespin <pespin(a)sysmocom.de> Gerrit-MessageType: merged

1 year, 5 months

1
0
0 0

[S] Change in osmo-iuh[master]: ranap_common: fix pointer type in ranap_decode_rab_releaseitemies_fro...

by laforge

laforge has posted comments on this change. ( https://gerrit.osmocom.org/c/osmo-iuh/+/36310?usp=email ) Change subject: ranap_common: fix pointer type in ranap_decode_rab_releaseitemies_fromlist() ...................................................................... Patch Set 2: Code-Review+2 -- To view, visit https://gerrit.osmocom.org/c/osmo-iuh/+/36310?usp=email To unsubscribe, or for help writing mail filters, visit https://gerrit.osmocom.org/settings Gerrit-Project: osmo-iuh Gerrit-Branch: master Gerrit-Change-Id: I16286c6f13dc4e8d5c6a7f0efacd22bafe04b0a5 Gerrit-Change-Number: 36310 Gerrit-PatchSet: 2 Gerrit-Owner: laforge <laforge(a)osmocom.org> Gerrit-Reviewer: Jenkins Builder Gerrit-Reviewer: laforge <laforge(a)osmocom.org> Gerrit-Reviewer: pespin <pespin(a)sysmocom.de> Gerrit-Comment-Date: Sat, 16 Mar 2024 07:39:45 +0000 Gerrit-HasComments: No Gerrit-Has-Labels: Yes Gerrit-MessageType: comment

1 year, 5 months

1
0
0 0

2025

2024

2023

2022

gerrit-log March 2024