Detailed Functional Specification for io bulk client.

Collaboration diagram for Detailed Functional Specification for io bulk client.:

Data Structures
struct	m0_io_fop
struct	m0_rpc_bulk_buf
struct	m0_rpc_bulk

Enumerations
enum	m0_rpc_bulk_op_states { M0_RPC_BULK_OP_INITIATE, M0_RPC_BULK_OP_FINISH }
enum	{ M0_RPC_BULK_NETBUF_ALLOCATED = (1 << 0), M0_RPC_BULK_NETBUF_REGISTERED = (1 << 1), M0_RPC_BULK_NETBUF_QUEUED = (1 << 2), M0_RPC_BULK_TMO = 60 }
enum	m0_rpc_bulk_op_type { M0_RPC_BULK_STORE = (1 << 0), M0_RPC_BULK_LOAD = (1 << 1) }

Functions
M0_INTERNAL int	m0_io_fop_init (struct m0_io_fop *iofop, const struct m0_fid *gfid, struct m0_fop_type *ftype, void(*fop_release)(struct m0_ref *))
M0_INTERNAL void	m0_io_fop_fini (struct m0_io_fop *iofop)
M0_INTERNAL struct m0_rpc_bulk *	m0_fop_to_rpcbulk (const struct m0_fop *fop)
M0_INTERNAL int	m0_io_fop_prepare (struct m0_fop *fop)
M0_INTERNAL void	m0_io_fop_destroy (struct m0_fop *fop)
M0_INTERNAL bool	m0_is_read_fop (const struct m0_fop *fop)
M0_INTERNAL bool	m0_is_write_fop (const struct m0_fop *fop)
M0_INTERNAL bool	m0_is_read_rep (const struct m0_fop *fop)
M0_INTERNAL bool	m0_is_write_rep (const struct m0_fop *fop)
M0_INTERNAL bool	m0_is_io_fop (const struct m0_fop *fop)
M0_INTERNAL bool	m0_is_io_fop_rep (const struct m0_fop *fop)
M0_INTERNAL struct m0_fop_cob_rw *	io_rw_get (struct m0_fop *fop)
M0_INTERNAL struct m0_fop_cob_rw_reply *	io_rw_rep_get (struct m0_fop *fop)
M0_INTERNAL bool	m0_is_cob_create_fop (const struct m0_fop *fop)
M0_INTERNAL bool	m0_is_cob_delete_fop (const struct m0_fop *fop)
M0_INTERNAL bool	m0_is_cob_truncate_fop (const struct m0_fop *fop)
M0_INTERNAL bool	m0_is_cob_create_delete_fop (const struct m0_fop *fop)
M0_INTERNAL bool	m0_is_cob_getattr_fop (const struct m0_fop *fop)
M0_INTERNAL bool	m0_is_cob_setattr_fop (const struct m0_fop *fop)
M0_INTERNAL struct m0_fop_cob_common *	m0_cobfop_common_get (struct m0_fop *fop)
M0_INTERNAL void	m0_dump_cob_attr (const struct m0_cob_attr *attr)
M0_INTERNAL int	m0_rpc_bulk_buf_add (struct m0_rpc_bulk *rbulk, uint32_t segs_nr, m0_bcount_t length, struct m0_net_domain *netdom, struct m0_net_buffer *nb, struct m0_rpc_bulk_buf **out)
M0_INTERNAL int	m0_rpc_bulk_buf_databuf_add (struct m0_rpc_bulk_buf *rbuf, void *buf, m0_bcount_t count, m0_bindex_t index, struct m0_net_domain *netdom)
M0_INTERNAL void	m0_rpc_bulk_init (struct m0_rpc_bulk *rbulk)
M0_INTERNAL void	m0_rpc_bulk_buflist_empty (struct m0_rpc_bulk *rbulk)
M0_INTERNAL void	m0_rpc_bulk_fini (struct m0_rpc_bulk *rbulk)
M0_INTERNAL void	m0_rpc_bulk_qtype (struct m0_rpc_bulk *rbulk, enum m0_net_queue_type q)
M0_INTERNAL int	m0_rpc_bulk_store (struct m0_rpc_bulk *rbulk, const struct m0_rpc_conn *conn, struct m0_net_buf_desc_data *to_desc, const struct m0_net_buffer_callbacks *bulk_cb)
M0_INTERNAL int	m0_rpc_bulk_load (struct m0_rpc_bulk *rbulk, const struct m0_rpc_conn *conn, struct m0_net_buf_desc_data *from_desc, const struct m0_net_buffer_callbacks *bulk_cb)
M0_INTERNAL void	m0_rpc_bulk_store_del (struct m0_rpc_bulk *rbulk)
M0_INTERNAL size_t	m0_rpc_bulk_store_del_unqueued (struct m0_rpc_bulk *rbulk)
M0_INTERNAL void	m0_rpc_bulk_default_cb (const struct m0_net_buffer_event *evt)
M0_INTERNAL size_t	m0_rpc_bulk_buf_length (struct m0_rpc_bulk *rbulk)
M0_INTERNAL bool	m0_rpc_bulk_is_empty (struct m0_rpc_bulk *rbulk)

