On 19 May 2015 at 16:19, Ciprian Barbu <ciprian.ba...@linaro.org> wrote: > On Tue, May 19, 2015 at 1:03 AM, Ola Liljedahl <ola.liljed...@linaro.org> > wrote: >> As promised, here is my first attempt at a standalone API for IPC - inter >> process communication in a shared nothing architecture (message passing >> between processes which do not share memory). >> >> Currently all definitions are in the file ipc.h but it is possible to >> break out some message/event related definitions (everything from >> odp_ipc_sender) in a separate file message.h. This would mimic the >> packet_io.h/packet.h separation. >> >> The semantics of message passing is that sending a message to an endpoint >> will always look like it succeeds. The appearance of endpoints is explicitly >> notified through user-defined messages specified in the odp_ipc_resolve() >> call. Similarly, the disappearance (e.g. death or otherwise lost connection) >> is also explicitly notified through user-defined messages specified in the >> odp_ipc_monitor() call. The send call does not fail because the addressed >> endpoints has disappeared. >> >> Messages (from endpoint A to endpoint B) are delivered in order. If message >> N sent to an endpoint is delivered, then all messages <N have also been >> delivered. Message delivery does not guarantee actual processing by the >> recipient. End-to-end acknowledgements (using messages) should be used if >> this guarantee is important to the user. >> >> IPC endpoints can be seen as interfaces (taps) to an internal reliable >> multidrop network where each endpoint has a unique address which is only >> valid for the lifetime of the endpoint. I.e. if an endpoint is destroyed >> and then recreated (with the same name), the new endpoint will have a >> new address (eventually endpoints addresses will have to be recycled but >> not for a very long time). Endpoints names do not necessarily have to be >> unique. >> >> Signed-off-by: Ola Liljedahl <ola.liljed...@linaro.org> >> --- >> (This document/code contribution attached is provided under the terms of >> agreement LES-LTM-21309) >> >> include/odp/api/ipc.h | 261 >> ++++++++++++++++++++++++++++++++++++++++++++++++++ >> 1 file changed, 261 insertions(+) >> create mode 100644 include/odp/api/ipc.h >> >> diff --git a/include/odp/api/ipc.h b/include/odp/api/ipc.h >> new file mode 100644 >> index 0000000..3395a34 >> --- /dev/null >> +++ b/include/odp/api/ipc.h >> @@ -0,0 +1,261 @@ >> +/* Copyright (c) 2015, Linaro Limited >> + * All rights reserved. >> + * >> + * SPDX-License-Identifier: BSD-3-Clause >> + */ >> + >> + >> +/** >> + * @file >> + * >> + * ODP IPC API >> + */ >> + >> +#ifndef ODP_API_IPC_H_ >> +#define ODP_API_IPC_H_ >> + >> +#ifdef __cplusplus >> +extern "C" { >> +#endif >> + >> +/** @defgroup odp_ipc ODP IPC >> + * @{ >> + */ >> + >> +/** >> + * @typedef odp_ipc_t >> + * ODP IPC handle >> + */ >> + >> +/** >> + * @typedef odp_ipc_msg_t >> + * ODP IPC message handle >> + */ >> + >> + >> +/** >> + * @def ODP_IPC_ADDR_SIZE >> + * Size of the address of an IPC endpoint >> + */ >> + >> +/** >> + * Create IPC endpoint >> + * >> + * @param name Name of local IPC endpoint >> + * @param pool Pool for incoming messages >> + * >> + * @return IPC handle on success >> + * @retval ODP_IPC_INVALID on failure and errno set >> + */ >> +odp_ipc_t odp_ipc_create(const char *name, odp_pool_t pool); >> + >> +/** >> + * Destroy IPC endpoint >> + * >> + * @param ipc IPC handle >> + * >> + * @retval 0 on success >> + * @retval <0 on failure >> + */ >> +int odp_ipc_destroy(odp_ipc_t ipc); >> + >> +/** >> + * Set the default input queue for an IPC endpoint >> + * >> + * @param ipc IPC handle >> + * @param queue Queue handle >> + * >> + * @retval 0 on success >> + * @retval <0 on failure >> + */ >> +int odp_ipc_inq_setdef(odp_ipc_t ipc, odp_queue_t queue); >> + >> +/** >> + * Remove the default input queue >> + * >> + * Remove (disassociate) the default input queue from an IPC endpoint. >> + * The queue itself is not touched. >> + * >> + * @param ipc IPC handle >> + * >> + * @retval 0 on success >> + * @retval <0 on failure >> + */ >> +int odp_ipc_inq_remdef(odp_ipc_t ipc); >> + >> +/** >> + * Resolve endpoint by name >> + * >> + * Look up an existing or future endpoint by name. >> + * When the endpoint exists, return the specified message with the endpoint >> + * as the sender. >> + * >> + * @param ipc IPC handle >> + * @param name Name to resolve >> + * @param msg Message to return >> + */ >> +void odp_ipc_resolve(odp_ipc_t ipc, >> + const char *name, >> + odp_ipc_msg_t msg); > > How does this take into account the 'address' of the endpoint? Will > the name include the search path, something like > "domain_name/endpoint_name"? If so, should there be an API for > creating a communication channel with domain_X? The semantics of names and any network topology is not defined and not really important to the endpoints themselves (the applications).
A specific IPC implementation can support some form of structured or partitioned network topology without changes to the IPC client-side API (I think). To compare, in OSE, adding support for link handlers and distributed systems did not change the original API designed for local communication. > >> + >> +/** >> + * Monitor endpoint >> + * >> + * Monitor an existing (potentially already dead) endpoint. >> + * When the endpoint is dead, return the specified message with the endpoint >> + * as the sender. >> + * >> + * Unrecognized or invalid endpoint addresses are treated as dead endpoints. >> + * >> + * @param ipc IPC handle >> + * @param addr Address of monitored endpoint >> + * @param msg Message to return >> + */ >> +void odp_ipc_monitor(odp_ipc_t ipc, >> + const uint8_t addr[ODP_IPC_ADDR_SIZE], >> + odp_ipc_msg_t msg); >> + >> +/** >> + * Send message >> + * >> + * Send a message to an endpoint (which may already be dead). >> + * Message delivery is ordered and reliable. All (accepted) messages will be >> + * delivered up to the point of endpoint death or lost connection. >> + * Actual reception and processing is not guaranteed (use end-to-end >> + * acknowledgements for that). >> + * Monitor the remote endpoint to detect death or lost connection. >> + * >> + * @param ipc IPC handle >> + * @param msg Message to send >> + * @param addr Address of remote endpoint >> + * >> + * @retval 0 on success >> + * @retval <0 on error >> + */ >> +int odp_ipc_send(odp_ipc_t ipc, >> + odp_ipc_msg_t msg, >> + const uint8_t addr[ODP_IPC_ADDR_SIZE]); >> + >> +/** >> + * Get address of sender (source) of message >> + * >> + * @param msg Message handle >> + * @param addr Address of sender endpoint >> + */ >> +void odp_ipc_sender(odp_ipc_msg_t msg, >> + uint8_t addr[ODP_IPC_ADDR_SIZE]); >> + >> +/** >> + * Message data pointer >> + * >> + * Return a pointer to the message data >> + * >> + * @param msg Message handle >> + * >> + * @return Pointer to the message data >> + */ >> +void *odp_ipc_data(odp_ipc_msg_t msg); >> + >> +/** >> + * Message data length >> + * >> + * Return length of the message data. >> + * >> + * @param msg Message handle >> + * >> + * @return Message length >> + */ >> +uint32_t odp_ipc_length(const odp_ipc_msg_t msg); >> + >> +/** >> + * Set message length >> + * >> + * Set length of the message data. >> + * >> + * @param msg Message handle >> + * @param len New length >> + * >> + * @retval 0 on success >> + * @retval <0 on error >> + */ >> +int odp_ipc_reset(const odp_ipc_msg_t msg, uint32_t len); >> + >> +/** >> + * Allocate message >> + * >> + * Allocate a message of a specific size. >> + * >> + * @param pool Message pool to allocate message from >> + * @param len Length of the allocated message >> + * >> + * @return IPC message handle on success >> + * @retval ODP_IPC_MSG_INVALID on failure and errno set >> + */ >> +odp_ipc_msg_t odp_ipc_alloc(odp_pool_t pool, uint32_t len); >> + >> +/** >> + * Free message >> + * >> + * Free message back to the message pool it was allocated from. >> + * >> + * @param msg Handle of message to free >> + */ >> +void odp_ipc_free(odp_ipc_msg_t msg); >> + >> +/** >> + * Get message handle from event >> + * >> + * Converts an ODP_EVENT_MESSAGE type event to a message. >> + * >> + * @param ev Event handle >> + * >> + * @return Message handle >> + * >> + * @see odp_event_type() >> + */ >> +odp_ipc_msg_t odp_message_from_event(odp_event_t ev); >> + >> +/** >> + * Convert message handle to event >> + * >> + * @param msg Message handle >> + * >> + * @return Event handle >> + */ >> +odp_event_t odp_message_to_event(odp_ipc_msg_t msg); >> + >> +/** >> + * Get printable value for an odp_ipc_t >> + * >> + * @param ipc IPC handle to be printed >> + * @return uint64_t value that can be used to print/display this >> + * handle >> + * >> + * @note This routine is intended to be used for diagnostic purposes >> + * to enable applications to generate a printable value that represents >> + * an odp_ipc_t handle. >> + */ >> +uint64_t odp_ipc_to_u64(odp_ipc_t ipc); >> + >> +/** >> + * Get printable value for an odp_ipc_msg_t >> + * >> + * @param msg Message handle to be printed >> + * @return uint64_t value that can be used to print/display this >> + * handle >> + * >> + * @note This routine is intended to be used for diagnostic purposes >> + * to enable applications to generate a printable value that represents >> + * an odp_ipc_msg_t handle. >> + */ >> +uint64_t odp_ipc_msg_to_u64(odp_ipc_msg_t msg); >> + >> +/** >> + * @} >> + */ >> + >> +#ifdef __cplusplus >> +} >> +#endif >> + >> +#endif >> -- >> 1.9.1 >> >> _______________________________________________ >> lng-odp mailing list >> lng-odp@lists.linaro.org >> https://lists.linaro.org/mailman/listinfo/lng-odp _______________________________________________ lng-odp mailing list lng-odp@lists.linaro.org https://lists.linaro.org/mailman/listinfo/lng-odp