Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
fi_msg(3)			   @VERSION@			     fi_msg(3)

NAME
       fi_msg -	Message	data transfer operations

       fi_recv / fi_recvv / fi_recvmsg
	      Post a buffer to receive an incoming message

       fi_send / fi_sendv / fi_sendmsg
       fi_inject / fi_senddata : Initiate an operation to send a message

SYNOPSIS
	      #include <rdma/fi_endpoint.h>

	      ssize_t fi_recv(struct fid_ep *ep, void *	buf, size_t len,
		  void *desc, fi_addr_t	src_addr, void *context);

	      ssize_t fi_recvv(struct fid_ep *ep, const	struct iovec *iov, void	**desc,
		  size_t count,	fi_addr_t src_addr, void *context);

	      ssize_t fi_recvmsg(struct	fid_ep *ep, const struct fi_msg	*msg,
		  uint64_t flags);

	      ssize_t fi_send(struct fid_ep *ep, const void *buf, size_t len,
		  void *desc, fi_addr_t	dest_addr, void	*context);

	      ssize_t fi_sendv(struct fid_ep *ep, const	struct iovec *iov,
		  void **desc, size_t count, fi_addr_t dest_addr, void *context);

	      ssize_t fi_sendmsg(struct	fid_ep *ep, const struct fi_msg	*msg,
		  uint64_t flags);

	      ssize_t fi_inject(struct fid_ep *ep, const void *buf, size_t len,
		  fi_addr_t dest_addr);

	      ssize_t fi_senddata(struct fid_ep	*ep, const void	*buf, size_t len,
		  void *desc, uint64_t data, fi_addr_t dest_addr, void *context);

	      ssize_t fi_injectdata(struct fid_ep *ep, const void *buf,	size_t len,
		  uint64_t data, fi_addr_t dest_addr);

ARGUMENTS
       ep     Fabric  endpoint	on which to initiate send or post receive buf-
	      fer.

       buf    Data buffer to send or receive.

       len    Length of	data buffer to send or receive,	 specified  in	bytes.
	      Valid   transfers	  are  from  0	bytes  up  to  the  endpoint's
	      max_msg_size.

       iov    Vectored data buffer.

       count  Count of vectored	data entries.

       desc   Descriptor associated with the data buffer.  See fi_mr(3).

       data   Remote CQ	data to	transfer with the sent message.

       dest_addr
	      Destination address for connectionless transfers.	  Ignored  for
	      connected	endpoints.

       src_addr
	      Source  address  to  receive  from for connectionless transfers.
	      Applies only to connectionless  endpoints	 with  the  FI_DIRECT-
	      ED_RECV capability enabled, otherwise this field is ignored.  If
	      set to FI_ADDR_UNSPEC, any source	address	may match.

       msg    Message descriptor for send and receive operations.

       flags  Additional flags to apply	for the	send or	receive	operation.

       context
	      User specified pointer to	associate with	the  operation.	  This
	      parameter	 is  ignored if	the operation will not generate	a suc-
	      cessful completion, unless an op flag specifies the context  pa-
	      rameter be used for required input.