Variables
enum m0_rpc_bulk_op_states	M0_XCA_ENUM
const struct m0_net_buffer_callbacks	m0_rpc__buf_bulk_cb

Detailed Description

The Detailed Functional Specification can be broken down in 2 major subcomponents.

• Generic io fop.
• RPC layer abstraction over bulk IO.

Detailed Level Design for bulk IO interface from rpc layer. Motr rpc layer, network layer and the underlying transport are supposed to constitute a zero-copy path for data IO. In order to do this, rpc layer needs to provide support for bulk interface exported by network layer which gives the capability to bundle IO buffers together and send/receive these buffer descriptors on demand. The underlying transport should have the capabilities to provide zero-copy path (e.g. RDMA). There are 2 major use cases here - read IO and write IO in which bulk interface is needed. The bulk IO interface from network layer provides abstractions like

• m0_net_buffer (a generic buffer identified at network layer) and
• m0_net_buf_desc (an identifier to point to a m0_net_buffer).

Whenever data buffers are encountered in rpc layer, rpc layer (especially formation sub-component) is supposed to take care of segregating these rpc items and register m0_net_buffers where data buffers are encountered (during write request and read reply) and buffer descriptors are copied into rpc items after registering net buffers. These descriptors are sent to the other side which asks for buffers identified by the supplied buffer descriptors.

Sequence of events in case of write IO call for rpc layer. Assumptions

• Write request call has IO buffers associated with it.
• Underlying transport supports zero-copy.

Sequence of events in case of read IO call for rpc layer. Assumptions

• Read request fop has IO buffers associated with it. These buffers are actually empty, they contain no user data. These buffers are replaced by m0_net_buf_desc and packed with rpc.
• Read reply fop consists of number of bytes read.
• Underlying transport supports zero-copy.

Enumeration Type Documentation

anonymous enum

anonymous enum

Represents attributes of struct m0_rpc_bulk_buf.

Enumerator
M0_RPC_BULK_NETBUF_ALLOCATED	The net buffer belonging to struct m0_rpc_bulk_buf is allocated by rpc bulk APIs. So it should be deallocated by rpc bulk APIs as well.
M0_RPC_BULK_NETBUF_REGISTERED	The net buffer belonging to struct m0_rpc_bulk_buf is registered with net domain by rpc bulk APIs. So it should be deregistered by rpc bulk APIs as well.
M0_RPC_BULK_NETBUF_QUEUED	The net buffer has been queued to TM's queue.
M0_RPC_BULK_TMO	RPC bulk operation timeout is kept as 60 sec.

Definition at line 144 of file bulk.h.

m0_rpc_bulk_op_states

enum m0_rpc_bulk_op_states

Enum to identify the state of bulk operation going on.

Enumerator
M0_RPC_BULK_OP_INITIATE
M0_RPC_BULK_OP_FINISH