DESCRIPTION
       The  send  functions  --	 fi_send, fi_sendv, fi_sendmsg,	fi_inject, and
       fi_senddata -- are used to transmit a message from one endpoint to  an-
       other  endpoint.	  The  main  difference	between	send functions are the
       number and type of parameters that they accept  as  input.   Otherwise,
       they perform the	same general function.	Messages sent using fi_msg op-
       erations	are received by	a remote endpoint into a buffer	posted to  re-
       ceive such messages.

       The  receive  functions -- fi_recv, fi_recvv, fi_recvmsg	-- post	a data
       buffer to an endpoint to	receive	inbound	messages.  Similar to the send
       operations,  receive  operations	 operate asynchronously.  Users	should
       not touch the posted data buffer(s) until  the  receive	operation  has
       completed.

       An  endpoint must be enabled before an application can post send	or re-
       ceive operations	to it.	For connected endpoints, receive  buffers  may
       be  posted  prior  to  connect  or accept being called on the endpoint.
       This ensures that buffers are available to receive incoming data	 imme-
       diately after the connection has	been established.

       Completed  message  operations  are reported to the user	through	one or
       more event collectors associated	with the endpoint.  Users provide con-
       text  which  are	associated with	each operation,	and is returned	to the
       user as part of the event completion.  See fi_cq	for  completion	 event
       details.

   fi_send
       The call	fi_send	transfers the data contained in	the user-specified da-
       ta buffer to a remote endpoint, with  message  boundaries  being	 main-
       tained.	 For connection	based endpoints	(FI_EP_MSG) the	local endpoint
       must be connected to a remote endpoint or destination before fi_send is
       called.	 Unless	the endpoint has been configured differently, the data
       buffer passed into fi_send must not be touched by the application until
       the fi_send call	completes asynchronously.

   fi_sendv
       The  fi_sendv  call  adds support for a scatter-gather list to fi_send.
       The fi_sendv transfers the set of data buffers referenced  by  the  iov
       parameter to a remote endpoint as a single message.

   fi_sendmsg
       The fi_sendmsg call supports data transfers over	both connected and un-
       connected endpoints, with the ability to	control	the send operation per
       call  through  the  use	of  flags.   The  fi_sendmsg  function takes a
       struct fi_msg as	input.

	      struct fi_msg {
		  const	struct iovec *msg_iov; /* scatter-gather array */
		  void		     **desc;   /* local	request	descriptors */
		  size_t	     iov_count;/* # elements in	iov */
		  fi_addr_t	     addr;     /* optional endpoint address */
		  void		     *context; /* user-defined context */
		  uint64_t	     data;     /* optional message data	*/
	      };

   fi_inject
       The send	inject call is an optimized version of fi_send with  the  fol-
       lowing characteristics.	The data buffer	is available for reuse immedi-
       ately on	return from the	call, and no CQ	entry will be written  if  the
       transfer	completes successfully.

       Conceptually,  this means that the fi_inject function behaves as	if the
       FI_INJECT transfer flag were set, selective  completions	 are  enabled,
       and  the	 FI_COMPLETION	flag is	not specified.	Note that the CQ entry
       will be suppressed even if the default behavior of the endpoint	is  to
       write CQ	entries	for all	successful completions.	 See the flags discus-
       sion below for more details.  The requested message size	 that  can  be
       used with fi_inject is limited by inject_size.

   fi_senddata
       The send	data call is similar to	fi_send, but allows for	the sending of
       remote CQ data (see FI_REMOTE_CQ_DATA flag) as part of the transfer.

   fi_injectdata
       The inject data call is similar to fi_inject, but allows	for the	 send-
       ing  of	remote	CQ  data  (see	FI_REMOTE_CQ_DATA flag)	as part	of the
       transfer.

   fi_recv
       The fi_recv call	posts a	data buffer to the receive queue of the	corre-
       sponding	 endpoint.  Posted receives are	searched in the	order in which
       they were posted	in order to match sends.  Message boundaries are main-
       tained.	 The  order in which the receives complete is dependent	on the
       endpoint	type and protocol.  For	unconnected  endpoints,	 the  src_addr
       parameter can be	used to	indicate that a	buffer should be posted	to re-
       ceive incoming data from	a specific remote endpoint.

   fi_recvv
       The fi_recvv call adds support for a scatter-gather  list  to  fi_recv.
       The fi_recvv posts the set of data buffers referenced by	the iov	param-
       eter to a receive incoming data.

   fi_recvmsg
       The fi_recvmsg call supports posting buffers over  both	connected  and
       unconnected  endpoints,	with the ability to control the	receive	opera-
       tion per	call through the use of	flags.	The fi_recvmsg function	 takes
       a struct	fi_msg as input.