Definition at line 136 of file bulk.h.

m0_rpc_bulk_op_type

enum m0_rpc_bulk_op_type

Enum to identify the type of bulk operation going on.

Enumerator
M0_RPC_BULK_STORE	Store the net buf descriptors from net buffers to io fops. Typically used by bulk client.
M0_RPC_BULK_LOAD	Load the net buf descriptors from io fops to destination net buffers. Typically used by bulk server.

Definition at line 295 of file bulk.h.

Function Documentation

io_rw_get()

M0_INTERNAL struct m0_fop_cob_rw* io_rw_get

(

struct m0_fop *

fop

)

Definition at line 1037 of file io_fops.c.

io_rw_rep_get()

M0_INTERNAL struct m0_fop_cob_rw_reply* io_rw_rep_get

(

struct m0_fop *

fop

)

Definition at line 1056 of file io_fops.c.

Here is the call graph for this function:

Here is the caller graph for this function:

m0_cobfop_common_get()

M0_INTERNAL struct m0_fop_cob_common* m0_cobfop_common_get

(

struct m0_fop *

fop

)

Definition at line 990 of file io_fops.c.

Here is the call graph for this function:

Here is the caller graph for this function:

m0_dump_cob_attr()

M0_INTERNAL void m0_dump_cob_attr

(

const struct m0_cob_attr *

attr

)

Definition at line 132 of file io_fops.c.

Here is the call graph for this function:

Here is the caller graph for this function:

m0_fop_to_rpcbulk()

M0_INTERNAL struct m0_rpc_bulk* m0_fop_to_rpcbulk

(

const struct m0_fop *

fop

)

Retrieves a m0_rpc_bulk structure from given m0_fop.

Precondition

fop != NULL.

Definition at line 904 of file io_fops.c.

Here is the caller graph for this function:

m0_io_fop_destroy()

M0_INTERNAL void m0_io_fop_destroy

(

struct m0_fop *

fop

)

Deallocates memory for sequence of net buf desc and sequence of index vector from io fop wire format.

Definition at line 1581 of file io_fops.c.

Here is the call graph for this function:

Here is the caller graph for this function:

m0_io_fop_fini()

M0_INTERNAL void m0_io_fop_fini

(

struct m0_io_fop *

iofop

)

Finalizes a m0_io_fop structure.

Precondition

iofop != NULL.

Definition at line 897 of file io_fops.c.

Here is the call graph for this function:

Here is the caller graph for this function:

m0_io_fop_init()

M0_INTERNAL int m0_io_fop_init	(	struct m0_io_fop *	iofop,
		const struct m0_fid *	gfid,
		struct m0_fop_type *	ftype,
		void(*)(struct m0_ref *)	fop_release
	)

Initializes a m0_io_fop structure.

Parameters

ftype	Type of fop to be initialized.
gfid	Global file fid.

Precondition

iofop != NULL.

Postcondition

io_fop_invariant(iofop)

Definition at line 865 of file io_fops.c.

Here is the call graph for this function:

Here is the caller graph for this function:

m0_io_fop_prepare()

M0_INTERNAL int m0_io_fop_prepare

(

struct m0_fop *

fop

)

Allocates memory for net buf descriptors array and index vector array and populate the array of index vectors.

Precondition

fop != NULL.

Definition at line 1513 of file io_fops.c.

Here is the call graph for this function:

Here is the caller graph for this function:

m0_is_cob_create_delete_fop()

M0_INTERNAL bool m0_is_cob_create_delete_fop

(

const struct m0_fop *

fop

)

Definition at line 985 of file io_fops.c.

Here is the call graph for this function:

m0_is_cob_create_fop()

M0_INTERNAL bool m0_is_cob_create_fop

(

const struct m0_fop *

fop

)

Definition at line 950 of file io_fops.c.

Here is the caller graph for this function:

m0_is_cob_delete_fop()

M0_INTERNAL bool m0_is_cob_delete_fop

(

const struct m0_fop *

fop

)

Definition at line 957 of file io_fops.c.