FLAGS
       The  fi_recvmsg	and  fi_sendmsg	 calls allow the user to specify flags
       which can change	the default message handling of	the  endpoint.	 Flags
       specified  with	fi_recvmsg / fi_sendmsg	override most flags previously
       configured with the endpoint, except where noted	 (see  fi_endpoint.3).
       The   following	list  of  flags	 are  usable  with  fi_recvmsg	and/or
       fi_sendmsg.

       FI_REMOTE_CQ_DATA
	      Applies to fi_sendmsg and	fi_senddata.  Indicates	that remote CQ
	      data  is	available  and	should be sent as part of the request.
	      See fi_getinfo for additional details on FI_REMOTE_CQ_DATA.

       FI_CLAIM
	      Applies to posted	receive	operations  for	 endpoints  configured
	      for  FI_BUFFERED_RECV  or	FI_VARIABLE_MSG.  This flag is used to
	      retrieve a message that was buffered by the provider.   See  the
	      Buffered Receives	section	for details.

       FI_COMPLETION
	      Indicates	 that  a  completion entry should be generated for the
	      specified	operation.  The	endpoint must be bound to a completion
	      queue with FI_SELECTIVE_COMPLETION that corresponds to the spec-
	      ified operation, or this flag is ignored.

       FI_DISCARD
	      Applies to posted	receive	operations  for	 endpoints  configured
	      for  FI_BUFFERED_RECV  or	FI_VARIABLE_MSG.  This flag is used to
	      free a message that was  buffered	 by  the  provider.   See  the
	      Buffered Receives	section	for details.

       FI_MORE
	      Indicates	 that the user has additional requests that will imme-
	      diately be posted	after the current call returns.	 Use  of  this
	      flag  may	 improve performance by	enabling the provider to opti-
	      mize its access to the fabric hardware.

       FI_INJECT
	      Applies to fi_sendmsg.  Indicates	that the outbound data	buffer
	      should  be  returned to user immediately after the send call re-
	      turns, even if the operation is  handled	asynchronously.	  This
	      may require that the underlying provider implementation copy the
	      data into	a local	buffer and transfer out	of that	buffer.	  This
	      flag can only be used with messages smaller than inject_size.

       FI_MULTI_RECV
	      Applies to posted	receive	operations.  This flag allows the user
	      to post a	single buffer that will	receive	multiple incoming mes-
	      sages.  Received messages	will be	packed into the	receive	buffer
	      until the	buffer has been	consumed.  Use of this flag may	 cause
	      a	single posted receive operation	to generate multiple events as
	      messages are placed into the buffer.  The	placement of  received
	      data  into  the  buffer  may  be	subjected to provider specific
	      alignment	restrictions.

       The buffer will be released by the provider when	the  available	buffer
       space  falls  below  the	specified minimum (see FI_OPT_MIN_MULTI_RECV).
       Note that an entry to the associated receive completion queue will  al-
       ways  be	generated when the buffer has been consumed, even if other re-
       ceive completions have been suppressed (i.e.  the Rx context  has  been
       configured for FI_SELECTIVE_COMPLETION).	 See the FI_MULTI_RECV comple-
       tion flag fi_cq(3).

       FI_INJECT_COMPLETE
	      Applies to fi_sendmsg.  Indicates	that a	completion  should  be
	      generated	when the source	buffer(s) may be reused.

       FI_TRANSMIT_COMPLETE
	      Applies  to  fi_sendmsg.	Indicates that a completion should not
	      be generated until the operation has been	successfully transmit-
	      ted and is no longer being tracked by the	provider.

       FI_DELIVERY_COMPLETE
	      Applies  to  fi_sendmsg.	 Indicates that	a completion should be
	      generated	when the operation has been processed by the  destina-
	      tion.

       FI_FENCE
	      Applies  to  transmits.  Indicates that the requested operation,
	      also known as the	fenced operation, and any operation posted af-
	      ter the fenced operation will be deferred	until all previous op-
	      erations targeting the same peer endpoint	have completed.	 Oper-
	      ations  posted after the fencing will see	and/or replace the re-
	      sults of any operations initiated	prior to the fenced operation.

       The ordering of operations starting at the posting of the fenced	opera-
       tion  (inclusive)  to the posting of a subsequent fenced	operation (ex-
       clusive)	is controlled by the endpoint's	ordering semantics.

       FI_MULTICAST
	      Applies to transmits.  This  flag	 indicates  that  the  address
	      specified	 as  the  data transfer	destination is a multicast ad-
	      dress.  This flag	must be	used in	all  multicast	transfers,  in
	      conjunction with a multicast fi_addr_t.

Buffered Receives
       Buffered	receives indicate that the networking layer allocates and man-
       ages the	data buffers used to receive network data transfers.  As a re-
       sult,  received	messages  must be copied from the network buffers into
       application buffers for processing.  However,  applications  can	 avoid
       this  copy  if  they are	able to	process	the message in place (directly
       from the	networking buffers).

       Handling	buffered receives differs based	on the size of the message be-
       ing  sent.  In general, smaller messages	are passed directly to the ap-
       plication for processing.  However, for large messages, an  application
       will  only  receive  the	 start of the message and must claim the rest.
       The details for how small messages are reported and large messages  may
       be claimed are described	below.

       When  a provider	receives a message, it will write an entry to the com-
       pletion queue associated	with the receiving endpoint.   For  discussion
       purposes,  the  completion  queue  is  assumed  to  be  configured  for
       FI_CQ_FORMAT_DATA.  Since buffered receives are not associated with ap-
       plication  posted  buffers,  the	 CQ  entry  op_context will point to a
       struct fi_recv_context.

	      struct fi_recv_context {
		  struct fid_ep	*ep;
		  void *context;
	      };

       The 'ep'	field will point to the	receiving endpoint or Rx context,  and
       'context'  will be NULL.	 The CQ	entry's	'buf' will point to a provider
       managed buffer where the	start of the received message is located,  and
       'len' will be set to the	total size of the message.

       The  maximum  sized message that	a provider can buffer is limited by an
       FI_OPT_BUFFERED_LIMIT.  This threshold can be obtained and may  be  ad-
       justed  by the application using	the fi_getopt and fi_setopt calls, re-
       spectively.  Any	adjustments must be made prior to  enabling  the  end-
       point.  The CQ entry 'buf' will point to	a buffer of received data.  If
       the sent	message	is larger than	the  buffered  amount,	the  CQ	 entry
       'flags'	will  have  the	FI_MORE	bit set.  When the FI_MORE bit is set,
       'buf' will reference at least FI_OPT_BUFFERED_MIN bytes	of  data  (see
       fi_endpoint.3 for more info).

       After  being notified that a buffered receive has arrived, applications
       must either claim or discard the	message.   Typically,  small  messages
       are  processed and discarded, while large messages are claimed.	Howev-
       er, an application is free to claim or discard any  message  regardless
       of message size.

       To  claim  a message, an	application must post a	receive	operation with
       the FI_CLAIM flag set.  The struct fi_recv_context returned as part  of
       the  notification  must be provided as the receive operation's context.
       The struct fi_recv_context contains a  'context'	 field.	  Applications
       may  modify  this  field	prior to claiming the message.	When the claim
       operation completes, a standard receive completion entry	will be	gener-
       ated on the completion queue.  The 'context' of the associated CQ entry
       will be set to the 'context' value passed in through  the  fi_recv_con-
       text structure, and the CQ entry	flags will have	the FI_CLAIM bit set.

       Buffered	 receives that are not claimed must be discarded by the	appli-
       cation when it is done processing the CQ	entry data.  To	discard	a mes-
       sage,  an application must post a receive operation with	the FI_DISCARD
       flag set.  The struct fi_recv_context returned as part of the notifica-
       tion  must  be  provided	 as the	receive	operation's context.  When the
       FI_DISCARD flag is set for a receive operation, the receive input  buf-
       fer(s) and length parameters are	ignored.

       IMPORTANT:  Buffered  receives must be claimed or discarded in a	timely
       manner.	Failure	to do so may result in increased memory	usage for net-
       work  buffering	or  communication stalls.  Once	a buffered receive has
       been claimed or discarded,  the	original  CQ  entry  'buf'  or	struct
       fi_recv_context data may	no longer be accessed by the application.

       The  use	 of  the  FI_CLAIM  and	FI_DISCARD operation flags is also de-
       scribed with  respect  to  tagged  message  transfers  in  fi_tagged.3.
       Buffered	 receives  of  tagged messages will include the	message	tag as
       part of the CQ entry, if	available.

       The handling of buffered	receives follows all message ordering restric-
       tions  assigned	to an endpoint.	 For example, completions may indicate
       the order in which received messages arrived at the receiver  based  on
       the endpoint attributes.