Here is the caller graph for this function:

m0_is_cob_getattr_fop()

M0_INTERNAL bool m0_is_cob_getattr_fop

(

const struct m0_fop *

fop

)

Definition at line 971 of file io_fops.c.

Here is the caller graph for this function:

m0_is_cob_setattr_fop()

M0_INTERNAL bool m0_is_cob_setattr_fop

(

const struct m0_fop *

fop

)

Definition at line 978 of file io_fops.c.

Here is the caller graph for this function:

m0_is_cob_truncate_fop()

M0_INTERNAL bool m0_is_cob_truncate_fop

(

const struct m0_fop *

fop

)

Definition at line 964 of file io_fops.c.

Here is the caller graph for this function:

m0_is_io_fop()

M0_INTERNAL bool m0_is_io_fop

(

const struct m0_fop *

fop

)

Definition at line 928 of file io_fops.c.

Here is the call graph for this function:

Here is the caller graph for this function:

m0_is_io_fop_rep()

M0_INTERNAL bool m0_is_io_fop_rep

(

const struct m0_fop *

fop

)

Definition at line 945 of file io_fops.c.

Here is the call graph for this function:

Here is the caller graph for this function:

m0_is_read_fop()

M0_INTERNAL bool m0_is_read_fop

(

const struct m0_fop *

fop

)

Definition at line 916 of file io_fops.c.

Here is the caller graph for this function:

m0_is_read_rep()

M0_INTERNAL bool m0_is_read_rep

(

const struct m0_fop *

fop

)

Definition at line 933 of file io_fops.c.

Here is the caller graph for this function:

m0_is_write_fop()

M0_INTERNAL bool m0_is_write_fop

(

const struct m0_fop *

fop

)

Definition at line 922 of file io_fops.c.

Here is the caller graph for this function:

m0_is_write_rep()

M0_INTERNAL bool m0_is_write_rep

(

const struct m0_fop *

fop

)

Definition at line 939 of file io_fops.c.

Here is the caller graph for this function:

m0_rpc_bulk_buf_add()

M0_INTERNAL int m0_rpc_bulk_buf_add	(	struct m0_rpc_bulk *	rbulk,
		uint32_t	segs_nr,
		m0_bcount_t	length,
		struct m0_net_domain *	netdom,
		struct m0_net_buffer *	nb,
		struct m0_rpc_bulk_buf **	out
	)

Adds a m0_rpc_bulk_buf structure to the list of such structures in a m0_rpc_bulk structure.

Parameters

segs_nr	Number of segments needed in new m0_rpc_bulk_buf structure.
length	Number of bytes in the buffer. If 0, computed as total size of databufs.
netdom	The m0_net_domain structure to which new m0_rpc_bulk_buf structure will belong to. It is primarily used to keep a check on thresholds like max_seg_size, max_buf_size and max_number_of_segs.
nb	Net buf pointer if user wants to use preallocated network buffer. (nb == NULL) implies that net buffer should be allocated by m0_rpc_bulk_buf_add().
out	Out parameter through which newly created m0_rpc_bulk_buf structure is returned back to the caller. Users need not remove the m0_rpc_bulk_buf structures manually. These structures are removed by rpc bulk callback.

See also

rpc_bulk_buf_cb().

Precondition

rbulk != NULL && segs_nr != 0.

Postcondition

(rc == 0 && *out != NULL) || rc != 0.

See also

m0_rpc_bulk.

Definition at line 291 of file bulk.c.

Here is the call graph for this function:

Here is the caller graph for this function:

m0_rpc_bulk_buf_databuf_add()

M0_INTERNAL int m0_rpc_bulk_buf_databuf_add	(	struct m0_rpc_bulk_buf *	rbuf,
		void *	buf,
		m0_bcount_t	count,
		m0_bindex_t	index,
		struct m0_net_domain *	netdom
	)

Adds a data buffer to zero vector referred to by rpc bulk structure.

Parameters