Variable Length	Messages
       Variable	 length	 messages,  or simply variable messages, are transfers
       where the size of the message is	unknown	to the receiver	prior  to  the
       message	being sent.  It	indicates that the recipient of	a message does
       not know	the amount of data to expect prior to  the  message  arriving.
       It  is  most  commonly  used  when the size of message transfers	varies
       greatly,	with very large	messages interspersed with much	 smaller  mes-
       sages,  making  receive	side  message  buffering  difficult to manage.
       Variable	messages are not subject to max	 message  length  restrictions
       (i.e.   struct  fi_ep_attr::max_msg_size	 limits), and may be up	to the
       maximum value of	size_t (e.g.  SIZE_MAX)	in length.

       Variable	length messages	support	requests that  the  provider  allocate
       and  manage  the	network	message	buffers.  As a result, the application
       requirements and	provider behavior is identical as  those  defined  for
       supporting  the	FI_BUFFERED_RECV  mode	bit.  See the Buffered Receive
       section above for details.  The main difference is  that	 buffered  re-
       ceives  are  limited by the fi_ep_attr::max_msg_size threshold, whereas
       variable	length messages	are not.

       Support for variable messages is	indicated through the  FI_VARIABLE_MSG
       capability bit.

NOTES
       If  an endpoint has been	configured with	FI_MSG_PREFIX, the application
       must include buffer space of size msg_prefix_size, as specified by  the
       endpoint	 attributes.  The prefix buffer	must occur at the start	of the
       data referenced by the buf parameter, or	be referenced by the first  IO
       vector.	 Message prefix	space cannot be	split between multiple IO vec-
       tors.  The size of the prefix buffer should be included as part of  the
       total buffer length.

RETURN VALUE
       Returns 0 on success.  On error,	a negative value corresponding to fab-
       ric errno is returned.  Fabric errno values are defined in  rdma/fi_er-
       rno.h.

       See the discussion below	for details handling FI_EAGAIN.

ERRORS
       -FI_EAGAIN
	      Indicates	 that  the underlying provider currently lacks the re-
	      sources needed to	initiate the requested operation.  The reasons
	      for  a provider returning	FI_EAGAIN are varied.  However,	common
	      reasons include insufficient internal buffering or full process-
	      ing queues.

       Insufficient  internal  buffering  is  often associated with operations
       that use	FI_INJECT.  In such cases,  additional	buffering  may	become
       available as posted operations complete.

       Full  processing	 queues	may be a temporary state related to local pro-
       cessing (for example, a large message is	being transferred), or may  be
       the  result of flow control.  In	the latter case, the queues may	remain
       blocked until additional	resources are made  available  at  the	remote
       side of the transfer.

       In  all	cases, the operation may be retried after additional resources
       become available.  It is	strongly recommended that  applications	 check
       for transmit and	receive	completions after receiving FI_EAGAIN as a re-
       turn value, independent of the operation	which failed.  This is partic-
       ularly  important  in  cases  where manual progress is employed,	as ac-
       knowledgements or flow control messages may need	to be processed	in or-
       der to resume execution.

SEE ALSO
       fi_getinfo(3), fi_endpoint(3), fi_domain(3), fi_cq(3)

AUTHORS
       OpenFabrics.

Libfabric Programmer's Manual	  2019-09-27			     fi_msg(3)

NAME | SYNOPSIS | ARGUMENTS | DESCRIPTION | FLAGS | Buffered Receives | Variable Length Messages | NOTES | RETURN VALUE | ERRORS | SEE ALSO | AUTHORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=fi_msg&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help