rbulk	rpc bulk structure to which data buffer will be added.
buf	User space buffer starting address.
count	Number of bytes in user space buffer.
index	Index of target object to which io is targeted.
netdom	Net domain to which the net buffer from m0_rpc_bulk_buf belongs.

Precondition

buf != NULL && count != 0 && netdom != NULL && rpc_bulk_invariant(rbulk).

Postcondition

rpc_bulk_invariant(rbulk).

Definition at line 331 of file bulk.c.

Here is the call graph for this function:

Here is the caller graph for this function:

m0_rpc_bulk_buf_length()

M0_INTERNAL size_t m0_rpc_bulk_buf_length

(

struct m0_rpc_bulk *

rbulk

)

Definition at line 550 of file bulk.c.

Here is the call graph for this function:

Here is the caller graph for this function:

m0_rpc_bulk_buflist_empty()

M0_INTERNAL void m0_rpc_bulk_buflist_empty

(

struct m0_rpc_bulk *

rbulk

)

Removes all m0_rpc_bulk_buf structures from list of such structures in m0_rpc_bulk structure and deallocates it.

Precondition

rbulk != NULL.

Postcondition

rpcbulk_tlist_length(&rbulk->rb_buflist) == 0.

Definition at line 279 of file bulk.c.

Here is the call graph for this function:

Here is the caller graph for this function:

m0_rpc_bulk_default_cb()

M0_INTERNAL void m0_rpc_bulk_default_cb

(

const struct m0_net_buffer_event *

evt

)

Definition at line 140 of file bulk.c.

Here is the call graph for this function:

Here is the caller graph for this function:

m0_rpc_bulk_fini()

M0_INTERNAL void m0_rpc_bulk_fini

(

struct m0_rpc_bulk *

rbulk

)

Finalizes the rpc bulk structure.

Precondition

rbulk != NULL && rpc_bulk_invariant(rbulk).

Definition at line 263 of file bulk.c.

Here is the call graph for this function:

Here is the caller graph for this function:

m0_rpc_bulk_init()

M0_INTERNAL void m0_rpc_bulk_init

(

struct m0_rpc_bulk *

rbulk

)

Initializes a rpc bulk structure.

Parameters

rbulk

rpc bulk structure to be initialized.

Precondition

rbulk != NULL.

Postcondition

rpc_bulk_invariant(rbulk).

Definition at line 247 of file bulk.c.

Here is the call graph for this function:

Here is the caller graph for this function:

m0_rpc_bulk_is_empty()

M0_INTERNAL bool m0_rpc_bulk_is_empty

(

struct m0_rpc_bulk *

rbulk

)

Definition at line 539 of file bulk.c.

Here is the call graph for this function:

Here is the caller graph for this function:

m0_rpc_bulk_load()

M0_INTERNAL int m0_rpc_bulk_load	(	struct m0_rpc_bulk *	rbulk,
		const struct m0_rpc_conn *	conn,
		struct m0_net_buf_desc_data *	from_desc,
		const struct m0_net_buffer_callbacks *	bulk_cb
	)

Loads the m0_net_buf_desc/s pointing to net buffer/s contained by m0_rpc_bulk_buf structure/s in rbulk->rb_buflist and starts RDMA transfer of buffers. This API is typically used by bulk server in a zero-copy buffer transfer.

Parameters

rbulk	Rpc bulk structure from whose list of m0_rpc_bulk_buf structures, net buffers will be added to transfer machine.
conn	The m0_rpc_conn object which represents the rpc connection made with receiving node.
from_desc	The source net buf descriptor which points to the source buffer from which data is copied.

Precondition

rbuf != NULL && item != NULL && from_desc != NULL && (rbuf->bb_nbuf & M0_NET_BUF_REGISTERED) && (rbuf->bb_nbuf.nb_qtype == M0_NET_QT_ACTIVE_BULK_RECV || rbuf->bb_nbuf.nb_qtype == M0_NET_QT_ACTIVE_BULK_SEND).

Postcondition

rpc_bulk_invariant(rbulk).

Definition at line 530 of file bulk.c.

Here is the call graph for this function:

Here is the caller graph for this function:

m0_rpc_bulk_qtype()

M0_INTERNAL void m0_rpc_bulk_qtype	(	struct m0_rpc_bulk *	rbulk,
		enum m0_net_queue_type	q
	)

Assigns queue type for buffers maintained in rbulk->rb_buflist from argument q.

Parameters

rbulk	m0_rpc_bulk structure containing list of m0_rpc_bulk_buf structures whose net buffers queue type has to be assigned.
q	Queue type for m0_net_buffer structures.

Precondition

rbulk != NULL && !m0_tlist_is_empty(rbulk->rb_buflist) && m0_mutex_is_locked(&rbulk->rb_mutex) && q == M0_NET_QT_PASSIVE_BULK_RECV || q == M0_NET_QT_PASSIVE_BULK_SEND || q == M0_NET_QT_ACTIVE_BULK_RECV || q == M0_NET_QT_ACTIVE_BULK_SEND.

Definition at line 372 of file bulk.c.

Here is the call graph for this function:

Here is the caller graph for this function:

m0_rpc_bulk_store()

M0_INTERNAL int m0_rpc_bulk_store	(	struct m0_rpc_bulk *	rbulk,
		const struct m0_rpc_conn *	conn,
		struct m0_net_buf_desc_data *	to_desc,
		const struct m0_net_buffer_callbacks *	bulk_cb
	)

Stores the m0_net_buf_desc/s for net buffer/s pointed to by m0_rpc_bulk_buf structure/s in the io fop wire format. This API is typically invoked by bulk client in a zero-copy buffer transfer.

Parameters

rbulk	Rpc bulk structure from whose list of m0_rpc_bulk_buf structures, the net buf descriptors of io fops will be populated.
conn	The m0_rpc_conn object that represents the rpc connection made with receiving node.
to_desc	Net buf descriptor from fop which will be populated.

Precondition

rbuf != NULL && item != NULL && to_desc != NULL && (rbuf->bb_nbuf & M0_NET_BUF_REGISTERED) && (rbuf->bb_nbuf.nb_qtype == M0_NET_QT_PASSIVE_BULK_RECV || rbuf->bb_nbuf.nb_qtype == M0_NET_QT_PASSIVE_BULK_SEND).

Postcondition

rpc_bulk_invariant(rbulk).

Definition at line 520 of file bulk.c.

Here is the call graph for this function:

Here is the caller graph for this function:

m0_rpc_bulk_store_del()

M0_INTERNAL void m0_rpc_bulk_store_del

(

struct m0_rpc_bulk *

rbulk

)

Does exactly opposite of what m0_rpc_bulk_store() does. Should be called only when m0_rpc_bulk_store() had succeeded earlier and later due to some other condition, bulk transfer did not happen. Now the already stored net buffers need to be deleted from m0_net_transfer_mc so that m0_rpc_bulk object can be finalised. Invocation of this API should be followed by wait on m0_rpc_bulk::rb_chan.

Precondition

rbulk != NULL && rbulk->rb_rc == 0 && rpc_bulk_invariant(rbulk).

Postcondition

rpcbulk_tlist_is_empty(&rbulk->rb_buflist).

Definition at line 215 of file bulk.c.

Here is the call graph for this function:

Here is the caller graph for this function:

m0_rpc_bulk_store_del_unqueued()

M0_INTERNAL size_t m0_rpc_bulk_store_del_unqueued

(

struct m0_rpc_bulk *

rbulk

)

Like m0_rpc_bulk_store_del() but deletes unqueued buffers only. Requires rbulk locked by user.

Returns

number of deleted unqueued bufs.

Definition at line 190 of file bulk.c.

Here is the call graph for this function:

Here is the caller graph for this function:

Variable Documentation

m0_rpc__buf_bulk_cb

const struct m0_net_buffer_callbacks m0_rpc__buf_bulk_cb

Definition at line 238 of file bulk.c.

M0_XCA_ENUM

enum m0_rpc_bulk_op_type M0_XCA_ENUM