diff options
Diffstat (limited to 'usr/src/man/man3dat')
74 files changed, 14210 insertions, 0 deletions
diff --git a/usr/src/man/man3dat/Makefile b/usr/src/man/man3dat/Makefile new file mode 100644 index 0000000000..cb54c45e2e --- /dev/null +++ b/usr/src/man/man3dat/Makefile @@ -0,0 +1,96 @@ +# +# This file and its contents are supplied under the terms of the +# Common Development and Distribution License ("CDDL"), version 1.0. +# You may only use this file in accordance with the terms of version +# 1.0 of the CDDL. +# +# A full copy of the text of the CDDL should have accompanied this +# source. A copy of the CDDL is also available via the Internet +# at http://www.illumos.org/license/CDDL. +# + +# Copyright 2011, Richard Lowe + +include ../../Makefile.master + +MANSECT = 3dat + +MANFILES = dat_cno_create.3dat \ + dat_cno_free.3dat \ + dat_cno_modify_agent.3dat \ + dat_cno_query.3dat \ + dat_cno_wait.3dat \ + dat_cr_accept.3dat \ + dat_cr_handoff.3dat \ + dat_cr_query.3dat \ + dat_cr_reject.3dat \ + dat_ep_connect.3dat \ + dat_ep_create.3dat \ + dat_ep_create_with_srq.3dat \ + dat_ep_disconnect.3dat \ + dat_ep_dup_connect.3dat \ + dat_ep_free.3dat \ + dat_ep_get_status.3dat \ + dat_ep_modify.3dat \ + dat_ep_post_rdma_read.3dat \ + dat_ep_post_rdma_write.3dat \ + dat_ep_post_recv.3dat \ + dat_ep_post_send.3dat \ + dat_ep_query.3dat \ + dat_ep_recv_query.3dat \ + dat_ep_reset.3dat \ + dat_ep_set_watermark.3dat \ + dat_evd_clear_unwaitable.3dat \ + dat_evd_dequeue.3dat \ + dat_evd_disable.3dat \ + dat_evd_enable.3dat \ + dat_evd_free.3dat \ + dat_evd_modify_cno.3dat \ + dat_evd_post_se.3dat \ + dat_evd_query.3dat \ + dat_evd_resize.3dat \ + dat_evd_set_unwaitable.3dat \ + dat_evd_wait.3dat \ + dat_get_consumer_context.3dat \ + dat_get_handle_type.3dat \ + dat_ia_close.3dat \ + dat_ia_open.3dat \ + dat_ia_query.3dat \ + dat_lmr_create.3dat \ + dat_lmr_free.3dat \ + dat_lmr_query.3dat \ + dat_lmr_sync_rdma_read.3dat \ + dat_lmr_sync_rdma_write.3dat \ + dat_provider_fini.3dat \ + dat_provider_init.3dat \ + dat_psp_create.3dat \ + dat_psp_create_any.3dat \ + dat_psp_free.3dat \ + dat_psp_query.3dat \ + dat_pz_create.3dat \ + dat_pz_free.3dat \ + dat_pz_query.3dat \ + dat_registry_add_provider.3dat \ + dat_registry_list_providers.3dat \ + dat_registry_remove_provider.3dat \ + dat_rmr_bind.3dat \ + dat_rmr_create.3dat \ + dat_rmr_free.3dat \ + dat_rmr_query.3dat \ + dat_rsp_create.3dat \ + dat_rsp_free.3dat \ + dat_rsp_query.3dat \ + dat_set_consumer_context.3dat \ + dat_srq_create.3dat \ + dat_srq_free.3dat \ + dat_srq_post_recv.3dat \ + dat_srq_query.3dat \ + dat_srq_resize.3dat \ + dat_srq_set_lw.3dat \ + dat_strerror.3dat + +.KEEP_STATE: + +include ../Makefile.man + +install: $(ROOTMANFILES) diff --git a/usr/src/man/man3dat/dat_cno_create.3dat b/usr/src/man/man3dat/dat_cno_create.3dat new file mode 100644 index 0000000000..052e6f4df8 --- /dev/null +++ b/usr/src/man/man3dat/dat_cno_create.3dat @@ -0,0 +1,142 @@ +'\" te +.\" This manual page is derived from the DAT/uDAPL 1.2 specification. +.\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH dat_cno_create 3DAT "16 Jul 2004" "SunOS 5.11" "Direct Access Transport Library Functions" +.SH NAME +dat_cno_create \- create a CNO instance +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ldat\fR [ \fIlibrary\fR\&.\|.\|. ] +#include <\fBdat/udat.h\fR> + +DAT_RETURN + dat_cno_create ( + IN DAT_IA_HANDLE \fIia_handle\fR, + IN DAT_OS_WAIT_PROXY_AGENT \fIagent\fR, + OUT DAT_CNO_HANDLE *\fIcno_handle\fR + ) +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIia_handle\fR\fR +.ad +.RS 14n +.rt +Handle for an instance of DAT IA. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIagent\fR\fR +.ad +.RS 14n +.rt +An optional OS Wait Proxy Agent that is to be invoked whenever CNO is invoked. +\fBDAT_OS_WAIT_PROXY_AGENT_NULL\fR indicates that there is no proxy agent +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcno_handle\fR\fR +.ad +.RS 14n +.rt +Handle for the created instance of CNO. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBdat_cno_create()\fR function creates a CNO instance. Upon creation, +there are no Event Dispatchers feeding it. +.sp +.LP +The \fIagent\fR parameter specifies the proxy agent, which is OS-dependent and +which is invoked when the CNO is triggered. After it is invoked, it is no +longer associated with the CNO. The value of \fBDAT_OS_WAIT_PROXY_AGENT_NULL\fR +specifies that no OS Wait Proxy Agent is associated with the created CNO. +.sp +.LP +Upon creation, the CNO is not associated with any EVDs, has no waiters and has, +at most, one OS Wait Proxy Agent. +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBDAT_SUCCESS\fR\fR +.ad +.RS 30n +.rt +The operation was successful. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INSUFFICIENT_RESOURCES\fR\fR +.ad +.RS 30n +.rt +The operation failed due to resource limitations. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_HANDLE\fR\fR +.ad +.RS 30n +.rt +The \fIia_handle\fR parameter is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_PARAMETER\fR\fR +.ad +.RS 30n +.rt +One of the parameters was invalid, out of range, or a combination of parameters +was invalid, or the \fIagent\fR parameter is invalid. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard: uDAPL, 1.1, 1.2 +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBlibdat\fR(3LIB), \fBattributes\fR(5) diff --git a/usr/src/man/man3dat/dat_cno_free.3dat b/usr/src/man/man3dat/dat_cno_free.3dat new file mode 100644 index 0000000000..bdb16510a2 --- /dev/null +++ b/usr/src/man/man3dat/dat_cno_free.3dat @@ -0,0 +1,137 @@ +'\" te +.\" This manual page is derived from the DAT/uDAPL 1.2 specification. +.\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH dat_cno_free 3DAT "16 Jul 2004" "SunOS 5.11" "Direct Access Transport Library Functions" +.SH NAME +dat_cno_free \- destroy an instance of the CNO +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ldat\fR [ \fIlibrary\fR\&.\|.\|. ] +#include <\fBdat/udat.h\fR> + +DAT_RETURN + dat_cno_free ( + IN DAT_CNO_HANDLE \fIcno_handle\fR + ) +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIcno_handle\fR\fR +.ad +.RS 14n +.rt +Handle for an instance of the CNO +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBdat_cno_free()\fR function destroys a specified instance of the CNO. +.sp +.LP +A CNO cannot be deleted while it is referenced by an Event Dispatcher or while +a thread is blocked on it. +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBDAT_SUCCESS\fR\fR +.ad +.RS 22n +.rt +The operation was successful. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_HANDLE\fR\fR +.ad +.RS 22n +.rt +The \fBcno_handle()\fR parameter is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_STATE\fR\fR +.ad +.RS 22n +.rt +Parameter in an invalid state. CNO is in use by an EVD instance or there is a +thread blocked on it. +.RE + +.SH USAGE +.sp +.LP +If there is a thread blocked in \fBdat_cno_wait\fR(3DAT), the Consumer can do +the following steps to unblock the waiter: +.RS +4 +.TP +.ie t \(bu +.el o +Create a temporary EVD that accepts software events. It can be created in +advance. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +For a CNO with the waiter, attach that EVD to the CNO and post the software +event on the EVD. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +This unblocks the CNO. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Repeat for other CNOs that have blocked waiters. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Destroy the temporary EVD after all CNOs are destroyed and the EVD is no longer +needed. +.RE +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard: uDAPL, 1.1, 1.2 +_ +MT-LevelUnsafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBdat_cno_wait\fR(3DAT), \fBlibdat\fR(3LIB), \fBattributes\fR(5) diff --git a/usr/src/man/man3dat/dat_cno_modify_agent.3dat b/usr/src/man/man3dat/dat_cno_modify_agent.3dat new file mode 100644 index 0000000000..a651db94cf --- /dev/null +++ b/usr/src/man/man3dat/dat_cno_modify_agent.3dat @@ -0,0 +1,113 @@ +'\" te +.\" This manual page is derived from the DAT/uDAPL 1.2 specification. +.\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH dat_cno_modify_agent 3DAT "16 Jul 2004" "SunOS 5.11" "Direct Access Transport Library Functions" +.SH NAME +dat_cno_modify_agent \- modify the OS Wait Proxy Agent +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ldat\fR [ \fIlibrary\fR\&.\|.\|. ] +#include <\fBdat/udat.h\fR> + +DAT_RETURN + dat_cno_modify_agent ( + IN DAT_CNO_HANDLE \fIcno_handle\fR, + IN DAT_OS_WAIT_PROXY_AGENT \fIagent\fR + ) +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIcno_handle\fR\fR +.ad +.RS 14n +.rt +Handle for an instance of CNO +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIagent\fR\fR +.ad +.RS 14n +.rt +Pointer to an optional OS Wait Proxy Agent to invoke whenever CNO is invoked. +\fBDAT_OS_WAIT_PROXY_AGENT_NULL\fR indicates that there is no proxy agent. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBdat_cno_modify_agent()\fR function modifies the OS Wait Proxy Agent +associated with a CNO. If non-null, any trigger received by the CNO is also +passed to the OS Wait Proxy Agent. This is in addition to any local delivery +through the CNO. The Consumer can pass the value of +\fBDAT_OS_WAIT_PROXY_AGENT_NULL\fR to disassociate the current Proxy agent from +the CNO +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBDAT_SUCCESS\fR\fR +.ad +.RS 25n +.rt +The operation was successful. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_HANDLE\fR\fR +.ad +.RS 25n +.rt +The \fIcno_handle\fR parameter is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_PARAMETER\fR\fR +.ad +.RS 25n +.rt +One of the parameters was invalid, out of range, or a combination of parameters +was invalid, or the \fIagent\fR parameter is invalid. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard: uDAPL, 1.1, 1.2 +_ +MT-LevelUnsafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBlibdat\fR(3LIB), \fBattributes\fR(5) diff --git a/usr/src/man/man3dat/dat_cno_query.3dat b/usr/src/man/man3dat/dat_cno_query.3dat new file mode 100644 index 0000000000..7696a83e54 --- /dev/null +++ b/usr/src/man/man3dat/dat_cno_query.3dat @@ -0,0 +1,130 @@ +'\" te +.\" This manual page is derived from the DAT/uDAPL 1.2 specification. +.\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH dat_cno_query 3DAT "16 Jul 2004" "SunOS 5.11" "Direct Access Transport Library Functions" +.SH NAME +dat_cno_query \- provide the Consumer parameters of the CNO +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ldat\fR [ \fIlibrary\fR\&.\|.\|. ] +#include <\fBdat/udat.h\fR> + +DAT_RETURN + dat_cno_query ( + IN DAT_CNO_HANDLE \fIcno_handle\fR, + IN DAT_CNO_PARAM_MASK \fIcno_param_mask\fR, + OUT DAT_CNO_PARAM *\fIcno_param\fR + ) +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIcno_handle\fR\fR +.ad +.RS 18n +.rt +Handle for the created instance of the Consumer Notification Object +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcno_param_mask\fR\fR +.ad +.RS 18n +.rt +Mask for CNO parameters +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcno_param\fR\fR +.ad +.RS 18n +.rt +Pointer to a Consumer-allocated structure that the Provider fills with CNO +parameters +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBdat_cno_query()\fR function provides the Consumer parameters of the CNO. +The Consumer passes in a pointer to the Consumer-allocated structures for CNO +parameters that the Provider fills. +.sp +.LP +The \fIcno_param_mask\fR parameter allows Consumers to specify which parameters +to query. The Provider returns values for \fIcno_param_mask\fR requested +parameters. The Provider can return values for any other parameters. +.sp +.LP +A value of \fBDAT_OS_WAIT_PROXY_AGENT_NULL\fR in \fIcno_param\fR indicates that +there are no Proxy Agent associated with the CNO. +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBDAT_SUCCESS\fR\fR +.ad +.RS 25n +.rt +The operation was successful. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_PARAMETER\fR\fR +.ad +.RS 25n +.rt +The \fIcno_param_mask\fR parameter is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_HANDLE\fR\fR +.ad +.RS 25n +.rt +The \fIcno_handle\fR parameter is invalid. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard: uDAPL, 1.1, 1.2 +_ +MT-LevelUnsafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBlibdat\fR(3LIB), \fBattributes\fR(5) diff --git a/usr/src/man/man3dat/dat_cno_wait.3dat b/usr/src/man/man3dat/dat_cno_wait.3dat new file mode 100644 index 0000000000..ee322e7fdf --- /dev/null +++ b/usr/src/man/man3dat/dat_cno_wait.3dat @@ -0,0 +1,168 @@ +'\" te +.\" This manual page is derived from the DAT/uDAPL 1.2 specification. +.\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH dat_cno_wait 3DAT "16 Jul 2004" "SunOS 5.11" "Direct Access Transport Library Functions" +.SH NAME +dat_cno_wait \- wait for notification events +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ldat\fR [ \fIlibrary\fR\&.\|.\|. ] +#include <\fBdat/udat.h\fR> + +DAT_RETURN + dat_cno_wait ( + IN DAT_CNO_HANDLE \fIcno_handle\fR, + IN DAT_TIMEOUT \fItimeout\fR, + OUT DAT_EVD_HANDLE *\fIevd_handle\fR + ) +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIcno_handle\fR\fR +.ad +.RS 14n +.rt +Handle for an instance of CNO +.RE + +.sp +.ne 2 +.mk +.na +\fB\fItimeout\fR\fR +.ad +.RS 14n +.rt +The duration to wait for a notification. The value \fBDAT_TIMEOUT_INFINITE\fR +can be used to wait indefinitely. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIevd_handle\fR\fR +.ad +.RS 14n +.rt +Handle for an instance of EVD +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBdat_cno_wait()\fR function allows the Consumer to wait for notification +events from a set of Event Dispatchers all from the same Interface Adapter. The +Consumer blocks until notified or the timeout period expires. +.sp +.LP +An Event Dispatcher that is disabled or in the "Waited" state does not deliver +notifications. A uDAPL Consumer waiting directly upon an Event Dispatcher +preempts the CNO. +.sp +.LP +The consumer can optionally specify a timeout, after which it is unblocked even +if there are no notification events. On a timeout, \fIevd_handle\fR is +explicitly set to a null handle. +.sp +.LP +The returned \fIevd_handle\fR is only a hint. Another Consumer can reap the +Event before this Consumer can get around to checking the Event Dispatcher. +Additionally, other Event Dispatchers feeding this CNO might have been +notified. The Consumer is responsible for ensuring that all EVDs feeding this +CNO are polled regardless of whether they are identified as the immediate cause +of the CNO unblocking. +.sp +.LP +All the waiters on the CNO, including the OS Wait Proxy Agent if it is +associated with the CNO, are unblocked with the NULL handle returns for an +unblocking EVD \fIevd_handle\fR when the IA instance is destroyed or when all +EVDs the CNO is associated with are freed. +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBDAT_SUCCESS\fR\fR +.ad +.RS 25n +.rt +The operation was successful. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_HANDLE\fR\fR +.ad +.RS 25n +.rt +The \fIcno_handle\fR parameter is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_QUEUE_EMPTY\fR\fR +.ad +.RS 25n +.rt +The operation timed out without a notification. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_PARAMETER\fR\fR +.ad +.RS 25n +.rt +One of the parameters was invalid or out of range, a combination of parameters +was invalid, or the \fItimeout\fR parameter is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INTERRUPTED_CALL\fR\fR +.ad +.RS 25n +.rt +The operation was interrupted by a signal. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard: uDAPL, 1.1, 1.2 +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBlibdat\fR(3LIB), \fBattributes\fR(5) diff --git a/usr/src/man/man3dat/dat_cr_accept.3dat b/usr/src/man/man3dat/dat_cr_accept.3dat new file mode 100644 index 0000000000..4e62aaccd8 --- /dev/null +++ b/usr/src/man/man3dat/dat_cr_accept.3dat @@ -0,0 +1,198 @@ +'\" te +.\" This manual page is derived from the DAT/uDAPL 1.2 specification. +.\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH dat_cr_accept 3DAT "16 Jul 2004" "SunOS 5.11" "Direct Access Transport Library Functions" +.SH NAME +dat_cr_accept \- establishes a Connection between the active remote side +requesting Endpoint and the passive side local Endpoint +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ldat\fR [ \fIlibrary\fR\&.\|.\|. ] +#include <\fBdat/udat.h\fR> + +DAT_RETURN + dat_cr_accept ( + IN DAT_CR_HANDLE cr_handle, + IN DAT_EP_HANDLE ep_handle, + IN DAT_COUNT private_data_size, + IN const DAT_PVOID private_data + ) +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIcr_handle\fR\fR +.ad +.RS 21n +.rt +Handle to an instance of a Connection Request that the Consumer is accepting. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIep_handle\fR\fR +.ad +.RS 21n +.rt +Handle for an instance of a local Endpoint that the Consumer is accepting the +Connection Request on. If the local Endpoint is specified by the Connection +Request, the \fIep_handle\fR shall be \fBDAT_HANDLE_NULL\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIprivate_data_size\fR\fR +.ad +.RS 21n +.rt +Size of the \fIprivate_data\fR, which must be nonnegative. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIprivate_data\fR\fR +.ad +.RS 21n +.rt +Pointer to the private data that should be provided to the remote Consumer when +the Connection is established. If \fIprivate_data_size\fR is zero, then +\fIprivate_data\fR can be \fINULL\fR. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBdat_cr_accept()\fR function establishes a Connection between the active +remote side requesting Endpoint and the passive side local Endpoint. The local +Endpoint is either specified explicitly by \fIep_handle\fR or implicitly by a +Connection Request. In the second case, \fIep_handle\fR is +\fBDAT_HANDLE_NULL\fR. +.sp +.LP +Consumers can specify private data that is provided to the remote side upon +Connection establishment. +.sp +.LP +If the provided local Endpoint does not satisfy the requested Connection +Request, the operation fails without any effect on the local Endpoint, Pending +Connection Request, private data, or remote Endpoint. +.sp +.LP +The operation is asynchronous. The successful completion of the operation is +reported through a Connection Event of type +\fBDAT_CONNECTION_EVENT_ESTABLISHED\fR on the \fIconnect_evd\fR of the local +Endpoint. +.sp +.LP +If the Provider cannot complete the Connection establishment, the connection is +not established and the Consumer is notified through a Connection Event of type +\fBDAT_CONNECTION_EVENT_ACCEPT_COMPLETION_ERROR\fR on the \fIconnect_evd\fR of +the local Endpoint. It can be caused by the active side timeout expiration, +transport error, or any other reason. If Connection is not established, +Endpoint transitions into Disconnected state and all posted Recv DTOs are +flushed to its \fIrecv_evd_handle\fR. +.sp +.LP +This operation, if successful, also destroys the Connection Request instance. +Use of the handle of the destroyed \fIcr_handle\fR in any consequent operation +fails. +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBDAT_SUCCESS\fR\fR +.ad +.RS 25n +.rt +The operation was successful. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_HANDLE\fR\fR +.ad +.RS 25n +.rt +The \fIcr_handle\fR or \fIep_handle\fR parameter is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_PARAMETER\fR\fR +.ad +.RS 25n +.rt +The \fIprivate_data_size\fR or \fIprivate_data\fR parameter is invalid, out of +range, or a combination of parameters was invalid +.RE + +.SH USAGE +.sp +.LP +Consumers should be aware that Connection establishment might fail in the +following cases: If the accepting Endpoint has an outstanding RDMA Read +outgoing attribute larger than the requesting remote Endpoint or outstanding +RDMA Read incoming attribute, or if the outstanding RDMA Read incoming +attribute is smaller than the requesting remote Endpoint or outstanding RDMA +Read outgoing attribute. +.sp +.LP +Consumers should set the accepting Endpoint RDMA Reads as the target (incoming) +to a number larger than or equal to the remote Endpoint RDMA Read outstanding +as the originator (outgoing), and the accepting Endpoint RDMA Reads as the +originator to a number smaller than or equal to the remote Endpoint RDMA Read +outstanding as the target. DAT API does not define a protocol on how remote +peers exchange Endpoint attributes. The exchange of outstanding RDMA Read +incoming and outgoing attributes of EPs is left to the Consumer ULP. Consumer +can use Private Data for it. +.sp +.LP +If the Consumer does not care about posting RDMA Read operations or remote RDMA +Read operations on the connection, it can set the two outstanding RDMA Read +attribute values to 0. +.sp +.LP +If the Consumer does not set the two outstanding RDMA Read attributes of the +Endpoint, the Provider is free to pick up any value for default. The Provider +can change these default values during connection setup. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard: uDAPL, 1.1, 1.2 +_ +MT-LevelUnsafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBlibdat\fR(3LIB), \fBattributes\fR(5) diff --git a/usr/src/man/man3dat/dat_cr_handoff.3dat b/usr/src/man/man3dat/dat_cr_handoff.3dat new file mode 100644 index 0000000000..8211804dd4 --- /dev/null +++ b/usr/src/man/man3dat/dat_cr_handoff.3dat @@ -0,0 +1,113 @@ +'\" te +.\" This manual page is derived from the DAT/uDAPL 1.2 specification. +.\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH dat_cr_handoff 3DAT "16 Jul 2004" "SunOS 5.11" "Direct Access Transport Library Functions" +.SH NAME +dat_cr_handoff \- hand off the Connection Request to another Service Point +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ldat\fR [ \fIlibrary\fR\&.\|.\|. ] +#include <\fBdat/udat.h\fR> + +DAT_RETURN + dat_cr_handoff ( + IN DAT_CR_HANDLE cr_handle, + IN DAT_CONN_QUAL handoff + ) +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIcr_handle\fR\fR +.ad +.RS 13n +.rt +Handle to an instance of a Connection Request that the Consumer is handing off. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIhandoff\fR\fR +.ad +.RS 13n +.rt +Indicator of another Connection Qualifier on the same IA to which this +Connection Request should be handed off. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBdat_cr_handoff()\fR function hands off the Connection Request to another +Service Point specified by the Connection Qualifier \fIhandoff\fR. +.sp +.LP +The operation is synchronous. This operation also destroys the Connection +Request instance. Use of the handle of the destroyed Connection Request in any +consequent operation fails. +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBDAT_SUCCESS\fR\fR +.ad +.RS 25n +.rt +The operation was successful. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_HANDLE\fR\fR +.ad +.RS 25n +.rt +The \fIcr_handle\fR parameter is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_PARAMETER\fR\fR +.ad +.RS 25n +.rt +The \fIhandoff\fR parameter is invalid. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard: uDAPL, 1.1, 1.2 +_ +MT-LevelUnsafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBlibdat\fR(3LIB), \fBattributes\fR(5) diff --git a/usr/src/man/man3dat/dat_cr_query.3dat b/usr/src/man/man3dat/dat_cr_query.3dat new file mode 100644 index 0000000000..e5ed75e7bd --- /dev/null +++ b/usr/src/man/man3dat/dat_cr_query.3dat @@ -0,0 +1,136 @@ +'\" te +.\" This manual page is derived from the DAT/uDAPL 1.2 specification. +.\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH dat_cr_query 3DAT "16 Jul 2004" "SunOS 5.11" "Direct Access Transport Library Functions" +.SH NAME +dat_cr_query \- provide parameters of the Connection Request +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ldat\fR [ \fIlibrary\fR\&.\|.\|. ] +#include <\fBdat/udat.h\fR> + +DAT_RETURN + dat_cr_query ( + IN DAT_CR_HANDLE cr_handle, + IN DAT_CR_PARAM_MASK cr_param_mask, + OUT DAT_CR_PARAM *cr_param + ) +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIcr_handle\fR\fR +.ad +.RS 17n +.rt +Handle for an instance of a Connection Request. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcr_param_mask\fR\fR +.ad +.RS 17n +.rt +Mask for Connection Request parameters. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcr_param\fR\fR +.ad +.RS 17n +.rt +Pointer to a Consumer-allocated structure that the Provider fills for +Consumer-requested parameters. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBdat_cr_query()\fR function provides to the Consumer parameters of the +Connection Request. The Consumer passes in a pointer to the Consumer-allocated +structures for Connection Request parameters that the Provider fills. +.sp +.LP +The \fIcr_param_mask\fR parameter allows Consumers to specify which parameters +to query. The Provider returns values for \fIcr_param_mask\fR requested +parameters. The Provider can return values for any other parameters. +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBDAT_SUCCESS\fR\fR +.ad +.RS 25n +.rt +The operation was successful +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_HANDLE\fR\fR +.ad +.RS 25n +.rt +The \fIcr_handle\fR handle is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_PARAMETER\fR\fR +.ad +.RS 25n +.rt +The \fIcr_param_mask\fR parameter is invalid. +.RE + +.SH USAGE +.sp +.LP +The Consumer uses \fBdat_cr_query()\fR to get information about requesting a +remote Endpoint as well as a local Endpoint if it was allocated by the Provider +for the arrived Connection Request. The local Endpoint is created if the +Consumer used PSP with \fBDAT_PSP_PROVIDER\fR as the value for \fIpsp_flags\fR. +For the remote Endpoint, \fBdat_cr_query()\fR provides \fIremote_ia_address\fR +and \fIremote_port_qual\fR. It also provides remote \fIpeer private_data\fR and +its size. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard: uDAPL, 1.1, 1.2 +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBlibdat\fR(3LIB), \fBattributes\fR(5) diff --git a/usr/src/man/man3dat/dat_cr_reject.3dat b/usr/src/man/man3dat/dat_cr_reject.3dat new file mode 100644 index 0000000000..f76fb1e3ca --- /dev/null +++ b/usr/src/man/man3dat/dat_cr_reject.3dat @@ -0,0 +1,95 @@ +'\" te +.\" This manual page is derived from the DAT/uDAPL 1.2 specification. +.\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH dat_cr_reject 3DAT "16 Jul 2004" "SunOS 5.11" "Direct Access Transport Library Functions" +.SH NAME +dat_cr_reject \- reject a Connection Request from the Active remote side +requesting Endpoint +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ldat\fR [ \fIlibrary\fR\&.\|.\|. ] +#include <\fBdat/udat.h\fR> + +DAT_RETURN + dat_cr_reject ( + IN DAT_CR_HANDLE cr_handle + ) +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIcr_handle\fR\fR +.ad +.RS 13n +.rt +Handle to an instance of a Connection Request that the Consumer is rejecting. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBdat_cr_reject()\fR function rejects a Connection Request from the Active +remote side requesting Endpoint. If the Provider passed a local Endpoint into a +Consumer for the Public Service Point-created Connection Request, that Endpoint +reverts to Provider Control. The behavior of an operation on that Endpoint is +undefined. The local Endpoint that the Consumer provided for Reserved Service +Point reverts to Consumer control, and the Consumer is free to use in any way +it wants. +.sp +.LP +The operation is synchronous. This operation also destroys the Connection +Request instance. Use of the handle of the destroyed Connection Request in any +consequent operation fails. +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBDAT_SUCCESS\fR\fR +.ad +.RS 22n +.rt +The operation was successful. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_HANDLE\fR\fR +.ad +.RS 22n +.rt +The \fIcr_handle\fR parameter is invalid. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard: uDAPL, 1.1, 1.2 +_ +MT-LevelUnsafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBlibdat\fR(3LIB), \fBattributes\fR(5) diff --git a/usr/src/man/man3dat/dat_ep_connect.3dat b/usr/src/man/man3dat/dat_ep_connect.3dat new file mode 100644 index 0000000000..79d4f8dcda --- /dev/null +++ b/usr/src/man/man3dat/dat_ep_connect.3dat @@ -0,0 +1,336 @@ +'\" te +.\" This manual page is derived from the DAT/uDAPL 1.2 specification. +.\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH dat_ep_connect 3DAT "16 Jul 2004" "SunOS 5.11" "Direct Access Transport Library Functions" +.SH NAME +dat_ep_connect \- establish a connection between the local Endpoint and a +remote Endpoint +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ldat\fR [ \fIlibrary\fR\&.\|.\|. ] +#include <\fBdat/udat.h\fR> + +DAT_RETURN + dat_ep_connect ( + IN DAT_EP_HANDLE ep_handle, + IN DAT_IA_ADDRESS_PTR remote_ia_address, + IN DAT_CONN_QUAL remote_conn_qual, + IN DAT_TIMEOUT timeout, + IN DAT_COUNT private_data_size, + IN const DAT_PVOID private_data, + IN DAT_QOS qos, + IN DAT_CONNECT_FLAGS connect_flags + ) +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIep_handle\fR\fR +.ad +.RS 21n +.rt +Handle for an instance of an Endpoint. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIremote_ia_address\fR\fR +.ad +.RS 21n +.rt +The Address of the remote IA to which an Endpoint is requesting a connection. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIremote_conn_qual\fR\fR +.ad +.RS 21n +.rt +Connection Qualifier of the remote IA from which an Endpoint requests a +connection. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fItimeout\fR\fR +.ad +.RS 21n +.rt +Duration of time, in microseconds, that a Consumer waits for Connection +establishment. The value of \fBDAT_TIMEOUT_INFINITE\fR represents no timeout, +indefinite wait. Values must be positive. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIprivate_data_size\fR\fR +.ad +.RS 21n +.rt +Size of the \fIprivate_data\fR. Must be nonnegative. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIprivate_data\fR\fR +.ad +.RS 21n +.rt +Pointer to the private data that should be provided to the remote Consumer as +part of the Connection Request. If \fIprivate_data_size\fR is zero, then +\fIprivate_data\fR can be \fINULL\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIqos\fR\fR +.ad +.RS 21n +.rt +Requested quality of service of the connection. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIconnect_flags\fR\fR +.ad +.RS 21n +.rt +Flags for the requested connection. If the least significant bit of +\fBDAT_MULTIPATH_FLAG\fR is 0, the Consumer does not request multipathing. If +the least significant bit of \fBDAT__MULTIPATH_FLAG\fR is 1, the Consumer +requests multipathing. The default value is \fBDAT_CONNECT_DEFAULT_FLAG\fR, +which is 0. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBdat_ep_connect()\fR function requests that a connection be established +between the local Endpoint and a remote Endpoint. This operation is used by the +active/client side Consumer of the Connection establishment model. The remote +Endpoint is identified by Remote IA and Remote Connection Qualifier. +.sp +.LP +As part of the successful completion of this operation, the local Endpoint is +bound to a Port Qualifier of the local IA. The Port Qualifier is passed to the +remote side of the requested connection and is available to the remote Consumer +in the Connection Request of the \fBDAT_CONNECTION_REQUEST_EVENT\fR. +.sp +.LP +The Consumer-provided \fIprivate_data\fR is passed to the remote side and is +provided to the remote Consumer in the Connection Request. Consumers can +encapsulate any local Endpoint attributes that remote Consumers need to know as +part of an upper-level protocol. Providers can also provide a Provider on the +remote side any local Endpoint attributes and Transport-specific information +needed for Connection establishment by the Transport. +.sp +.LP +Upon successful completion of this operation, the local Endpoint is transferred +into \fBDAT_EP_STATE_ACTIVE_CONNECTION_PENDING\fR. +.sp +.LP +Consumers can request a specific value of \fIqos\fR. The Provider specifies +which quality of service it supports in documentation and in the Provider +attributes. If the local Provider or Transport does not support the requested +\fIqos\fR, the operation fails and \fBDAT_MODEL_NOT_SUPPORTED\fR is returned +synchronously. If the remote Provider does not support the requested \fIqos\fR, +the local Endpoint is automatically transitioned into the +\fBDAT_EP_STATE_DISCONNECTED\fR state, the connection is not established, and +the event returned on the \fIconnect_evd_handle\fR is +\fBDAT_CONNECTION_EVENT_NON_PEER_REJECTED\fR. The same +\fBDAT_CONNECTION_EVENT_NON_PEER_REJECTED\fR event is returned if the +connection cannot be established for all reasons of not establishing the +connection, except timeout, remote host not reachable, and remote peer reject. +For example, remote Consumer is not listening on the requested Connection +Qualifier, Backlog of the requested Service Point is full, and Transport +errors. In this case, the local Endpoint is automatically transitioned into +\fBDAT_EP_STATE_DISCONNECTED\fR state. +.sp +.LP +The acceptance of the requested connection by the remote Consumer is reported +to the local Consumer through a \fBDAT_CONNECTION_EVENT_ESTABLISHED\fR event on +the \fIconnect_evd_handle\fR of the local Endpoint and the local Endpoint is +automatically transitioned into a \fBDAT_EP_STATE_CONNECTED\fR state. +.sp +.LP +The rejection of the connection by the remote Consumer is reported to the local +Consumer through a \fBDAT_CONNECTION_EVENT_PEER_REJECTED\fR event on the +\fIconnect_evd_handle\fR of the local Endpoint and the local Endpoint is +automatically transitioned into a \fBDAT_EP_STATE_DISCONNECTED\fR state. +.sp +.LP +When the Provider cannot reach the remote host or the remote host does not +respond within the Consumer requested Timeout, a +\fBDAT_CONNECTION_EVENT_UNREACHABLE\fR event is generated on the +\fIconnect_evd_handle\fR of the Endpoint. The Endpoint transitions into a +\fBDAT_EP_STATE_DISCONNECTED\fR state. +.sp +.LP +If the Provider can locally determine that the \fIremote_ia_address\fR is +invalid, or that the remote_ia_address cannot be converted to a +Transport-specific address, the operation can fail synchronously with a +\fBDAT_INVALID_ADDRESS\fR return. +.sp +.LP +The local Endpoint is automatically transitioned into a +\fBDAT_EP_STATE_CONNECTED\fR state when a Connection Request accepted by the +remote Consumer and the Provider completes the Transport-specific Connection +establishment. The local Consumer is notified of the established connection +through a \fBDAT_CONNECTION_EVENT_ESTABLISHED\fR event on the +\fIconnect_evd_handle\fR of the local Endpoint. +.sp +.LP +When the \fItimeout\fR expired prior to completion of the Connection +establishment, the local Endpoint is automatically transitioned into a +\fBDAT_EP_STATE_DISCONNECTED\fR state and the local Consumer through a +\fBDAT_CONNECTION_EVENT_TIMED_OUT\fR event on the \fIconnect_evd_handle\fR of +the local Endpoint. +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBDAT_SUCCESS\fR\fR +.ad +.RS 30n +.rt +The operation was successful. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INSUFFICIENT_RESOURCES\fR\fR +.ad +.RS 30n +.rt +The operation failed due to resource limitations. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_PARAMETER\fR\fR +.ad +.RS 30n +.rt +Invalid parameter. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_ADDRESS\fR\fR +.ad +.RS 30n +.rt +Invalid address. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_HANDLE\fR\fR +.ad +.RS 30n +.rt +Invalid DAT handle; Invalid Endpoint handle. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_STATE\fR\fR +.ad +.RS 30n +.rt +Parameter in an invalid state. Endpoint was not in +\fBDAT_EP_STATE_UNCONNECTED\fR state. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_MODEL_NOT_SUPPORTED\fR\fR +.ad +.RS 30n +.rt +The requested Model was not supported by the Provider. For example, the +requested qos was not supported by the local Provider. +.RE + +.SH USAGE +.sp +.LP +It is up to the Consumer to negotiate outstanding RDMA Read incoming and +outgoing with a remote peer. The outstanding RDMA Read outgoing attribute +should be smaller than the remote Endpoint outstanding RDMA Read incoming +attribute. If this is not the case, Connection establishment might fail. +.sp +.LP +DAT API does not define a protocol on how remote peers exchange Endpoint +attributes. The exchange of outstanding RDMA Read incoming and outgoing +attributes of EPs is left to the Consumer ULP. The Consumer can use Private +Data for it. +.sp +.LP +If the Consumer does not care about posting RDMA Read operations or remote RDMA +Read operations on the connection, it can set the two outstanding RDMA Read +attribute values to 0. +.sp +.LP +If the Consumer does not set the two outstanding RDMA Read attributes of the +Endpoint, the Provider is free to pick up any value for default. The Provider +is allowed to change these default values during connection setup. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard: uDAPL, 1.1, 1.2 +_ +MT-LevelUnsafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBlibdat\fR(3LIB), \fBattributes\fR(5) diff --git a/usr/src/man/man3dat/dat_ep_create.3dat b/usr/src/man/man3dat/dat_ep_create.3dat new file mode 100644 index 0000000000..8dc9d3f4da --- /dev/null +++ b/usr/src/man/man3dat/dat_ep_create.3dat @@ -0,0 +1,318 @@ +'\" te +.\" This manual page is derived from the DAT/uDAPL 1.2 specification. +.\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH dat_ep_create 3DAT "16 Jul 2004" "SunOS 5.11" "Direct Access Transport Library Functions" +.SH NAME +dat_ep_create \- create an instance of an Endpoint +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ldat\fR [ \fIlibrary\fR\&.\|.\|. ] +#include <\fBdat/udat.h\fR> + +DAT_RETURN + dat_ep_create ( + IN DAT_IA_HANDLE ia_handle, + IN DAT_PZ_HANDLE pz_handle, + IN DAT_EVD_HANDLE recv_evd_handle, + IN DAT_EVD_HANDLE request_evd_handle, + IN DAT_EVD_HANDLE connect_evd_handle, + IN DAT_EP_ATTR *ep_attributes, + OUT DAT_EP_HANDLE *ep_handle + ) +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIia_handle\fR\fR +.ad +.RS 22n +.rt +Handle for an open instance of the IA to which the created Endpoint belongs. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIpz_handle\fR\fR +.ad +.RS 22n +.rt +Handle for an instance of the Protection Zone. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIrecv_evd_handle\fR\fR +.ad +.RS 22n +.rt +Handle for the Event Dispatcher where events for completions of incoming +(receive) DTOs are reported. \fBDAT_HANDLE_NULL\fR specifies that the Consumer +is not interested in events for completions of receives. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIrequest_evd_handle\fR\fR +.ad +.RS 22n +.rt +Handle for the Event Dispatcher where events for completions of outgoing (Send, +RDMA Write, RDMA Read, and RMR Bind) DTOs are reported. \fBDAT_HANDLE_NULL\fR +specifies that the Consumer is not interested in events for completions of +requests. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIconnect_evd_handle\fR\fR +.ad +.RS 22n +.rt +Handle for the Event Dispatcher where Connection events are reported. +\fBDAT_HANDLE_NULL\fR specifies that the Consumer is not interested in +connection events for now. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIep_attributes\fR\fR +.ad +.RS 22n +.rt +Pointer to a structure that contains Consumer-requested Endpoint attributes. +Can be \fINULL\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIep_handle\fR\fR +.ad +.RS 22n +.rt +Handle for the created instance of an Endpoint. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBdat_ep_create()\fR function creates an instance of an Endpoint that is +provided to the Consumer as \fIep_handle\fR. The value of \fIep_handle\fR is +not defined if the \fBDAT_RETURN\fR is not \fBDAT_SUCCESS\fR. +.sp +.LP +The Endpoint is created in the Unconnected state. +.sp +.LP +Protection Zone \fIpz_handle\fR allows Consumers to control what local memory +the Endpoint can access for DTOs and what memory remote RDMA operations can +access over the connection of a created Endpoint. Only memory referred to by +LMRs and RMRs that match the Endpoint Protection Zone can be accessed by the +Endpoint. +.sp +.LP +The \fIrecv_evd_handle\fR and \fIrequest_evd_handle\fR parameters are Event +Dispatcher instances where the Consumer collects completion notifications of +DTOs. Completions of Receive DTOs are reported in \fIrecv_evd_handle\fR Event +Dispatcher, and completions of Send, RDMA Read, and RDMA Write DTOs are +reported in \fIrequest_evd_handle\fR Event Dispatcher. All completion +notifications of RMR bindings are reported to a Consumer in +\fIrequest_evd_handle\fR Event Dispatcher. +.sp +.LP +All Connection events for the connected Endpoint are reported to the Consumer +through \fIconnect_evd_handle\fR Event Dispatcher. +.sp +.LP +The \fIep_attributes\fR parameter specifies the initial attributes of the +created Endpoint. If the Consumer specifies \fINULL\fR, the Provider fills it +with its default Endpoint attributes. The Consumer might not be able to do any +posts to the Endpoint or use the Endpoint in connection establishment until +certain Endpoint attributes are set. Maximum Message Size and Maximum Recv DTOs +are examples of such attributes. +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBDAT_SUCCESS\fR\fR +.ad +.RS 30n +.rt +The operation was successful. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INSUFFICIENT_RESOURCES\fR\fR +.ad +.RS 30n +.rt +The operation failed due to resource limitations. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_HANDLE\fR\fR +.ad +.RS 30n +.rt +Invalid DAT handle. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_PARAMETER\fR\fR +.ad +.RS 30n +.rt +Invalid parameter. One of the requested EP parameters or attributes was invalid +or a combination of attributes or parameters is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_MODEL_NOT_SUPPORTED\fR\fR +.ad +.RS 30n +.rt +The requested Provider Model was not supported. +.RE + +.SH USAGE +.sp +.LP +The Consumer creates an Endpoint prior to the establishment of a connection. +The created Endpoint is in \fBDAT_EP_STATE_UNCONNECTED\fR. Consumers can do the +following: +.RS +4 +.TP +1. +Request a connection on the Endpoint through \fBdat_ep_connect\fR(3DAT) or +\fBdat_ep_dup_connect\fR(3DAT) for the active side of the connection model. +.RE +.RS +4 +.TP +2. +Associate the Endpoint with the Pending Connection Request that does not +have an associated local Endpoint for accepting the Pending Connection Request +for the passive/server side of the connection model. +.RE +.RS +4 +.TP +3. +Create a Reserved Service Point with the Endpoint for the passive/server +side of the connection model. Upon arrival of a Connection Request on the +Service Point, the Consumer accepts the Pending Connection Request that has the +Endpoint associated with it +.RE +.sp +.LP +The Consumer cannot specify a \fIrequest_evd_handle\fR (\fIrecv_evd_handle\fR) +with Request Completion Flags (Recv Completion Flags) that do not match the +other Endpoint Completion Flags for the DTO/RMR completion streams that use the +same EVD. If \fIrequest_evd_handle\fR (\fIrecv_evd_handle\fR) is used for an +EVD that is fed by any event stream other than DTO or RMR completion event +streams, only \fBDAT_COMPLETION_THRESHOLD\fR is valid for Request/Recv +Completion Flags for the Endpoint completion streams that use that EVD. If +\fIrequest_evd_handle\fR (\fIrecv_evd_handle\fR) is used for request (recv) +completions of an Endpoint whose associated Request (Recv) Completion Flag +attribute is \fBDAT_COMPLETION_UNSIGNALLED_FLAG\fR, the Request Completion +Flags and Recv Completion Flags for all Endpoint completion streams that use +the EVD must specify the same. Analogously, if \fIrecv_evd_handle\fR is used +for recv completions of an Endpoint whose associated Recv Completion Flags +attribute is \fBDAT_COMPLETION_SOLICITED_WAIT\fR, the Recv Completion Flags for +all Endpoint Recv completion streams that use the same EVD must specify the +same Recv Completion Flags attribute value and the EVD cannot be used for any +other event stream types. +.sp +.LP +If EP is created with \fINULL\fR attributes, Provider can fill them with its +own default values. The Consumer should not rely on the Provider-filled +attribute defaults, especially for portable applications. The Consumer cannot +do any operations on the created Endpoint except for \fBdat_ep_query\fR(3DAT), +\fBdat_ep_get_status\fR(3DAT), \fBdat_ep_modify\fR(3DAT), and +\fBdat_ep_free\fR(3DAT), depending on the values that the Provider picks. +.sp +.LP +The Provider is encouraged to pick up reasonable defaults because unreasonable +values might restrict Consumers to the \fBdat_ep_query()\fR, +\fBdat_ep_get_status()\fR, \fBdat_ep_modify()\fR, and \fBdat_ep_free()\fR +operations. The Consumer should check what values the Provider picked up for +the attributes. It is especially important to make sure that the number of +posted operations is not too large to avoid EVD overflow. Depending on the +values picked up by the Provider, the Consumer might not be able to do any RDMA +operations; it might only be able to send or receive messages of very small +sizes, or it might not be able to have more than one segment in a buffer. +Before doing any operations, except the ones listed above, the Consumer can +configure the Endpoint using \fBdat_ep_modify()\fR to the attributes they want. +.sp +.LP +One reason the Consumer might still want to create an Endpoint with Null +attributes is for the Passive side of the connection establishment, where the +Consumer sets up Endpoint attributes based on the connection request of the +remote side. +.sp +.LP +Consumers might want to create Endpoints with \fINULL\fR attributes if Endpoint +properties are negotiated as part the Consumer connection establishment +protocol. +.sp +.LP +Consumers that create Endpoints with Provider default attributes should always +verify that the Provider default attributes meet their application's +requirements with regard to the number of request/receive DTOs that can be +posted, maximum message sizes, maximum request/receive IOV sizes, and maximum +RDMA sizes. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard: uDAPL, 1.1, 1.2 +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBdat_ep_connect\fR(3DAT), \fBdat_ep_dup_connect\fR(3DAT), +\fBdat_ep_free\fR(3DAT), \fBdat_ep_get_status\fR(3DAT), +\fBdat_ep_modify\fR(3DAT), \fBdat_ep_query\fR(3DAT), \fBlibdat\fR(3LIB), +\fBattributes\fR(5) diff --git a/usr/src/man/man3dat/dat_ep_create_with_srq.3dat b/usr/src/man/man3dat/dat_ep_create_with_srq.3dat new file mode 100644 index 0000000000..8ea4af416f --- /dev/null +++ b/usr/src/man/man3dat/dat_ep_create_with_srq.3dat @@ -0,0 +1,422 @@ +'\" te +.\" This manual page is derived from the DAT/uDAPL 1.2 specification. +.\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH dat_ep_create_with_srq 3DAT "16 Jul 2004" "SunOS 5.11" "Direct Access Transport Library Functions" +.SH NAME +dat_ep_create_with_srq \- create an instance of End Point with Shared Receive +Queue +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ldat\fR [ \fIlibrary\fR\&.\|.\|. ] +#include <\fBdat/udat.h\fR> + +DAT_RETURN + dat_ep_create_with_srq ( + IN DAT_IA_HANDLE ia_handle, + IN DAT_PZ_HANDLE pz_handle, + IN DAT_EVD_HANDLE recv_evd_handle, + IN DAT_EVD_HANDLE request_evd_handle, + IN DAT_EVD_HANDLE connect_evd_handle, + IN DAT_SRQ_HANDLE srq_handle, + IN DAT_EP_ATTR *ep_attributes, + OUT DAT_EP_HANDLE *ep_handle + ) +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIia_handle\fR\fR +.ad +.RS 22n +.rt +Handle for an open instance of the IA to which the created Endpoint belongs. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIpz_handle\fR\fR +.ad +.RS 22n +.rt +Handle for an instance of the Protection Zone. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIrecv_evd_handle\fR\fR +.ad +.RS 22n +.rt +Handle for the Event Dispatcher where events for completions of incoming +(receive) DTOs are reported. \fBDAT_HANDLE_NULL\fR specifies that the Consumer +is not interested in events for completions of receives. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIrequest_evd_handle\fR\fR +.ad +.RS 22n +.rt +Handle for the Event Dispatcher where events for completions of outgoing (Send, +RDMA Write, RDMA Read, and RMR Bind) DTOs are reported. \fBDAT_HANDLE_NULL\fR +specifies that the Consumer is not interested in events for completions of +requests. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIconnect_evd_handle\fR\fR +.ad +.RS 22n +.rt +Handle for the Event Dispatcher where Connection events are reported. +\fBDAT_HANDLE_NULL\fR specifies that the Consumer is not interested in +connection events for now. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIsrq_handle\fR\fR +.ad +.RS 22n +.rt +Handle for an instance of the Shared Receive Queue. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIep_attributes\fR\fR +.ad +.RS 22n +.rt +Pointer to a structure that contains Consumer-requested Endpoint attributes. +Cannot be \fINULL\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIep_handle\fR\fR +.ad +.RS 22n +.rt +Handle for the created instance of an Endpoint. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBdat_ep_create_with_srq()\fR function creates an instance of an Endpoint +that is using SRQ for Recv buffers is provided to the Consumer as +\fIep_handle\fR. The value of \fIep_handle\fR is not defined if the +\fBDAT_RETURN\fR is not \fBDAT_SUCCESS\fR. +.sp +.LP +The Endpoint is created in the Unconnected state. +.sp +.LP +Protection Zone \fIpz_handle\fR allows Consumers to control what local memory +the Endpoint can access for DTOs except Recv and what memory remote RDMA +operations can access over the connection of a created Endpoint. Only memory +referred to by LMRs and RMRs that match the Endpoint Protection Zone can be +accessed by the Endpoint. The Recv DTO buffers PZ must match the SRQ PZ. The +SRQ PZ might or might not be the same as the EP one. Check Provider attribute +for the support of different PZs between SRQ and its EPs. +.sp +.LP +The \fIrecv_evd_handle\fR and \fIrequest_evd_handle\fR arguments are Event +Dispatcher instances where the Consumer collects completion notifications of +DTOs. Completions of Receive DTOs are reported in \fIrecv_evd_handle\fR Event +Dispatcher, and completions of Send, RDMA Read, and RDMA Write DTOs are +reported in \fIrequest_evd_handle\fR Event Dispatcher. All completion +notifications of RMR bindings are reported to a Consumer in +\fIrequest_evd_handle\fR Event Dispatcher. +.sp +.LP +All Connection events for the connected Endpoint are reported to the Consumer +through \fIconnect_evd_handle\fR Event Dispatcher. +.sp +.LP +Shared Receive Queue \fIsrq_handle\fR specifies where the EP will dequeue Recv +DTO buffers. +.sp +.LP +The created EP can be reset. The relationship between SRQ and EP is not +effected by \fBdat_ep_reset\fR(3DAT). +.sp +.LP +SRQ can not be disassociated or replaced from created EP. The only way to +disassociate SRQ from EP is to destroy EP. +.sp +.LP +Receive buffers cannot be posted to the created Endpoint. Receive buffers must +be posted to the SRQ to be used for the created Endpoint. +.sp +.LP +The ep_attributes parameter specifies the initial attributes of the created +Endpoint. Consumer can not specify \fINULL\fR for \fIep_attributes\fR but can +specify values only for the parameters needed and default for the rest. +.sp +.LP +For \fImax_request_dtos\fR and \fImax_request_iov\fR, the created Endpoint will +have at least the Consumer requested values but might have larger values. +Consumer can query the created Endpoint to find out the actual values for these +attributes. Created Endpoint has the exact Consumer requested values for +\fImax_recv_dtos\fR, \fImax_message_size\fR, \fImax_rdma_size\fR, \fImax_ +rdma_read_in\fR, and \fImax_rdma_read_out\fR. For all other attributes, except +\fImax_recv_iov\fR that is ignored, the created Endpoint has the exact values +requested by Consumer. If Provider cannot satisfy the Consumer requested +attribute values the operation fails. +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBDAT_SUCCESS\fR\fR +.ad +.RS 30n +.rt +The operation was successful. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INSUFFICIENT_RESOURCES\fR\fR +.ad +.RS 30n +.rt +The operation failed due to resource limitations. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_HANDLE\fR\fR +.ad +.RS 30n +.rt +Invalid DAT handle. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_PARAMETER\fR\fR +.ad +.RS 30n +.rt +Invalid parameter. One of the requested EP parameters or attributes was invalid +or a combination of attributes or parameters is invalid. For example, +\fIpz_handle\fR specified does not match the one for SRQ or the requested +maximum RDMA Read IOV exceeds IA capabilities.. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_MODEL_NOT_SUPPORTED\fR\fR +.ad +.RS 30n +.rt +The requested Provider Model was not supported. +.RE + +.SH USAGE +.sp +.LP +The Consumer creates an Endpoint prior to the establishment of a connection. +The created Endpoint is in \fBDAT_EP_STATE_UNCONNECTED\fR. Consumers can do the +following: +.RS +4 +.TP +1. +Request a connection on the Endpoint through \fBdat_ep_connect\fR(3DAT) or +\fBdat_ep_dup_connect\fR(3DAT) for the active side of the connection model. +.RE +.RS +4 +.TP +2. +Associate the Endpoint with the Pending Connection Request that does not +have an associated local Endpoint for accepting the Pending Connection Request +for the passive/server side of the con-nection model. +.RE +.RS +4 +.TP +3. +Create a Reserved Service Point with the Endpoint for the passive/server +side of the connection model. Upon arrival of a Connection Request on the +Service Point, the Consumer accepts the Pending Connection Request that has the +Endpoint associated with it. +.RE +.sp +.LP +The Consumer cannot specify a \fIrequest_evd_handle\fR (\fIrecv_evd_handle\fR) +with Request Completion Flags (Recv Completion Flags) that do not match the +other Endpoint Completion Flags for the DTO/RMR completion streams that use the +same EVD. If \fIrequest_evd_handle\fR (\fIrecv_evd_ handle\fR) is used for +request (recv) completions of an Endpoint whose associated Request (Recv) +Completion Flag attribute is \fBDAT_COMPLETION_UNSIGNALLED_FLAG\fR, the Request +Completion Flags and Recv Completion Flags for all Endpoint completion streams +that use the EVD must specify the same. By definition, completions of all Recv +DTO posted to SRQ complete with Signal. Analogously, if \fIrecv_evd_handle\fR +is used for recv completions of an Endpoint whose associated Recv Completion +Flag attribute is \fBDAT_COMPLETION_SOLICITED_WAIT\fR, the Recv Completion +Flags for all Endpoint Recv completion streams that use the same EVD must +specify the same Recv Completion Flags attribute value and the EVD cannot be +used for any other event stream types. If \fIrecv_evd_handle\fR is used for +Recv completions of an Endpoint that uses SRQ and whose Recv Completion Flag +attribute is \fBDAT_COMPLETION_EVD_THRESHOLD\fR then all Endpoint DTO +completion streams (request and/or recv completion streams) that use that +\fIrecv_evd_handle\fR must specify \fBDAT_COMPLETION_EVD_THRESHOLD\fR. Other +event stream types can also use the same EVD. +.sp +.LP +Consumers might want to use \fBDAT_COMPLETION_UNSIGNALLED_FLAG\fR for Request +and/or Recv completions when they control locally with posted DTO/RMR +completion flag (not needed for Recv posted to SRQ) whether posted DTO/RMR +completes with Signal or not. Consumers might want to use +\fBDAT_COMPLETION_SOLICITED_WAIT\fR for Recv completions when the remote sender +side control whether posted Recv competes with Signal or not or not. uDAPL +Consumers might want to use \fBDAT_COMPLETION_EVD_THRESHOLD\fR for Request +and/or Recv completions when they control waiter unblocking with the +\fIthreshold\fR parameter of the \fBdat_evd_wait\fR(3DAT). +.sp +.LP +Some Providers might restrict whether multiple EPs that share a SRQ can have +different Protection Zones. Check the \fIsrq_ep_pz_difference_support\fR +Provider attribute for it. +.sp +.LP +Consumers might want to have a different PZ between EP and SRQ. This allows +incoming RDMA operations to be specific to this EP PZ and not the same for all +EPs that share SRQ. This is critical for servers that supports multiple +independent clients. +.sp +.LP +The Provider is strongly encouraged to create an EP that is ready to be +connected. Any effects of previous connections or connection establishment +attempts on the underlying Transport-specific Endpoint to which the DAT +Endpoint is mapped to should be hidden from the Consumer. The methods described +below are examples: +.RS +4 +.TP +.ie t \(bu +.el o +The Provider does not create an underlying Transport Endpoint until the +Consumer is connecting the Endpoint or accepting a connection request on it. +This allows the Provider to accumulate Consumer requests for attribute settings +even for attributes that the underlying transport does not allow to change +after the Transport Endpoint is created. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +The Provider creates the underlying Transport Endpoint or chooses one from a +pool of Provider-controlled Transport Endpoints when the Consumer creates the +Endpoint. The Provider chooses the Transport Endpoint that is free from any +underlying internal attributes that might prevent the Endpoint from being +connected. For IB and IP, that means that the Endpoint is not in the TimeWait +state. Changing of some of the Endpoint attributes becomes hard and might +potentially require mapping the Endpoint to another underlying Transport +Endpoint that might not be feasible for all transports. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +The Provider allocates a Transport-specific Endpoint without worrying about +impact on it from previous connections or connection establishment attempts. +Hide the Transport-specific TimeWait state or CM timeout of the underlying +transport Endpoint within \fBdat_ep_connect\fR(3DAT), +\fBdat_ep_dup_connect\fR(3DAT), or \fBdat_cr_accept\fR(3DAT). On the Active +side of the connection establishment, if the remnants of a previous connection +for Transport-specific Endpoint can be hidden within the Timeout parameter, do +so. If not, generating \fBDAT_CONNECTION_ EVENT_NON_PEER_REJECTED\fR is an +option. For the Passive side, generating a +\fBDAT_CONNECTION_COMPLETION_ERROR\fR event locally, while sending a +non-peer-reject message to the active side, is a way of handling it. +.RE +.sp +.LP +Any transitions of an Endpoint into an Unconnected state can be handled +similarly. One transition from a Disconnected to an Unconnected state is a +special case. +.sp +.LP +For \fBdat_ep_reset\fR(3DAT), the Provider can hide any remnants of the +previous connection or failed connection establishment in the operation itself. +Because the operation is synchronous, the Provider can block in it until the +TimeWait state effect of the previous connection or connection setup is +expired, or until the Connection Manager timeout of an unsuccessful connection +establishment attempt is expired. Alternatively, the Provider can create a new +Endpoint for the Consumer that uses the same handle. +.sp +.LP +DAT Providers are required not to change any Consumer-specified Endpoint +attributes during connection establishment. If the Consumer does not specify an +attribute, the Provider can set it to its own default. Some EP attributes, +like outstanding RDMA Read incoming or outgoing, if not set up by the Consumer, +can be changed by Providers to establish connection. It is recommended that the +Provider pick the default for outstanding RDMA Read attributes as 0 if the +Consumer has not specified them. This ensures that connection establishment +does not fail due to insufficient outstanding RDMA Read resources, which is a +requirement for the Provider. +.sp +.LP +The Provider is not required to check for a mismatch between the maximum RDMA +Read IOV and maximum RDMA Read outgoing attributes, but is allowed to do so. In +the later case it is allowed to return \fBDAT_INVALID_ PARAMETER\fR when a +mismatch is detected. Provider must allocate resources to satisfy the +combination of these two EP attributes for local RDMA Read DTOs. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard: uDAPL, 1.2 +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBdat_ep_create\fR(3DAT), \fBdat_srq_create\fR(3DAT), +\fBdat_srq_free\fR(3DAT), \fBdat_srq_query\fR(3DAT), \fBlibdat\fR(3LIB), +\fBattributes\fR(5) diff --git a/usr/src/man/man3dat/dat_ep_disconnect.3dat b/usr/src/man/man3dat/dat_ep_disconnect.3dat new file mode 100644 index 0000000000..1a13bde5ae --- /dev/null +++ b/usr/src/man/man3dat/dat_ep_disconnect.3dat @@ -0,0 +1,212 @@ +'\" te +.\" This manual page is derived from the DAT/uDAPL 1.2 specification. +.\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH dat_ep_disconnect 3DAT "16 Jul 2004" "SunOS 5.11" "Direct Access Transport Library Functions" +.SH NAME +dat_ep_disconnect \- terminate a connection or a connection establishment +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ldat\fR [ \fIlibrary\fR\&.\|.\|. ] +#include <\fBdat/udat.h\fR> + +DAT_RETURN + dat_ep_disconnect ( + IN DAT_EP_HANDLE ep_handle, + IN DAT_CLOSE_FLAGS disconnect_flags + ) +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIep_handle\fR\fR +.ad +.RS 20n +.rt +Handle for an instance of Endpoint. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdisconnect_flags\fR\fR +.ad +.RS 20n +.rt +Flags for disconnect. Flag values are as follows: +.sp +.ne 2 +.mk +.na +\fB\fBDAT_CLOSE_ABRUPT_FLAG\fR\fR +.ad +.RS 27n +.rt +Abrupt close. This is the default value. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_CLOSE_GRACEFUL_FLAG\fR\fR +.ad +.RS 27n +.rt +Graceful close. +.RE + +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBdat_ep_disconnect()\fR function requests a termination of a connection +or connection establishment. This operation is used by the active/client or a +passive/server side Consumer of the connection model. +.sp +.LP +The \fIdisconnect_flags\fR parameter allows Consumers to specify whether they +want graceful or abrupt disconnect. Upon disconnect, all outstanding and +in-progress DTOs and RMR Binds must be completed. +.sp +.LP +For abrupt disconnect, all outstanding DTOs and RMR Binds are completed +unsuccessfully, and in-progress DTOs and RMR Binds can be completed +successfully or unsuccessfully. If an in-progress DTO is completed +unsuccessfully, all follow on in-progress DTOs in the same direction also must +be completed unsuccessfully. This order is presented to the Consumer through a +DTO completion Event Stream of the \fIrecv_evd_handle\fR and and +\fIrequest_evd_handle\fR of the Endpoint. +.sp +.LP +For graceful disconnect, all outstanding and in-progress request DTOs and RMR +Binds must try to be completed successfully first, before disconnect proceeds. +During that time, the local Endpoint is in a \fBDAT_EP_DISCONNECT_PENDING\fR +state. +.sp +.LP +The Consumer can call abrupt \fBdat_ep_disconnect()\fR when the local Endpoint +is in the \fBDAT_EP_DISCONNECT_PENDING\fR state. This causes the Endpoint to +transition into \fBDAT_EP_STATE_DISCONNECTED\fR without waiting for outstanding +and in-progress request DTOs and RMR Binds to successfully complete. The +graceful \fBdat_ep_disconnect()\fR call when the local Endpoint is in the +\fBDAT_EP_DISCONNECT_PENDING\fR state has no effect. +.sp +.LP +If the Endpoint is not in \fBDAT_EP_STATE_CONNECTED\fR, the semantic of the +operation is the same for graceful or abrupt \fIdisconnect_flags\fR value. +.sp +.LP +No new Send, RDMA Read, and RDMA Write DTOs, or RMR Binds can be posted to the +Endpoint when the local Endpoint is in the \fBDAT_EP_DISCONNECT_PENDING\fR +state. +.sp +.LP +The successful completion of the disconnect is reported to the Consumer through +a \fBDAT_CONNECTION_EVENT_DISCONNECTED\fR event on \fIconnect_evd_handle\fR of +the Endpoint. The Endpoint is automatically transitioned into a +\fBDAT_EP_STATE_DISCONNECTED\fR state upon successful asynchronous completion. +If the same EVD is used for \fIconnect_evd_handle\fR and any +\fIrecv_evd_handle\fR and request_evd_handle, all successful Completion events +of in-progress DTOs precede the Disconnect Completion event. +.sp +.LP +Disconnecting an unconnected Disconnected Endpoint is no-op. Disconnecting an +Endpoint in \fBDAT_EP_STATE_UNCONNECTED\fR, \fBDAT_EP_STATE_RESERVED\fR, +\fBDAT_EP_STATE_PASSIVE_CONNECTION_PENDING\fR, and +\fBDAT_EP_STATE_TENTATIVE_CONNECTION_PENDING\fR is disallowed. +.sp +.LP +Both abrupt and graceful disconnect of the Endpoint during connection +establishment, \fBDAT_EP_STATE_ACTIVE_CONNECTION_PENDING\fR and +\fBDAT_EP_STATE_COMPLETION_PENDING\fR, "aborts" the connection establishment +and transitions the local Endpoint into \fBDAT_EP_STATE_DISCONNECTED\fR. That +causes preposted Recv DTOs to be flushed to \fIrecv_evd_handle\fR. +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBDAT_SUCCESS\fR\fR +.ad +.RS 30n +.rt +The operation was successful. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_HANDLE\fR\fR +.ad +.RS 30n +.rt +The \fIep_handle\fR parameter is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INSUFFICIENT_RESOURCES\fR\fR +.ad +.RS 30n +.rt +The operation failed due to resource limitations. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_PARAMETER\fR\fR +.ad +.RS 30n +.rt +The \fIdisconnect_flags\fR parameter is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_STATE\fR\fR +.ad +.RS 30n +.rt +A parameter is in an invalid state. Endpoint is not in the valid state for +disconnect. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard: uDAPL, 1.1, 1.2 +_ +MT-Level Unsafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBlibdat\fR(3LIB), \fBattributes\fR(5) diff --git a/usr/src/man/man3dat/dat_ep_dup_connect.3dat b/usr/src/man/man3dat/dat_ep_dup_connect.3dat new file mode 100644 index 0000000000..6f58f3d514 --- /dev/null +++ b/usr/src/man/man3dat/dat_ep_dup_connect.3dat @@ -0,0 +1,294 @@ +'\" te +.\" This manual page is derived from the DAT/uDAPL 1.2 specification. +.\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH dat_ep_dup_connect 3DAT "16 Jul 2004" "SunOS 5.11" "Direct Access Transport Library Functions" +.SH NAME +dat_ep_dup_connect \- establish a connection between the local Endpoint and a +remote Endpoint +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ldat\fR [ \fIlibrary\fR\&.\|.\|. ] +#include <\fBdat/udat.h\fR> + +DAT_RETURN + dat_ep_dup_connect ( + IN DAT_EP_HANDLE ep_handle, + IN DAT_EP_HANDLE dup_ep_handle, + IN DAT_TIMEOUT timeout, + IN DAT_COUNT private_data_size, + IN const DAT_PVOID private_data, + IN DAT_QOS qos + ) +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIep_handle\fR\fR +.ad +.RS 21n +.rt +Handle for an instance of an Endpoint. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdup_ep_handle\fR\fR +.ad +.RS 21n +.rt +Connected local Endpoint that specifies a requested connection remote end. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fItimeout:\fR\fR +.ad +.RS 21n +.rt +Duration of time, in microseconds, that Consumers wait for Connection +establishment. The value of \fBDAT_TIMEOUT_INFINITE\fR represents no timeout, +indefinite wait. Values must be positive. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIprivate_data_size\fR\fR +.ad +.RS 21n +.rt +Size of \fIprivate_data\fR. Must be nonnegative. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIprivate_data\fR\fR +.ad +.RS 21n +.rt +Pointer to the private data that should be provided to the remote Consumer as +part of the Connection Request. If \fIprivate_data_size\fR is zero, then +\fIprivate_data\fR can be \fINULL\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIqos\fR\fR +.ad +.RS 21n +.rt +Requested Quality of Service of the connection. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBdat_ep_dup_connect()\fR function requests that a connection be +established between the local Endpoint and a remote Endpoint. This operation is +used by the active/client side Consumer of the connection model. The remote +Endpoint is identified by the \fIdup_ep_handle\fR. The remote end of the +requested connection shall be the same as the remote end of the +\fIdup_ep_handle\fR. This is equivalent to requesting a connection to the same +remote IA, Connection Qualifier, and \fIconnect_flags\fR as used for +establishing the connection on duplicated Endpoints and following the same +redirections. +.sp +.LP +Upon establishing the requested connection as part of the successful completion +of this operation, the local Endpoint is bound to a Port Qualifier of the local +IA. The Port Qualifier is passed to the remote side of the requested connection +and is available to the remote Consumer in the Connection Request of the +\fBDAT_CONNECTION_REQUEST_EVENT\fR. +.sp +.LP +The Consumer-provided \fIprivate_data\fR is passed to the remote side and is +provided to the remote Consumer in the Connection Request. Consumers can +encapsulate any local Endpoint attributes that remote Consumers need to know as +part of an upper-level protocol. Providers can also provide a Provider on the +remote side any local Endpoint attributes and Transport-specific information +needed for Connection establishment by the Transport. +.sp +.LP +Upon successful completion of this operation, the local Endpoint is transferred +into \fBDAT_EP_STATE_ACTIVE_CONNECTION_PENDING\fR. +.sp +.LP +Consumers can request a specific value of \fIqos\fR. The Provider specifies +which Quality of Service it supports in documentation and in the Provider +attributes. If the local Provider or Transport does not support the requested +\fIqos\fR, the operation fails and \fBDAT_MODEL_NOT_SUPPORTED\fR is returned +synchronously. If the remote Provider does not support the requested \fIqos\fR, +the local Endpoint is automatically transitioned into a +\fBDAT_EP_STATE_UNDISCONNECTED\fR state, the connection is not established, and +the event returned on the \fIconnect_evd_handle\fR is +\fBDAT_CONNECTION_EVENT_NON_PEER_REJECTED\fR. The same +\fBDAT_CONNECTION_EVENT_NON_PEER_REJECTED\fR event is returned if connection +cannot be established for all reasons for not establishing the connection, +except timeout, remote host not reachable, and remote peer reject. For example, +remote host is not reachable, remote Consumer is not listening on the requested +Connection Qualifier, Backlog of the requested Service Point is full, and +Transport errors. In this case, the local Endpoint is automatically +transitioned into a \fBDAT_EP_STATE_UNDISCONNECTED\fR state. +.sp +.LP +The acceptance of the requested connection by the remote Consumer is reported +to the local Consumer through a \fBDAT_CONNECTION_EVENT_ESTABLISHED\fR event on +the \fIconnect_evd_handle\fR of the local Endpoint. +.sp +.LP +The rejection of the connection by the remote Consumer is reported to the local +Consumer through a \fBDAT_CONNECTION_EVENT_PEER_REJECTED\fR event on the +\fIconnect_evd_handle\fR of the local Endpoint and the local Endpoint is +automatically transitioned into a \fBDAT_EP_STATE_UNDISCONNECTED\fR state. +.sp +.LP +When the Provider cannot reach the remote host or the remote host does not +respond within the Consumer-requested \fItimeout\fR, a +\fBDAT_CONNECTION_EVENT_UNREACHABLE\fR is generated on the +\fIconnect_evd_handle\fR of the Endpoint. The Endpoint transitions into a +\fBDAT_EP_STATE_DISCONNECTED\fR state. +.sp +.LP +The local Endpoint is automatically transitioned into a +\fBDAT_EP_STATE_CONNECTED\fR state when a Connection Request is accepted by the +remote Consumer and the Provider completes the Transport-specific Connection +establishment. The local Consumer is notified of the established connection +through a \fBDAT_CONNECTION_EVENT_ESTABLISHED\fR event on the +\fIconnect_evd_handle\fR of the local Endpoint. +.sp +.LP +When the \fItimeout\fR expired prior to completion of the Connection +establishment, the local Endpoint is automatically transitioned into a +\fBDAT_EP_STATE_UNDISCONNECTED\fR state and the local Consumer through a +\fBDAT_CONNECTION_EVENT_TIMED_OUT\fR event on the \fIconnect_evd_handle\fR of +the local Endpoint. +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBDAT_SUCCESS\fR\fR +.ad +.RS 30n +.rt +The operation was successful. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INSUFFICIENT_RESOURCES\fR\fR +.ad +.RS 30n +.rt +The operation failed due to resource limitations. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_PARAMETER\fR\fR +.ad +.RS 30n +.rt +Invalid parameter. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_HANDLE\fR\fR +.ad +.RS 30n +.rt +The \fIep_handle\fR or \fIdup_ep_handle\fR parameter is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_STATE\fR\fR +.ad +.RS 30n +.rt +A parameter is in an invalid state. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_MODEL_NOT_SUPPORTED\fR\fR +.ad +.RS 30n +.rt +The requested Model is not supported by the Provider. For example, requested +\fIqos\fR was not supported by the local Provider. +.RE + +.SH USAGE +.sp +.LP +It is up to the Consumer to negotiate outstanding RDMA Read incoming and +outgoing with a remote peer. The outstanding RDMA Read outgoing attribute +should be smaller than the remote Endpoint outstanding RDMA Read incoming +attribute. If this is not the case, connection establishment might fail. +.sp +.LP +DAT API does not define a protocol on how remote peers exchange Endpoint +attributes. The exchange of outstanding RDMA Read incoming and outgoing +attributes of EPs is left to the Consumer ULP. The Consumer can use Private +Data for it. +.sp +.LP +If the Consumer does not care about posting RDMA Read operations or remote RDMA +Read operations on the connection, it can set the two outstanding RDMA Read +attribute values to 0. +.sp +.LP +If the Consumer does not set the two outstanding RDMA Read attributes of the +Endpoint, the Provider is free to pick up any values as a default. The Provider +is allowed to change these default values during connection setup. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard: uDAPL, 1.1, 1.2 +_ +MT-LevelUnsafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBlibdat\fR(3LIB), \fBattributes\fR(5) diff --git a/usr/src/man/man3dat/dat_ep_free.3dat b/usr/src/man/man3dat/dat_ep_free.3dat new file mode 100644 index 0000000000..f92e4417d9 --- /dev/null +++ b/usr/src/man/man3dat/dat_ep_free.3dat @@ -0,0 +1,128 @@ +'\" te +.\" This manual page is derived from the DAT/uDAPL 1.2 specification. +.\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH dat_ep_free 3DAT "16 Jul 2004" "SunOS 5.11" "Direct Access Transport Library Functions" +.SH NAME +dat_ep_free \- destroy an instance of the Endpoint +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ldat\fR [ \fIlibrary\fR\&.\|.\|. ] +#include <\fBdat/udat.h\fR> + +DAT_RETURN + dat_ep_free ( + IN DAT_EP_HANDLE ep_handle + ) +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIep_handle\fR\fR +.ad +.RS 13n +.rt +Handle for an instance of the Endpoint. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBdat_ep_free()\fR function destroys an instance of the Endpoint. +.sp +.LP +The Endpoint can be destroyed in any Endpoint state except Reserved, Passive +Connection Pending, and Tentative Connection Pending. The destruction of the +Endpoint can also cause the destruction of DTOs and RMRs posted to the Endpoint +and not dequeued yet. This includes completions for all outstanding and +in-progress DTOs/RMRs. The Consumer must be ready for all completions that are +not dequeued yet either still being on the Endpoint \fIrecv_evd_handle\fR and +\fIrequest_evd_handle\fR or not being there. +.sp +.LP +The destruction of the Endpoint during connection setup aborts connection +establishment. +.sp +.LP +If the Endpoint is in the Reserved state, the Consumer shall first destroy the +associated Reserved Service Point that transitions the Endpoint into the +Unconnected state where the Endpoint can be destroyed. If the Endpoint is in +the Passive Connection Pending state, the Consumer shall first reject the +associated Connection Request that transitions the Endpoint into the +Unconnected state where the Endpoint can be destroyed. If the Endpoint is in +the Tentative Connection Pending state, the Consumer shall reject the +associated Connection Request that transitions the Endpoint back to Provider +control, and the Endpoint is destroyed as far as the Consumer is concerned. +.sp +.LP +The freeing of an Endpoint also destroys an Event Stream for each of the +associated Event Dispatchers. +.sp +.LP +Use of the handle of the destroyed Endpoint in any subsequent operation except +for the \fBdat_ep_free()\fR fails. +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBDAT_SUCCESS\fR\fR +.ad +.RS 22n +.rt +The operation was successful. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_HANDLE\fR\fR +.ad +.RS 22n +.rt +The \fIep_handle\fR parameter is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_STATE\fR\fR +.ad +.RS 22n +.rt +Parameter in an invalid state. The Endpoint is in \fBDAT_EP_STATE_RESERVED\fR, +\fBDAT_EP_STATE_PASSIVE_CONNECTION_PENDING\fR, or +\fBDAT_EP_STATE_TENTATIVE_CONNECTION_PENDING\fR. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard: uDAPL, 1.1, 1.2 +_ +MT-LevelUnsafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBlibdat\fR(3LIB), \fBattributes\fR(5) diff --git a/usr/src/man/man3dat/dat_ep_get_status.3dat b/usr/src/man/man3dat/dat_ep_get_status.3dat new file mode 100644 index 0000000000..44f18dc2ab --- /dev/null +++ b/usr/src/man/man3dat/dat_ep_get_status.3dat @@ -0,0 +1,146 @@ +'\" te +.\" This manual page is derived from the DAT/uDAPL 1.2 specification. +.\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH dat_ep_get_status 3DAT "16 Jul 2004" "SunOS 5.11" "Direct Access Transport Library Functions" +.SH NAME +dat_ep_get_status \- provide a quick snapshot of the Endpoint +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ldat\fR [ \fIlibrary\fR\&.\|.\|. ] +#include <\fBdat/udat.h\fR> + +DAT_RETURN + dat_ep_get_status ( + IN DAT_EP_HANDLE ep_handle, + OUT DAT_EP_STATE *ep_state, + OUT DAT_BOOLEAN *recv_idle, + OUT DAT_BOOLEAN *request_idle + ) +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIep_handle\fR\fR +.ad +.RS 16n +.rt +Handle for an instance of the Endpoint. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIep_state\fR\fR +.ad +.RS 16n +.rt +Current state of the Endpoint. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIrecv_idle\fR\fR +.ad +.RS 16n +.rt +Status of the incoming DTOs on the Endpoint. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIrequest_idle\fR\fR +.ad +.RS 16n +.rt +Status of the outgoing DTOs and RMR Bind operations on the Endpoint. +.RE + +.SH DESCRIPTION +.sp +.LP +the \fBdat_ep_get_status()\fR function provides the Consumer a quick snapshot +of the Endpoint. The snapshot consists of the Endpoint state and whether there +are outstanding or in-progress, incoming or outgoing DTOs. Incoming DTOs +consist of Receives. Outgoing DTOs consist of the Requests, Send, RDMA Read, +RDMA Write, and RMR Bind. +.sp +.LP +The \fIep_state\fR parameter returns the value of the current state of the +Endpoint \fIep_handle\fR. State value is one of the following: +\fBDAT_EP_STATE_UNCONNECTED\fR, \fBDAT_EP_STATE_RESERVED\fR, +\fBDAT_EP_STATE_PASSIVE_CONNECTION_PENDING\fR, +\fBDAT_EP_STATE_ACTIVE_CONNECTION_PENDING\fR, +\fBDAT_EP_STATE_TENTATIVE_CONNECTION_PENDING\fR, \fBDAT_EP_STATE_CONNECTED\fR, +\fBDAT_EP_STATE_DISCONNECT_PENDING\fR, or \fBDAT_EP_STATE_DISCONNECTED\fR. +.sp +.LP +A \fIrecv_idle\fR value of \fBDAT_TRUE\fR specifies that there are no +outstanding or in-progress Receive DTOs at the Endpoint, and \fBDAT_FALSE\fR +otherwise. +.sp +.LP +A \fIrequest_idle\fR value of \fBDAT_TRUE\fR specifies that there are no +outstanding or in-progress Send, RDMA Read, and RDMA Write DTOs, and RMR Binds +at the Endpoint, and \fBDAT_FALSE\fR otherwise. +.sp +.LP +This call provides a snapshot of the Endpoint status only. No heroic +synchronization with DTO queuing or processing is implied. +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBDAT_SUCCESS\fR\fR +.ad +.RS 22n +.rt +The operation was successful. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_HANDLE\fR\fR +.ad +.RS 22n +.rt +The \fIep_handle\fR parameter is invalid. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard: uDAPL, 1.1, 1.2 +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBlibdat\fR(3LIB), \fBattributes\fR(5) diff --git a/usr/src/man/man3dat/dat_ep_modify.3dat b/usr/src/man/man3dat/dat_ep_modify.3dat new file mode 100644 index 0000000000..febbde80a0 --- /dev/null +++ b/usr/src/man/man3dat/dat_ep_modify.3dat @@ -0,0 +1,550 @@ +'\" te +.\" This manual page is derived from the DAT/uDAPL 1.2 specification. +.\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH dat_ep_modify 3DAT "16 Jul 2004" "SunOS 5.11" "Direct Access Transport Library Functions" +.SH NAME +dat_ep_modify \- change parameters of an Endpoint +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ldat\fR [ \fIlibrary\fR\&.\|.\|. ] +#include <\fBdat/udat.h\fR> + +DAT_RETURN + dat_ep_modify ( + IN DAT_EP_HANDLE ep_handle, + IN DAT_EP_PARAM_MASK ep_param_mask, + IN DAT_EP_PARAM *ep_param + ) +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIep_handle\fR\fR +.ad +.RS 17n +.rt +Handle for an instance of the Endpoint. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIep_param_mask\fR\fR +.ad +.RS 17n +.rt +Mask for Endpoint parameters. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIep_param\fR\fR +.ad +.RS 17n +.rt +Pointer to the Consumer-allocated structure that contains Consumer-requested +Endpoint parameters. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBdat_ep_modify()\fR function provides the Consumer a way to change +parameters of an Endpoint. +.sp +.LP +The \fIep_param_mask\fR parameter allows Consumers to specify which parameters +to modify. Providers modify values for \fIep_param_mask\fR requested parameters +only. +.sp +.LP +Not all the parameters of the Endpoint can be modified. Some can be modified +only when the Endpoint is in a specific state. The following list specifies +which parameters can be modified and when they can be modified. +.sp +.ne 2 +.mk +.na +\fBInterface Adapter\fR +.ad +.sp .6 +.RS 4n +Cannot be modified. +.sp +Endpoint belongs to an open instance of IA and that association cannot be +changed. +.RE + +.sp +.ne 2 +.mk +.na +\fBEndpoint State\fR +.ad +.sp .6 +.RS 4n +Cannot be modified. +.sp +State of Endpoint cannot be changed by a \fBdat_ep_modify()\fR operation. +.RE + +.sp +.ne 2 +.mk +.na +\fBLocal IA Address\fR +.ad +.sp .6 +.RS 4n +Cannot be modified. +.sp +Local IA Address cannot be changed by a \fBdat_ep_modify()\fR operation. +.RE + +.sp +.ne 2 +.mk +.na +\fBLocal Port Qualifier\fR +.ad +.sp .6 +.RS 4n +Cannot be modified. +.sp +Local port qualifier cannot be changed by a \fBdat_ep_modify()\fR operation. +.RE + +.sp +.ne 2 +.mk +.na +\fBRemote IA Address\fR +.ad +.sp .6 +.RS 4n +Cannot be modified. +.sp +Remote IA Address cannot be changed by a \fBdat_ep_modify()\fR operation. +.RE + +.sp +.ne 2 +.mk +.na +\fBRemote Port Qualifier\fR +.ad +.sp .6 +.RS 4n +Cannot be modified. +.sp +Remote port qualifier cannot be changed by a \fBdat_ep_modify()\fR operation +.RE + +.sp +.ne 2 +.mk +.na +\fBProtection Zone\fR +.ad +.sp .6 +.RS 4n +Can be modified when in Quiescent, Unconnected, and Tentative Connection +Pending states. +.sp +Protection Zone can be changed only when the Endpoint is in quiescent state. +The only Endpoint states that isare quiescent isare +\fBDAT_EP_STATE_UNCONNECTED\fR and +\fBDAT_EP_STATE_TENTATIVE_CONNECTION_PENDING\fR. Consumers should be aware that +any Receive DTOs currently posted to the Endpoint that do not match the new +Protection Zone fail with a \fBDAT_PROTECTION_VIOLATION\fR return. +.RE + +.sp +.ne 2 +.mk +.na +\fBIn DTO Event Dispatcher\fR +.ad +.sp .6 +.RS 4n +Can be modified when in Unconnected, Reserved, Passive Connection Request +Pending, and Tentative Connection Pending states. +.sp +Event Dispatcher for incoming DTOs (Receive) can be changed only prior to a +request for a connection for an Active side or prior to accepting a Connection +Request for a Passive side. +.RE + +.sp +.ne 2 +.mk +.na +\fBOut DTO Event Dispatcher\fR +.ad +.sp .6 +.RS 4n +Can be modified when in Unconnected, Reserved, Passive Connection Pending, and +Tentative Connection Pending states. +.sp +Event Dispatcher for outgoing DTOs (Send, RDMA Read, and RDMA Write) can be +changed only prior to a request for a connection for an Active side or prior to +accepting a Connection Request for a Passive side. +.RE + +.sp +.ne 2 +.mk +.na +\fBConnection Event Dispatcher\fR +.ad +.sp .6 +.RS 4n +Can be modified when in Unconnected, Reserved, Passive Connection Pending, and +Tentative Connection Pending states. +.sp +Event Dispatcher for the Endpoint Connection events can be changed only prior +to a request for a connection for an Active side or accepting a Connection +Request for a Passive side. +.RE + +.sp +.ne 2 +.mk +.na +\fBService Type\fR +.ad +.sp .6 +.RS 4n +Can be modified when in Unconnected, Reserved, Passive Connection Pending, and +Tentative Connection Pending states. +.sp +Service Type can be changed only prior to a request for a connection for an +Active side or accepting a Connection Request for a Passive side. +.RE + +.sp +.ne 2 +.mk +.na +\fBMaximum Message Size\fR +.ad +.sp .6 +.RS 4n +Can be modified when in Unconnected, Reserved, Passive Connection Request +Pending, and Tentative Connection Pending states. +.sp +Maximum Message Size can be changed only prior to a request for a connection +for an Active side or accepting a Connection Request for a Passive side. +.RE + +.sp +.ne 2 +.mk +.na +\fBMaximum RDMA Size\fR +.ad +.sp .6 +.RS 4n +Can be modified when in Unconnected, Reserved, Passive Connection Pending, and +Tentative Connection Pending states. +.sp +Maximum RDMA Size can be changed only prior to a request for a connection for +an Active side or accepting a Connection Request for a Passive side. +.RE + +.sp +.ne 2 +.mk +.na +\fBQuality of Service\fR +.ad +.sp .6 +.RS 4n +Can be modified when in Unconnected, Reserved, Passive Connection Pending, and +Tentative Connection Pending states. +.sp +QoS can be changed only prior to a request for a connection for an Active side +or accepting a Connection Request for a Passive side. +.RE + +.sp +.ne 2 +.mk +.na +\fBRecv Completion Flags\fR +.ad +.sp .6 +.RS 4n +Can be modified when in Unconnected, Reserved, Passive Connection Pending, and +Tentative Connection Pending states. +.sp +Recv Completion Flags specifies what DTO flags the Endpoint should support for +Receive DTO operations. The value can be +\fBDAT_COMPLETION_NOTIFICATION_SUPPRESS_FLAG\fR, +\fBDAT_COMPLETION_SOLICITED_WAIT_FLAG\fR, or +\fBDAT_COMPLETION_EVD_THRESHOLD_FLAG\fR. Recv posting does not support +\fBDAT_COMPLETION_SUPPRESS_FLAG\fR or \fBDAT_COMPLETION_BARRIER_FENCE_FLAG\fR +dat_completion_flags values that are only applicable to Request postings. Recv +Completion Flags can be changed only prior to a request for a connection for an +Active side or accepting a Connection Request for a Passive side, but before +posting of any Recvs. +.RE + +.sp +.ne 2 +.mk +.na +\fBRequest Completion Flags\fR +.ad +.sp .6 +.RS 4n +Can be modified when in Unconnected, Reserved, Passive Connection Request +Pending, and Tentative Connection Pending states. +.sp +Request Completion Flags specifies what DTO flags the Endpoint should support +for Send, RDMA Read, RDMA Write, and RMR Bind operations. The value can be: +\fBDAT_COMPLETION_UNSIGNALLED_FLAG\fR or +\fBDAT_COMPLETION_EVD_THRESHOLD_FLAG\fR. Request postings always support +\fBDAT_COMPLETION_SUPPRESS_FLAG\fR, \fBDAT_COMPLETION_SOLICITED_WAIT_FLAG\fR, +or \fBDAT_COMPLETION_BARRIER_FENCE_FLAG\fR completion_flags values. Request +Completion Flags can be changed only prior to a request for a connection for an +Active side or accepting a Connection Request for a Passive side. +.RE + +.sp +.ne 2 +.mk +.na +\fBMaximum Recv DTO\fR +.ad +.sp .6 +.RS 4n +Can be modified when in Unconnected, Reserved, Passive Connection Pending, and +Tentative Connection Pending states. +.sp +Maximum Recv DTO specifies the maximum number of outstanding Consumer-submitted +Receive DTOs that a Consumer expects at any time at the Endpoint. Maximum Recv +DTO can be changed only prior to a request for a connection for an Active side +or accepting a Connection Request for a Passive side. +.RE + +.sp +.ne 2 +.mk +.na +\fBMaximum Request DTO\fR +.ad +.sp .6 +.RS 4n +Can be modified when in Unconnected, Reserved, Passive Connection Pending, and +Tentative Connection Pending states. +.sp +Maximum Request DTO specifies the maximum number of outstanding +Consumer-submitted send and RDMA DTOs and RMR Binds that a Consumer expects at +any time at the Endpoint. Maximum Out DTO can be changed only prior to a +request for a connection for an Active side or accepting a Connection Request +for a Passive side. +.RE + +.sp +.ne 2 +.mk +.na +\fBMaximum Recv IOV\fR +.ad +.sp .6 +.RS 4n +Can be modified when in Unconnected, Reserved, Passive Connection Pending, and +Tentative Connection Pending states. +.sp +Maximum Recv IOV specifies the maximum number of elements in IOV that a +Consumer specifies for posting a Receive DTO for the Endpoint. Maximum Recv IOV +can be changed only prior to a request for a connection for an Active side or +accepting a Connection Request for a Passive side. +.RE + +.sp +.ne 2 +.mk +.na +\fBMaximum Request IOV\fR +.ad +.sp .6 +.RS 4n +Can be modified when in Unconnected, Reserved, Passive Connection Pending, and +Tentative Connection Pending states. +.sp +Maximum Request IOV specifies the maximum number of elements in IOV that a +Consumer specifies for posting a Send, RDMA Read, or RDMA Write DTO for the +Endpoint. Maximum Request IOV can be changed only prior to a request for a +connection for an Active side or accepting a Connection Request for a Passive +side. +.RE + +.sp +.ne 2 +.mk +.na +\fBMaximum outstanding RDMA Read as target\fR +.ad +.sp .6 +.RS 4n +Can be modified when in Unconnected, Reserved, Passive Connection Pending, and +Tentative Connection Pending states. +.sp +Maximum number of outstanding RDMA Reads for which the Endpoint is the target. +.RE + +.sp +.ne 2 +.mk +.na +\fBMaximum outstanding RDMA Read as originator\fR +.ad +.sp .6 +.RS 4n +Can be modified when in Unconnected, Reserved, Passive Connection Pending, and +Tentative Connection Pending states. +.sp +Maximum number of outstanding RDMA Reads for which the Endpoint is the +originator. +.RE + +.sp +.ne 2 +.mk +.na +\fBNum transport-specific attributes\fR +.ad +.sp .6 +.RS 4n +Can be modified when in Quiescent (unconnected) state. +.sp +Number of transport-specific attributes to be modified. +.RE + +.sp +.ne 2 +.mk +.na +\fBTransport-specific endpoint attributes\fR +.ad +.sp .6 +.RS 4n +Can be modified when in Quiescent (unconnected) state. +.sp +Transport-specific attributes can be modified only in the transport-defined +Endpoint state. The only guaranteed safe state in which to modify +transport-specific Endpoint attributes is the quiescent state +\fBDAT_EP_STATE_UNCONNECTED\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fBNum provider-specific attributes\fR +.ad +.sp .6 +.RS 4n +Can be modified when in Quiescent (unconnected) state. +.sp + Number of Provider-specific attributes to be modified. +.RE + +.sp +.ne 2 +.mk +.na +\fBProvider-specific endpoint attributes\fR +.ad +.sp .6 +.RS 4n +Can be modified when in Quiescent (unconnected) state. +.sp +Provider-specific attributes can be modified only in the Provider-defined +Endpoint state. The only guaranteed safe state in which to modify +Provider-specific Endpoint attributes is the quiescent state +\fBDAT_EP_STATE_UNCONNECTED\fR. +.RE + +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBDAT_SUCCESS\fR\fR +.ad +.RS 25n +.rt +The operation was successful. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_HANDLE\fR\fR +.ad +.RS 25n +.rt +The \fIep_handle\fR parameter is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_PARAMETER\fR\fR +.ad +.RS 25n +.rt +The \fIep_param_mask\fR parameter is invalid, or one of the requested Endpoint +parameters or attributes was invalid, not supported, or cannot be modified. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_STATE\fR\fR +.ad +.RS 25n +.rt +Parameter in an invalid state. The Endpoint was not in the state that allows +one of the parameters or attributes to be modified. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard: uDAPL, 1.1, 1.2 +_ +MT-LevelUnsafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBlibdat\fR(3LIB), \fBattributes\fR(5) diff --git a/usr/src/man/man3dat/dat_ep_post_rdma_read.3dat b/usr/src/man/man3dat/dat_ep_post_rdma_read.3dat new file mode 100644 index 0000000000..2c9f6187e1 --- /dev/null +++ b/usr/src/man/man3dat/dat_ep_post_rdma_read.3dat @@ -0,0 +1,353 @@ +'\" te +.\" This manual page is derived from the DAT/uDAPL 1.2 specification. +.\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH dat_ep_post_rdma_read 3DAT "16 Jul 2004" "SunOS 5.11" "Direct Access Transport Library Functions" +.SH NAME +dat_ep_post_rdma_read \- transfer all data to the local data buffer +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ldat\fR [ \fIlibrary\fR\&.\|.\|. ] +#include <\fBdat/udat.h\fR> + +DAT_RETURN + dat_ep_post_rdma_read ( + IN DAT_EP_HANDLE ep_handle, + IN DAT_COUNT num_segments, + IN DAT_LMR_TRIPLET *local_iov, + IN DAT_DTO_COOKIE user_cookie, + IN DAT_RMR_TRIPLET *remote_buffer, + IN DAT_COMPLETION_FLAGS completion_flags + ) +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIep_handle\fR\fR +.ad +.RS 20n +.rt +Handle for an instance of the Endpoint. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fInum_segments\fR\fR +.ad +.RS 20n +.rt +Number of \fIlmr_triplets\fR in \fIlocal_iov\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIlocal_iov\fR\fR +.ad +.RS 20n +.rt +I/O Vector that specifies the local buffer to fill. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIuser_cookie\fR\fR +.ad +.RS 20n +.rt +User-provided cookie that is returned to the Consumer at the completion of the +RDMA Read. Can be \fINULL\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIremote_buffer\fR\fR +.ad +.RS 20n +.rt +A pointer to an RMR Triplet that specifies the remote buffer from which the +data is read. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcompletion_flags\fR\fR +.ad +.RS 20n +.rt +Flags for posted RDMA Read. The default \fBDAT_COMPLETION_DEFAULT_FLAG\fR is +0x00. Other values are as follows: +.sp +.ne 2 +.mk +.na +\fBCompletion Suppression\fR +.ad +.RS 30n +.rt +\fBDAT_COMPLETION_SUPPRESS_FLAG\fR +.sp +.ne 2 +.mk +.na +\fB0x01\fR +.ad +.RS 8n +.rt +Suppress successful Completion. +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fBNotification of Completion\fR +.ad +.RS 30n +.rt +\fB\fR\fBDAT_COMPLETION_UNSIGNALLED_FLAG\fR +.sp +.ne 2 +.mk +.na +\fB0x04\fR +.ad +.RS 8n +.rt +Non-notification completion. Local Endpoint must be configured for Notification +Suppression. +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fBBarrier Fence\fR +.ad +.RS 30n +.rt +\fB\fR\fBDAT_COMPLETION_BARRIER_FENCE_FLAG\fR +.sp +.ne 2 +.mk +.na +\fB0x08\fR +.ad +.RS 8n +.rt +Request for Barrier Fence. +.RE + +.RE + +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBdat_ep_post_rdma_read()\fR function requests the transfer of all the +data specified by the \fIremote_buffer\fR over the connection of the +\fIep_handle\fR Endpoint into the \fIlocal_iov\fR. +.sp +.LP +The \fInum_segments\fR parameter specifies the number of segments in the +\fIlocal_iov\fR. The \fIlocal_iov\fR segments are filled in the I/O Vector +order until the whole message is received. This ensures that all the "front" +segments of the \fIlocal_iov\fR I/O Vector are completely filled, only one +segment is partially filled, if needed, and all segments that follow it are not +filled at all. +.sp +.LP +The \fIuser_cookie\fR allows Consumers to have unique identifiers for each DTO. +These identifiers are completely under user control and are opaque to the +Provider. There is no requirement on the Consumer that the value +\fIuser_cookie\fR should be unique for each DTO. The \fIuser_cookie\fR is +returned to the Consumer in the Completion event for the posted RDMA Read. +.sp +.LP +A Consumer must not modify the \fIlocal_iov\fR or its content until the DTO is +completed. When a Consumer does not adhere to this rule, the behavior of the +Provider and the underlying Transport is not defined. Providers that allow +Consumers to get ownership of the \fIlocal_iov\fR but not the memory it +specifies back after the \fBdat_ep_post_rdma_read()\fR returns should document +this behavior and also specify its support in Provider attributes. This +behavior allows Consumers full control of the \fIlocal_iov\fR after +\fBdat_ep_post_rdma_read()\fR returns. Because this behavior is not guaranteed +by all Providers, portable Consumers should not rely on this behavior. +Consumers should not rely on the Provider copying \fIlocal_iov\fR information. +.sp +.LP +The completion of the posted RDMA Read is reported to the Consumer +asynchronously through a DTO Completion event based on the specified +\fIcompletion_flags\fR value. The value of +\fBDAT_COMPLETION_UNSIGNALLED_FLAG\fR is only valid if the Endpoint Request +Completion Flags \fBDAT_COMPLETION_UNSIGNALLED_FLAG\fR. Otherwise, +\fBDAT_INVALID_PARAMETER\fR is returned. +.sp +.LP +The \fBDAT_SUCCESS\fR return of the \fBdat_ep_post_rdma_read()\fR is at least +the equivalent of posting an RDMA Read operation directly by native Transport. +Providers should avoid resource allocation as part of +\fBdat_ep_post_rdma_read()\fR to ensure that this operation is nonblocking and +thread safe for an UpCall. +.sp +.LP +The operation is valid for the Endpoint in the \fBDAT_EP_STATE_CONNECTED\fR and +\fBDAT_EP_STATE_DISCONNECTED\fR states. If the operation returns successfully +for the Endpoint in the \fBDAT_EP_STATE_DISCONNECTED\fR state, the posted RDMA +Read is immediately flushed to \fIrequest_evd_handle\fR. +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBDAT_SUCCESS\fR\fR +.ad +.RS 30n +.rt +The operation was successful. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INSUFFICIENT_RESOURCES\fR\fR +.ad +.RS 30n +.rt +The operation failed due to resource limitations. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_PARAMETER\fR\fR +.ad +.RS 30n +.rt +Invalid parameter. For example, one of the IOV segments pointed to a memory +outside its LMR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_HANDLE\fR\fR +.ad +.RS 30n +.rt +The \fIep_handle\fR parameter is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_STATE\fR\fR +.ad +.RS 30n +.rt +A parameter is in an invalid state. Endpoint was not in the +\fBDAT_EP_STATE_CONNECTED\fR or \fBDAT_EP_STATE_DISCONNECTED\fR state. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_LENGTH_ERROR\fR\fR +.ad +.RS 30n +.rt +The size of the receiving buffer is too small for sending buffer data. The size +of the local buffer is too small for the data of the remote buffer. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_PROTECTION_VIOLATION\fR\fR +.ad +.RS 30n +.rt +Protection violation for local or remote memory access. Protection Zone +mismatch between either an LMR of one of the \fIlocal_iov\fR segments and the +local Endpoint or the \fIrmr_context\fR and the remote Endpoint. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_PRIVILEGES_VIOLATION\fR\fR +.ad +.RS 30n +.rt +Privileges violation for local or remote memory access. Either one of the LMRs +used in \fIlocal_iov\fR is invalid or does not have the local write privileges, +or \fIrmr_context\fR does not have the remote read privileges. +.RE + +.SH USAGE +.sp +.LP +For best RDMA Read operation performance, the Consumer should align each buffer +segment of \fIlocal_iov\fR to the Optimal Buffer Alignment attribute of the +Provider. For portable applications, the Consumer should align each buffer +segment of \fIlocal_iov\fR to the \fBDAT_OPTIMAL_ALIGNMENT\fR. +.sp +.LP +If connection was established without outstanding RDMA Read attributes matching +on Endpoints on both sides (outstanding RDMA Read outgoing on one end is larger +than the outstanding RDMA Read incoming on the other end), connection is broken +when the number of incoming RDMA Read exceeds the outstanding RDMA Read +incoming attribute of the Endpoint. The Consumer can use its own flow control +to ensure that it does not post more RDMA Reads then the remote EP outstanding +RDMA Read incoming attribute is. Thus, they do not rely on the underlying +Transport enforcing it. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard: uDAPL, 1.1, 1.2 +_ +MT-LevelUnsafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBlibdat\fR(3LIB), \fBattributes\fR(5) diff --git a/usr/src/man/man3dat/dat_ep_post_rdma_write.3dat b/usr/src/man/man3dat/dat_ep_post_rdma_write.3dat new file mode 100644 index 0000000000..c12a33f902 --- /dev/null +++ b/usr/src/man/man3dat/dat_ep_post_rdma_write.3dat @@ -0,0 +1,340 @@ +'\" te +.\" This manual page is derived from the DAT/uDAPL 1.2 specification. +.\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH dat_ep_post_rdma_write 3DAT "16 Jul 2004" "SunOS 5.11" "Direct Access Transport Library Functions" +.SH NAME +dat_ep_post_rdma_write \- write all data to the remote data buffer +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ldat\fR [ \fIlibrary\fR\&.\|.\|. ] +#include <\fBdat/udat.h\fR> + +DAT_RETURN + dat_ep_post_rdma_read ( + IN DAT_EP_HANDLE ep_handle, + IN DAT_COUNT num_segments, + IN DAT_LMR_TRIPLET *local_iov, + IN DAT_DTO_COOKIE user_cookie, + IN DAT_RMR_TRIPLET *remote_buffer, + IN DAT_COMPLETION_FLAGS completion_flags + ) +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIep_handle\fR\fR +.ad +.RS 20n +.rt +Handle for an instance of the Endpoint. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fInum_segments\fR\fR +.ad +.RS 20n +.rt +Number of \fIlmr_triplets\fR in \fIlocal_iov\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIlocal_iov\fR\fR +.ad +.RS 20n +.rt +I/O Vector that specifies the local buffer from which the data is transferred. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIuser_cookie\fR\fR +.ad +.RS 20n +.rt +User-provided cookie that is returned to the Consumer at the completion of the +RDMA Write. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIremote_buffer\fR\fR +.ad +.RS 20n +.rt +A pointer to an RMR Triplet that specifies the remote buffer from which the +data is read. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcompletion_flags\fR\fR +.ad +.RS 20n +.rt +Flags for posted RDMA read. The default \fBDAT_COMPLETION_DEFAULT_FLAG\fR is +0x00. Other values are as follows: +.sp +.ne 2 +.mk +.na +\fBCompletion Suppression\fR +.ad +.RS 30n +.rt +\fBDAT_COMPLETION_SUPPRESS_FLAG\fR +.sp +.ne 2 +.mk +.na +\fB0x01\fR +.ad +.RS 8n +.rt +Suppress successful Completion. +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fBNotification of Completion\fR +.ad +.RS 30n +.rt +\fB\fR\fBDAT_COMPLETION_UNSIGNALLED_FLAG\fR +.sp +.ne 2 +.mk +.na +\fB0x04\fR +.ad +.RS 8n +.rt +Non-notification completion. Local Endpoint must be configured for Notification +Suppression. +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fBBarrier Fence\fR +.ad +.RS 30n +.rt +\fB\fR\fBDAT_COMPLETION_BARRIER_FENCE_FLAG\fR +.sp +.ne 2 +.mk +.na +\fB0x08\fR +.ad +.RS 8n +.rt +Request for Barrier Fence. +.RE + +.RE + +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBdat_ep_post_rdma_write()\fR function requests the transfer of all the +data specified by the \fIlocal_iov\fR over the connection of the +\fIep_handle\fR Endpoint into the \fIremote_buffer\fR. +.sp +.LP +The \fInum_segments\fR parameter specifies the number of segments in the +\fIlocal_iov\fR. The \fIlocal_iov\fR segments are traversed in the I/O Vector +order until all the data is transferred. +.sp +.LP +A Consumer must not modify the \fIlocal_iov\fR or its content until the DTO is +completed. When a Consumer does not adhere to this rule, the behavior of the +Provider and the underlying Transport is not defined. Providers that allow +Consumers to get ownership of the \fIlocal_iov\fR but not the memory it +specifies back after the \fBdat_ep_post_rdma_write()\fR returns should document +this behavior and also specify its support in Provider attributes. This +behavior allows Consumers full control of the \fIlocal_iov\fR after +\fBdat_ep_post_rdma_write()\fR returns. Because this behavior is not guaranteed +by all Providers, portable Consumers should not rely on this behavior. +Consumers should not rely on the Provider copying \fIlocal_iov\fR information. +.sp +.LP +The \fBDAT_SUCCESS\fR return of the \fBdat_ep_post_rdma_write()\fR is at least +the equivalent of posting an RDMA Write operation directly by native Transport. +Providers should avoid resource allocation as part of +\fBdat_ep_post_rdma_write()\fR to ensure that this operation is nonblocking and +thread safe for an UpCall. +.sp +.LP +The completion of the posted RDMA Write is reported to the Consumer +asynchronously through a DTO Completion event based on the specified +\fIcompletion_flags\fR value. The value of +\fBDAT_COMPLETION_UNSIGNALLED_FLAG\fR is only valid if the Endpoint Request +Completion Flags \fBDAT_COMPLETION_UNSIGNALLED_FLAG\fR. Otherwise, +\fBDAT_INVALID_PARAMETER\fR is returned. +.sp +.LP +The \fIuser_cookie\fR allows Consumers to have unique identifiers for each DTO. +These identifiers are completely under user control and are opaque to the +Provider. There is no requirement on the Consumer that the value +\fIuser_cookie\fR should be unique for each DTO. The \fIuser_cookie\fR is +returned to the Consumer in the Completion event for the posted RDMA Write. +.sp +.LP +The operation is valid for the Endpoint in the \fBDAT_EP_STATE_CONNECTED\fR and +\fBDAT_EP_STATE_DISCONNECTED\fR states. If the operation returns successfully +for the Endpoint in the \fBDAT_EP_STATE_DISCONNECTED\fR state, the posted RDMA +Write is immediately flushed to \fIrequest_evd_handle\fR. +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBDAT_SUCCESS\fR\fR +.ad +.RS 30n +.rt +The operation was successful. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INSUFFICIENT_RESOURCES\fR\fR +.ad +.RS 30n +.rt +The operation failed due to resource limitations. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_PARAMETER\fR\fR +.ad +.RS 30n +.rt +Invalid parameter. For example, one of the IOV segments pointed to a memory +outside its LMR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_HANDLE\fR\fR +.ad +.RS 30n +.rt +The \fIep_handle\fR parameter is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_STATE\fR\fR +.ad +.RS 30n +.rt +A parameter is in an invalid state. Endpoint was not in the +\fBDAT_EP_STATE_CONNECTED\fR or \fBDAT_EP_STATE_DISCONNECTED\fR state. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_LENGTH_ERROR\fR\fR +.ad +.RS 30n +.rt +The size of the receiving buffer is too small for sending buffer data. The size +of the remote buffer is too small for the data of the local buffer. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_PROTECTION_VIOLATION\fR\fR +.ad +.RS 30n +.rt +Protection violation for local or remote memory access. Protection Zone +mismatch between either an LMR of one of the \fIlocal_iov\fR segments and the +local Endpoint or the \fIrmr_context\fR and the remote Endpoint. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_PRIVILEGES_VIOLATION\fR\fR +.ad +.RS 30n +.rt +Privileges violation for local or remote memory access. Either one of the LMRs +used in \fIlocal_iov\fR is invalid or does not have the local read privileges, +or \fIrmr_context\fR does not have the remote write privileges. +.RE + +.SH USAGE +.sp +.LP +For best RDMA Write operation performance, the Consumer should align each +buffer segment of \fIlocal_iov\fR to the Optimal Buffer Alignment attribute of +the Provider. For portable applications, the Consumer should align each buffer +segment of \fIlocal_iov\fR to the \fBDAT_OPTIMAL_ALIGNMENT\fR. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard: uDAPL, 1.1, 1.2 +_ +MT-LevelUnsafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBlibdat\fR(3LIB), \fBattributes\fR(5) diff --git a/usr/src/man/man3dat/dat_ep_post_recv.3dat b/usr/src/man/man3dat/dat_ep_post_recv.3dat new file mode 100644 index 0000000000..cdebadb692 --- /dev/null +++ b/usr/src/man/man3dat/dat_ep_post_recv.3dat @@ -0,0 +1,271 @@ +'\" te +.\" This manual page is derived from the DAT/uDAPL 1.2 specification. +.\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH dat_ep_post_recv 3DAT "16 Jul 2004" "SunOS 5.11" "Direct Access Transport Library Functions" +.SH NAME +dat_ep_post_recv \- receive data over the connection of the Endpoint +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ldat\fR [ \fIlibrary\fR\&.\|.\|. ] +#include <\fBdat/udat.h\fR> + +DAT_RETURN + dat_ep_post_recv ( + IN DAT_EP_HANDLE ep_handle, + IN DAT_COUNT num_segments, + IN DAT_LMR_TRIPLET *local_iov, + IN DAT_DTO_COOKIE user_cookie, + IN DAT_COMPLETION_FLAGS completion_flags + ) +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIep_handle\fR\fR +.ad +.RS 20n +.rt +Handle for an instance of the Endpoint. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fInum_segments\fR\fR +.ad +.RS 20n +.rt +Number of \fIlmr_triplets\fR in \fIlocal_iov\fR. Can be 0 for receiving a 0 +size message. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIlocal_iov\fR\fR +.ad +.RS 20n +.rt +I/O Vector that specifies the local buffer to be filled. Can be \fINULL\fR for +receiving a 0 size message. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIuser_cookie:\fR\fR +.ad +.RS 20n +.rt +User-provided cookie that is returned to the Consumer at the completion of the +Receive DTO. Can be \fINULL\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcompletion_flags\fR\fR +.ad +.RS 20n +.rt +Flags for posted Receive. The default \fBDAT_COMPLETION_DEFAULT_FLAG\fR is +0x00. Other values are as follows: +.sp +.ne 2 +.mk +.na +\fBNotification of Completion\fR +.ad +.RS 30n +.rt +\fBDAT_COMPLETION_UNSIGNALLED_FLAG\fR +.sp +.ne 2 +.mk +.na +\fB0x04\fR +.ad +.RS 8n +.rt +Non-notification completion. Local Endpoint must be configured for Unsignaled +CompletionNotification Suppression. +.RE + +.RE + +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBdat_ep_post_recv()\fR function requests the receive of the data over the +connection of the \fIep_handle\fR Endpoint of the incoming message into the +\fIlocal_iov\fR. +.sp +.LP +The \fInum_segments\fR parameter specifies the number of segments in the +\fIlocal_iov\fR. The \fIlocal_iov\fR segments are filled in the I/O Vector +order until the whole message is received. This ensures that all the "front" +segments of the \fIlocal_iov\fR I/O Vector are completely filled, only one +segment is partially filled, if needed, and all segments that follow it are not +filled at all. +.sp +.LP +The \fIuser_cookie\fR allows Consumers to have unique identifiers for each DTO. +These identifiers are completely under user control and are opaque to the +Provider. There is no requirement on the Consumer that the value +\fIuser_cookie\fR should be unique for each DTO. The \fIuser_cookie\fR is +returned to the Consumer in the Completion event for the posted Receive. +.sp +.LP +The completion of the posted Receive is reported to the Consumer asynchronously +through a DTO Completion event based on the configuration of the connection for +Solicited Wait and the specified \fIcompletion_flags\fR value for the matching +Send. The value of \fBDAT_COMPLETION _UNSIGNALLED_FLAG\fR is only valid if the +Endpoint Recv Completion Flags \fBDAT_COMPLETION_UNSIGNALLED_FLAG\fR. +Otherwise, \fBDAT_INVALID_PARAMETER\fR is returned. +.sp +.LP +A Consumer must not modify the \fIlocal_iov\fR or its content until the DTO is +completed. When a Consumer does not adhere to this rule, the behavior of the +Provider and the underlying Transport is not defined. Providers that allow +Consumers to get ownership of the \fIlocal_iov\fR but not the memory it +specified back after the \fBdat_ep_post_recv()\fR returns should document this +behavior and also specify its support in Provider attributes. This behavior +allows Consumer full control of the \fIlocal_iov\fR content after +\fBdat_ep_post_recv()\fR returns. Because this behavior is not guaranteed by +all Providers, portable Consumers should not rely on this behavior. Consumers +shouldnot rely on the Provider copying \fIlocal_iov\fR information. +.sp +.LP +The \fBDAT_SUCCESS\fR return of the \fBdat_ep_post_recv()\fR is at least the +equivalent of posting a Receive operation directly by native Transport. +Providers should avoid resource allocation as part of \fBdat_ep_post_recv()\fR +to ensure that this operation is nonblocking and thread safe for an UpCall. +.sp +.LP +If the size of an incoming message is larger than the size of the +\fIlocal_iov\fR, the reported status of the posted Receive DTO in the +corresponding Completion DTO event is \fBDAT_DTO_LENGTH_ERROR\fR. If the +reported status of the Completion DTO event corresponding to the posted Receive +DTO is not \fBDAT_DTO_SUCCESS\fR, the content of the \fIlocal_iov\fR is not +defined. +.sp +.LP +The operation is valid for all states of the Endpoint. The actual data transfer +does not take place until the Endpoint is in the \fBDAT_EP_STATE_CONNECTED\fR +state. The operation on the Endpoint in \fBDAT_EP_STATE_DISCONNECTED\fR is +allowed. If the operation returns successfully, the posted Recv is immediately +flushed to \fIrecv_evd_handle\fR. +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBDAT_SUCCESS\fR\fR +.ad +.RS 30n +.rt +The operation was successful. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INSUFFICIENT_RESOURCES\fR\fR +.ad +.RS 30n +.rt +The operation failed due to resource limitations. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_PARAMETER\fR\fR +.ad +.RS 30n +.rt +Invalid parameter. For example, one of the IOV segments pointed to a memory +outside its LMR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_HANDLE\fR\fR +.ad +.RS 30n +.rt +The \fIep_handle\fR parameter is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_PROTECTION_VIOLATION\fR\fR +.ad +.RS 30n +.rt +Protection violation for local or remote memory access. Protection Zone +mismatch between an LMR of one of the \fIlocal_iov\fR segments and the local +Endpoint. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_PRIVILEGES_VIOLATION\fR\fR +.ad +.RS 30n +.rt +Privileges violation for local or remote memory access. One of the LMRs used in +\fIlocal_iov\fR was either invalid or did not have the local read privileges. +.RE + +.SH USAGE +.sp +.LP +For best Recv operation performance, the Consumer should align each buffer +segment of \fIlocal_iov\fR to the Optimal Buffer Alignment attribute of the +Provider. For portable applications, the Consumer should align each buffer +segment of \fIlocal_iov\fR to the \fBDAT_OPTIMAL_ALIGNMENT\fR. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard: uDAPL, 1.1, 1.2 +_ +MT-LevelUnsafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBlibdat\fR(3LIB), \fBattributes\fR(5) diff --git a/usr/src/man/man3dat/dat_ep_post_send.3dat b/usr/src/man/man3dat/dat_ep_post_send.3dat new file mode 100644 index 0000000000..de3f466289 --- /dev/null +++ b/usr/src/man/man3dat/dat_ep_post_send.3dat @@ -0,0 +1,336 @@ +'\" te +.\" This manual page is derived from the DAT/uDAPL 1.2 specification. +.\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH dat_ep_post_send 3DAT "16 Jul 2004" "SunOS 5.11" "Direct Access Transport Library Functions" +.SH NAME +dat_ep_post_send \- transfer data to the remote side +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ldat\fR [ \fIlibrary\fR\&.\|.\|. ] +#include <\fBdat/udat.h\fR> + +DAT_RETURN + dat_ep_post_send ( + IN DAT_EP_HANDLE ep_handle, + IN DAT_COUNT num_segments, + IN DAT_LMR_TRIPLET *local_iov, + IN DAT_DTO_COOKIE user_cookie, + IN DAT_COMPLETION_FLAGS completion_flags + ) +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIep_handle\fR\fR +.ad +.RS 20n +.rt +Handle for an instance of the Endpoint. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fInum_segments\fR\fR +.ad +.RS 20n +.rt +Number of \fIlmr_triplets\fR in \fIlocal_iov\fR. Can be 0 for 0 size message. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIlocal_iov\fR\fR +.ad +.RS 20n +.rt +I/O Vector that specifies the local buffer that contains data to be +transferred. Can be \fINULL\fR for 0 size message. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIuser_cookie:\fR\fR +.ad +.RS 20n +.rt +User-provided cookie that is returned to the Consumer at the completion of the +send. Can be \fINULL\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcompletion_flags\fR\fR +.ad +.RS 20n +.rt +Flags for posted Send. The default \fBDAT_COMPLETION_DEFAULT_FLAG\fR is 0x00. +Other values are as follows: +.sp +.ne 2 +.mk +.na +\fBCompletion Suppression\fR +.ad +.RS 30n +.rt +\fBDAT_COMPLETION_SUPPRESS_FLAG\fR +.sp +.ne 2 +.mk +.na +\fB0x01\fR +.ad +.RS 8n +.rt +Suppress successful Completion. +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fBSolicited Wait\fR +.ad +.RS 30n +.rt +\fBDAT_COMPLETION_SOLICITED_WAIT_FLAG\fR +.sp +.ne 2 +.mk +.na +\fB0x02\fR +.ad +.RS 8n +.rt +Request for notification completion for matching receive on the other side of +the connection. +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fBNotification of Completion\fR +.ad +.RS 30n +.rt +\fB\fR\fBDAT_COMPLETION_UNSIGNALLED_FLAG\fR +.sp +.ne 2 +.mk +.na +\fB0x04\fR +.ad +.RS 8n +.rt +Non-notification completion. Local Endpoint must be configured for Notification +Suppression. +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fBBarrier Fence\fR +.ad +.RS 30n +.rt +\fB\fR\fBDAT_COMPLETION_BARRIER_FENCE_FLAG\fR +.sp +.ne 2 +.mk +.na +\fB0x08\fR +.ad +.RS 8n +.rt +Request for Barrier Fence. +.RE + +.RE + +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBdat_ep_post_send()\fR function requests a transfer of all the data from +the \fIlocal_iov\fR over the connection of the \fIep_handle\fR Endpoint to the +remote side. +.sp +.LP +The \fInum_segments\fR parameter specifies the number of segments in the +\fIlocal_iov\fR. The \fIlocal_iov\fR segments are traversed in the I/O Vector +order until all the data is transferred. +.sp +.LP +A Consumer cannot modify the \fIlocal_iov\fR or its content until the DTO is +completed. When a Consumer does not adhere to this rule, the behavior of the +Provider and the underlying Transport is not defined. Providers that allow +Consumers to get ownership of the \fIlocal_iov\fR back after the +\fBdat_ep_post_send()\fR returns should document this behavior and also specify +its support in Provider attributes. This behavior allows Consumers full control +of the \fIlocal_iov\fR, but not the memory it specifies after +\fBdat_ep_post_send()\fR returns. Because this behavior is not guaranteed by +all Providers, portable Consumers should not rely on this behavior. Consumers +should not rely on the Provider copying \fIlocal_iov\fR information. +.sp +.LP +The \fBDAT_SUCCESS\fR return of the \fBdat_ep_post_send()\fR is at least the +equivalent of posting a Send operation directly by native Transport. Providers +should avoid resource allocation as part of \fBdat_ep_post_send()\fR to ensure +that this operation is nonblocking and thread safe for an UpCall. +.sp +.LP +The completion of the posted Send is reported to the Consumer asynchronously +through a DTO Completion event based on the specified \fIcompletion_flags\fR +value. The value of \fBDAT_COMPLETION _UNSIGNALLED_FLAG\fR is only valid if the +Endpoint Request Completion Flags \fBDAT_COMPLETION_UNSIGNALLED_FLAG\fR. +Otherwise, \fBDAT_INVALID_PARAMETER\fR is returned. +.sp +.LP +The \fIuser_cookie\fR allows Consumers to have unique identifiers for each DTO. +These identifiers are completely under user control and are opaque to the +Provider. There is no requirement on the Consumer that the value +\fIuser_cookie\fR should be unique for each DTO. The \fIuser_cookie\fR is +returned to the Consumer in the Completion event for the posted Send. +.sp +.LP +The operation is valid for the Endpoint in the \fBDAT_EP_STATE_CONNECTED\fR and +\fBDAT_EP_STATE_DISCONNECTED\fR states. If the operation returns successfully +for the Endpoint in the \fBDAT_EP_STATE_DISCONNECTED\fR state, the posted Send +is immediately flushed to \fIrequest_evd_handle\fR. +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBDAT_SUCCESS\fR\fR +.ad +.RS 30n +.rt +The operation was successful. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INSUFFICIENT_RESOURCES\fR\fR +.ad +.RS 30n +.rt +The operation failed due to resource limitations. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_PARAMETER\fR\fR +.ad +.RS 30n +.rt +Invalid parameter. For example, one of the IOV segments pointed to a memory +outside its LMR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_HANDLE\fR\fR +.ad +.RS 30n +.rt +The \fIep_handle\fR parameter is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_STATE\fR\fR +.ad +.RS 30n +.rt +A parameter is in an invalid state. Endpoint was not in the +\fBDAT_EP_STATE_CONNECTED\fR or \fBDAT_EP_STATE_DISCONNECTED\fR state. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_PROTECTION_VIOLATION\fR\fR +.ad +.RS 30n +.rt +Protection violation for local or remote memory access. Protection Zone +mismatch between an LMR of one of the \fIlocal_iov\fR segments and the local +Endpoint. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_PRIVILEGES_VIOLATION\fR\fR +.ad +.RS 30n +.rt +Privileges violation for local or remote memory access. One of the LMRs used in +\fIlocal_iov\fR was either invalid or did not have the local read privileges. +.RE + +.SH USAGE +.sp +.LP +For best Send operation performance, the Consumer should align each buffer +segment of \fIlocal_iov\fR to the Optimal Buffer Alignment attribute of the +Provider. For portable applications, the Consumer should align each buffer +segment of \fIlocal_iov\fR to the \fBDAT_OPTIMAL_ALIGNMENT\fR. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard: uDAPL, 1.1, 1.2 +_ +MT-LevelUnsafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBlibdat\fR(3LIB), \fBattributes\fR(5) diff --git a/usr/src/man/man3dat/dat_ep_query.3dat b/usr/src/man/man3dat/dat_ep_query.3dat new file mode 100644 index 0000000000..0fff1a04e6 --- /dev/null +++ b/usr/src/man/man3dat/dat_ep_query.3dat @@ -0,0 +1,144 @@ +'\" te +.\" This manual page is derived from the DAT/uDAPL 1.2 specification. +.\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH dat_ep_query 3DAT "16 Jul 2004" "SunOS 5.11" "Direct Access Transport Library Functions" +.SH NAME +dat_ep_query \- provide parameters of the Endpoint +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ldat\fR [ \fIlibrary\fR\&.\|.\|. ] +#include <\fBdat/udat.h\fR> + +DAT_RETURN + dat_ep_query ( + IN DAT_EP_HANDLE ep_handle, + IN DAT_EP_PARAM_MASK ep_param_mask, + OUT DAT_EP_PARAM *ep_param + ) +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIep_handle\fR\fR +.ad +.RS 17n +.rt +Handle for an instance of the Endpoint. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIep_param_mask\fR\fR +.ad +.RS 17n +.rt +Mask for Endpoint parameters. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIep_param\fR\fR +.ad +.RS 17n +.rt +Pointer to a Consumer-allocated structure that the Provider fills with Endpoint +parameters. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBdat_ep_query()\fR function provides the Consumer parameters, including +attributes and status, of the Endpoint. Consumers pass in a pointer to +Consumer-allocated structures for Endpoint parameters that the Provider fills. +.sp +.LP +The \fIep_param_mask\fR parameter allows Consumers to specify which parameters +to query. The Provider returns values for \fIep_param_mask\fR requested +parameters. The Provider can return values for any other parameters. +.sp +.LP +Some of the parameters only have values for certain Endpoint states. +Specifically, the values for \fIremote_ia_address\fR and \fIremote_port_qual\fR +are valid only for Endpoints in the +\fBDAT_EP_STATE_PASSIVE_CONNECTION_PENDING\fR, +\fBDAT_EP_STATE_ACTIVE_CONNECTION_PENDING\fR, +\fBDAT_EP_STATE_TENTATIVE_CONNECTION_PENDING\fR, +\fBDAT_EP_STATE_DISCONNECT_PENDING\fR, \fBDAT_EP_STATE_COMPLETION_PENDING\fR, +or \fBDAT_EP_STATE_CONNECTED\fR states. The values of \fIlocal_port_qual\fR is +valid only for Endpoints in the \fBDAT_EP_STATE_PASSIVE_CONNECTION_PENDING\fR, +\fBDAT_EP_STATE_ACTIVE_CONNECTION_PENDING\fR, +\fBDAT_EP_STATE_DISCONNECT_PENDING\fR, \fBDAT_EP_STATE_COMPLETION_PENDING\fR, +or \fBDAT_EP_STATE_CONNECTED\fR states, and might be valid for +\fBDAT_EP_STATE_UNCONNECTED\fR, \fBDAT_EP_STATE_RESERVED\fR, +\fBDAT_EP_STATE_TENTATIVE_CONNECTION_PENDING\fR, +\fBDAT_EP_STATE_PASSIVE_CONNECTION_PENDING\fR, and +\fBDAT_EP_STATE_UNCONNECTED\fR states. +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBDAT_SUCCESS\fR\fR +.ad +.RS 25n +.rt +The operation was successful. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_HANDLE\fR\fR +.ad +.RS 25n +.rt +The \fIep_handle\fR parameter is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_PARAMETER\fR\fR +.ad +.RS 25n +.rt +The \fIep_param_mask\fR parameter is invalid. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard: uDAPL, 1.1, 1.2 +_ +MT-LevelUnsafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBlibdat\fR(3LIB), \fBattributes\fR(5) diff --git a/usr/src/man/man3dat/dat_ep_recv_query.3dat b/usr/src/man/man3dat/dat_ep_recv_query.3dat new file mode 100644 index 0000000000..6601c07104 --- /dev/null +++ b/usr/src/man/man3dat/dat_ep_recv_query.3dat @@ -0,0 +1,231 @@ +'\" te +.\" This manual page is derived from the DAT/uDAPL 1.2 specification. +.\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH dat_ep_recv_query 3DAT "16 Jul 2004" "SunOS 5.11" "Direct Access Transport Library Functions" +.SH NAME +dat_ep_recv_query \- provide Endpoint receive queue consumption on SRQ +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ldat\fR [ \fIlibrary\fR\&.\|.\|. ] +#include <\fBdat/udat.h\fR> + +DAT_RETURN + dat_ep_recv_query ( + IN DAT_EP_HANDLE ep_handle, + OUT DAT_COUNT *nbufs_allocated, + OUT DAT_COUNT *bufs_alloc_span + ) +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIep_handle\fR\fR +.ad +.RS 19n +.rt +Handle for an instance of the EP. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fInbufs_allocated\fR\fR +.ad +.RS 19n +.rt +The number of buffers at the EP for which completions have not yet been +generated. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIbufs_alloc_span\fR\fR +.ad +.RS 19n +.rt +The span of buffers that EP needs to complete arriving messages. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBdat_ep_recv_query()\fR function provides to the Consumer a snapshot for +Recv buffers on EP. The values for \fInbufs_allocated\fR and +\fIbufs_alloc_span\fR are not defined when \fBDAT_RETURN\fR is not +\fBDAT_SUCCESS\fR. +.sp +.LP +The Provider might not support \fInbufs_allocated\fR, \fIbufs_alloc_span\fR or +both. Check the Provider attribute for EP Recv info support. When the Provider +does not support both of these counts, the return value for the operation can +be \fBDAT_MODEL_NOT_SUPPORTED\fR. +.sp +.LP +If \fInbufs_allocated\fR is not \fINULL\fR, the count pointed to by +\fInbufs_allocated\fR will return a snapshot count of the number of buffers +allocated to \fIep_handle\fR but not yet completed. +.sp +.LP +Once a buffer has been allocated to an EP, it will be completed to the EP +\fIrecv_evd\fR if the EVD has not overflowed. When an EP does not use SRQ, a +buffer is allocated as soon as it is posted to the EP. For EP that uses SRQ, a +buffer is allocated to the EP when EP removes it from SRQ. +.sp +.LP +If \fIbufs_alloc_span\fR is not \fINULL\fR, then the count to which +\fIbufs_alloc_span\fR pointed will return the span of buffers allocated to the +\fIep_handle\fR. The span is the number of additional successful Recv +completions that EP can generate if all the messages it is currently receiving +will complete successfully. +.sp +.LP +If a message sequence number is assigned to all received messages, the buffer +span is the difference between the latest message sequence number of an +allocated buffer minus the latest message sequence number for which completion +has been generated. This sequence number only counts Send messages of remote +Endpoint of the connection. +.sp +.LP +The Message Sequence Number (MSN) represents the order that Send messages were +submitted by the remote Consumer. The ordering of sends is intrinsic to the +definition of a reliable service. Therefore every send message does have a MSN +whether or not the native transport has a field with that name. +.sp +.LP +For both \fInbufs_allocated\fR and \fIbufs_alloc_span\fR, the Provider can +return the reserved value \fBDAT_VALUE_UNKNOWN\fR if it cannot obtain the +requested count at a reasonable cost. +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBDAT_SUCCESS\fR\fR +.ad +.RS 27n +.rt +The operation was successful. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_PARAMETER\fR\fR +.ad +.RS 27n +.rt +Invalid parameter. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_HANDLE\fR\fR +.ad +.RS 27n +.rt +The DAT handle ep_handle is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_MODEL_NOT_SUPPORTED\fR\fR +.ad +.RS 27n +.rt +The requested Model was not supported by the Provider. +.RE + +.SH USAGE +.sp +.LP +If the Provider cannot support the query for \fInbufs_allocated\fR or +\fIbufs_alloc_span\fR, the value returned for that attribute must be +\fBDAT_VALUE_UNKNOWN\fR. +.sp +.LP +An implementation that processes incoming packets out of order and allocates +from SRQs on an arrival basis can have gaps in the MSNs associated with buffers +allocated to an Endpoint. +.sp +.LP +For example, suppose Endpoint X has received buffer fragments for MSNs 19, 22, +and 23. With arrival ordering, the EP would have allocated three buffers from +the SRQ for messages 19, 22, and 23. The number allocated would be 3, but the +span would be 5. The difference of two represents the buffers that will have to +be allocated for messages 20 and 21. They have not yet been allocated, but +messages 22 and 23 will not be delivered until after messages 20 and 21 have +not only had their buffers allocated but have also completed. +.sp +.LP +An implementation can choose to allocate 20 and 21 as soon as any higher buffer +is allocated. This makes sense if you presume that this is a valid connection, +because obviously 20 and 21 are in flight. However, it creates a greater +vulnerability to Denial Of Service attacks. There are also other implementation +tradeoffs, so the Consumer should accept that different RNICs for iWARP will +employ different strategies on when to perform these allocations. +.sp +.LP +Each implementation will have some method of tracking the receive buffers +already associated with an EP and knowing which buffer matches which incoming +message, though those methods might vary. In particular, there are valid +implementations such as linked lists, where a count of the outstanding buffers +is not instantly available. Such implementations would have to scan the +allocated list to determine both the number of buffers and their span. If such +a scan is necessary, it is important that it be only a single scan. The set of +buffers that was counted must be the same set of buffers for which the span is +reported. +.sp +.LP +The implementation should not scan twice, once to count the buffers and then +again to determine their span. Not only is it inefficient, but it might produce +inconsistent results if buffers were completed or arrived between the two +scans. +.sp +.LP +Other implementations can simply maintain counts of these values to easily +filter invalid packets. If so, these status counters should be updated and +referenced atomically. +.sp +.LP +The implementation must never report \fIn\fR buffers in a span that is less +than \fIn\fR. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard: uDAPL, 1.2 +_ +MT-LevelUnsafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBdat_ep_create\fR(3DAT), \fBdat_srq_create\fR(3DAT), +\fBdat_srq_free\fR(3DAT), \fBdat_srq_query\fR(3DAT), +\fBdat_ep_set_watermark\fR(3DAT), \fBlibdat\fR(3LIB), \fBattributes\fR(5) diff --git a/usr/src/man/man3dat/dat_ep_reset.3dat b/usr/src/man/man3dat/dat_ep_reset.3dat new file mode 100644 index 0000000000..8bbf878c88 --- /dev/null +++ b/usr/src/man/man3dat/dat_ep_reset.3dat @@ -0,0 +1,116 @@ +'\" te +.\" This manual page is derived from the DAT/uDAPL 1.2 specification. +.\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH dat_ep_reset 3DAT "16 Jul 2004" "SunOS 5.11" "Direct Access Transport Library Functions" +.SH NAME +dat_ep_reset \- transition the local Endpoint from a Disconnected to an +Unconnected state +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ldat\fR [ \fIlibrary\fR\&.\|.\|. ] +#include <\fBdat/udat.h\fR> + +DAT_RETURN + dat_ep_reset ( + IN DAT_EP_HANDLE ep_handle + ) +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIep_handle\fR\fR +.ad +.RS 13n +.rt +Handle for an instance of Endpoint. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBdat_ep_reset()\fR function transitions the local Endpoint from a +Disconnected to an Unconnected state. +.sp +.LP +The operation might cause the loss of any completions of previously posted DTOs +and RMRs that were not dequeued yet. +.sp +.LP +The \fBdat_ep_reset()\fR function is valid for both Disconnected and +Unconnected states. For Unconnected state, the operation is no-op because the +Endpoint is already in an Unconnected state. For an Unconnected state, the +preposted Recvs are not affected by the call. +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBDAT_SUCCESS\fR\fR +.ad +.RS 22n +.rt +The operation was successful. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_HANDLE\fR\fR +.ad +.RS 22n +.rt +ep_handle is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_STATE\fR\fR +.ad +.RS 22n +.rt +Parameter in an invalid state. Endpoint is not in the valid state for reset. +.RE + +.SH USAGE +.sp +.LP +If the Consumer wants to ensure that all Completions are dequeued, the Consumer +can post DTO or RMR operations as a "marker" that are flushed to +\fIrecv_evd_handle\fR or \fIrequest_evd_handle\fR. Now, when the Consumer +dequeues the completion of the "marker" from the EVD, it is guaranteed that all +previously posted DTO and RMR completions for the Endpoint were dequeued for +that EVD. Now, it is safe to reset the Endpoint without losing any +completions. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard: uDAPL, 1.1, 1.2 +_ +MT-LevelUnsafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBlibdat\fR(3LIB), \fBattributes\fR(5) diff --git a/usr/src/man/man3dat/dat_ep_set_watermark.3dat b/usr/src/man/man3dat/dat_ep_set_watermark.3dat new file mode 100644 index 0000000000..09e22e7fb0 --- /dev/null +++ b/usr/src/man/man3dat/dat_ep_set_watermark.3dat @@ -0,0 +1,180 @@ +'\" te +.\" This manual page is derived from the DAT/uDAPL 1.2 specification. +.\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH dat_ep_set_watermark 3DAT "16 Jul 2004" "SunOS 5.11" "Direct Access Transport Library Functions" +.SH NAME +dat_ep_set_watermark \- set high watermark on Endpoint +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ldat\fR [ \fIlibrary\fR\&.\|.\|. ] +#include <\fBdat/udat.h\fR> + +DAT_RETURN + dat_ep_set_watermark ( + IN DAT_EP_HANDLE ep_handle, + IN DAT_COUNT soft_high_watermark, + IN DAT_COUNT hard_high_watermark + ) +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIep_handle\fR\fR +.ad +.RS 23n +.rt +The handle for an instance of an Endpoint. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIsoft_high_watermark\fR\fR +.ad +.RS 23n +.rt +The soft high watermark for the number of Recv buffers consumed by the +Endpoint. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIhard_high_watermark\fR\fR +.ad +.RS 23n +.rt +The hard high watermark for the number of Recv buffers consumed by the +Endpoint. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBdat_ep_set_watermark()\fR function sets the soft and hard high watermark +values for EP and arms EP for generating asynchronous events for high +watermarks. An asynchronous event will be generated for IA \fIasync_evd\fR when +the number of Recv buffers at EP exceeds the soft high watermark for the first +time. A connection broken event will be generated for EP \fIconnect_evd\fR when +the number of Recv buffers at EP exceeds the hard high watermark. These can +occur during this call or when EP takes a buffer from the SRQ or EP RQ. The +soft and hard high watermark asynchronous event generation and setting are +independent of each other. +.sp +.LP +The asynchronous event for a soft high watermark is generated only once per +setting. Once an event is generated, no new asynchronous events for the soft +high watermark is generated until the EP is again set for the soft high +watermark. If the Consumer is once again interested in the event, the Consumer +should again set the soft high watermark. +.sp +.LP +If the Consumer is not interested in a soft or hard high watermark, the value +of \fBDAT_WATERMARK_INFINITE\fR can be specified for the case that is the +default value. This value specifies that a non-asynchronous event will be +generated for a high watermark EP attribute for which this value is set. It +does not prevent generation of a connection broken event for EP when no Recv +buffer is available for a message arrived on the EP connection. +.sp +.LP +The operation is supported for all states of Endpoint. +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBDAT_SUCCESS\fR\fR +.ad +.RS 27n +.rt +The operation was successful. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_HANDLE\fR\fR +.ad +.RS 27n +.rt +The \fIep_handle\fR argument is an invalid DAT handle. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_PARAMETER\fR\fR +.ad +.RS 27n +.rt +One of the parameters is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_MODEL_NOT_SUPPORTED\fR\fR +.ad +.RS 27n +.rt +The requested Model was not supported by the Provider. The Provider does not +support EP Soft or Hard High Watermarks. +.RE + +.SH USAGE +.sp +.LP +For a hard high watermark, the Provider is ready to generate a connection +broken event as soon as the connection is established. +.sp +.LP +If the asynchronous event for a soft or hard high watermark has not yet been +generated, this call simply modifies the values for these attributes. The +Provider remains armed for generation of these asynchronous events. +.sp +.LP +Regardless of whether an asynchronous event for the soft and hard high +watermark has been generated, this operation will set the generation of an +asynchronous event with the Consumer-provided high watermark values. If the new +high watermark values are below the current number of Receive DTOs at EP, an +asynchronous event will be generated immediately. Otherwise the old soft or +hard (or both) high watermark values are simply replaced with the new ones. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard: uDAPL, 1.2 +_ +MT-LevelUnsafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBdat_ep_create\fR(3DAT), \fBdat_ep_recv_query\fR(3DAT), +\fBdat_srq_create\fR(3DAT), \fBdat_srq_free\fR(3DAT), +\fBdat_srq_post_recv\fR(3DAT), \fBdat_srq_query\fR(3DAT), +\fBdat_srq_resize\fR(3DAT), \fBdat_srq_set_lw\fR(3DAT), \fBlibdat\fR(3LIB), +\fBattributes\fR(5) diff --git a/usr/src/man/man3dat/dat_evd_clear_unwaitable.3dat b/usr/src/man/man3dat/dat_evd_clear_unwaitable.3dat new file mode 100644 index 0000000000..f3c2945132 --- /dev/null +++ b/usr/src/man/man3dat/dat_evd_clear_unwaitable.3dat @@ -0,0 +1,95 @@ +'\" te +.\" This manual page is derived from the DAT/uDAPL 1.2 specification. +.\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH dat_evd_clear_unwaitable 3DAT "16 Jul 2004" "SunOS 5.11" "Direct Access Transport Library Functions" +.SH NAME +dat_evd_clear_unwaitable \- transition the Event Dispatcher into a waitable +state +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ldat\fR [ \fIlibrary\fR\&.\|.\|. ] +#include <\fBdat/udat.h\fR> + +DAT_RETURN + dat_evd_clear_unwaitable( + IN DAT_EVD_HANDLE \fIevd_handle\fR + ) +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIevd_handle\fR\fR +.ad +.RS 14n +.rt +Handle for an instance of Event Dispatcher. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBdat_evd_clear_unwaitable()\fR transitions the Event Dispatcher into a +waitable state. In this state, calls to \fBdat_evd_wait\fR(3DAT) are permitted +on the EVD. The actual state of the Event Dispatcher is accessible through +\fBdat_evd_query\fR(3DAT) and is \fBDAT_EVD_WAITABLE\fR after the return of +this operation. +.sp +.LP +This call does not affect a CNO associated with this EVD at all. Events +arriving on the EVD after it is set waitable still trigger the CNO (if +appropriate), and can be retrieved with \fBdat_evd_dequeue\fR(3DAT). +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBDAT_SUCCESS\fR\fR +.ad +.RS 22n +.rt +The operation was successful. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_HANDLE\fR\fR +.ad +.RS 22n +.rt +The \fIevd_handle\fR parameter is invalid. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard: uDAPL, 1.1, 1.2 +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBdat_evd_dequeue\fR(3DAT), \fBdat_evd_query\fR(3DAT), +\fBdat_evd_set_unwaitable\fR(3DAT), \fBdat_evd_wait\fR(3DAT), +\fBlibdat\fR(3LIB), \fBattributes\fR(5) diff --git a/usr/src/man/man3dat/dat_evd_dequeue.3dat b/usr/src/man/man3dat/dat_evd_dequeue.3dat new file mode 100644 index 0000000000..7680b3a7ad --- /dev/null +++ b/usr/src/man/man3dat/dat_evd_dequeue.3dat @@ -0,0 +1,199 @@ +'\" te +.\" This manual page is derived from the DAT/uDAPL 1.2 specification. +.\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH dat_evd_dequeue 3DAT "16 Jul 2004" "SunOS 5.11" "Direct Access Transport Library Functions" +.SH NAME +dat_evd_dequeue \- remove the first event from the Event Dispatcher event queue +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ldat\fR [ \fIlibrary\fR\&.\|.\|. ] +#include <\fBdat/udat.h\fR> + +DAT_RETURN + dat_evd_dequeue( + IN DAT_EVD_HANDLE \fIevd_handle\fR, + OUT DAT_EVENT *\fIevent\fR + ) +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIevd_handle\fR\fR +.ad +.RS 14n +.rt +Handle for an instance of the Event Dispatcher. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIevent\fR\fR +.ad +.RS 14n +.rt +Pointer to the Consumer-allocated structure that Provider fills with the event +data. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBdat_evd_dequeue()\fR function removes the first event from the Event +Dispatcher event queue and fills the Consumer allocated \fIevent\fR structure +with event data. The first element in this structure provides the type of the +event; the rest provides the event-type-specific parameters. The Consumer +should allocate an \fIevent\fR structure big enough to hold any event that the +Event Dispatcher can deliver. +.sp +.LP +For all events the Provider fills the \fBdat_event\fR that the Consumer +allocates. So for all events, all fields of \fBdat_event\fR are OUT from the +Consumer point of view. For \fBDAT_CONNECTION_REQUEST_EVENT\fR, the Provider +creates a Connection Request whose \fIcr_handle\fR is returned to the Consumer +in \fBDAT_CR_ARRIVAL_EVENT_DATA\fR. That object is destroyed by the Provider as +part of \fBdat_cr_accept\fR(3DAT), \fBdat_cr_reject\fR(3DAT), or +\fBdat_cr_handoff\fR(3DAT). The Consumer should not use \fIcr_handle\fR or any +of its parameters, including \fIprivate_data\fR, after one of these operations +destroys the Connection Request. +.sp +.LP +For \fBDAT_CONNECTION_EVENT_ESTABLISHED\fR for the Active side of connection +establishment, the Provider returns the pointer for \fIprivate_data\fR and the +\fIprivate_data_size\fR. For the Passive side, +\fBDAT_CONNECTION_EVENT_ESTABLISHED\fR event \fIprivate_data\fR is not defined +and \fIprivate_data_size\fR returns zero. The Provider is responsible for the +memory allocation and deallocation for \fIprivate_data\fR. The +\fIprivate_data\fR is valid until the Active side Consumer destroys the +connected Endpoint (\fBdat_ep_free\fR(3DAT)), or transitions the Endpoint into +Unconnected state so it is ready for the next connection. So while the Endpoint +is in Connected, Disconnect Pending, or Disconnected state, the private_data of +\fBDAT_CONNECTION_REQUEST_EVENT\fR is still valid for Active side Consumers. +.sp +.LP +Provider must pass to the Consumer the entire Private Data that the remote +Consumer provided for \fBdat_ep_connect\fR(3DAT), +\fBdat_ep_dup_connect\fR(3DAT), and \fBdat_cr_accept()\fR. If the Consumer +provides more data than the Provider and Transport can support (larger than IA +Attribute of \fImax_private_data_size\fR), \fBDAT_INVALID_PARAMETER\fR is +returned for that operation. +.sp +.LP +The returned event that was posted from an Event Stream guarantees Consumers +that all events that were posted from the same Event Stream prior to the +returned event were already returned to a Consumer directly through a +\fBdat_evd_dequeue()\fR or \fBdat_evd_wait\fR(3DAT) operation. +.sp +.LP +The ordering of events dequeued by overlapping calls to \fBdat_evd_wait()\fR or +\fBdat_evd_dequeue()\fR is not specified. +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBDAT_SUCCESS\fR\fR +.ad +.RS 22n +.rt +The operation was successful. An event was returned to a Consumer. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_HANDLE\fR\fR +.ad +.RS 22n +.rt +Invalid DAT handle; evd_handle is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_QUEUE_EMPTY\fR\fR +.ad +.RS 22n +.rt +There are no entries on the Event Dispatcher queue. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_STATE\fR\fR +.ad +.RS 22n +.rt +One of the parameters was invalid for this operation. There is already a waiter +on the EVD. +.RE + +.SH USAGE +.sp +.LP +No matter how many contexts attempt to dequeue from an Event Dispatcher, each +event is delivered exactly once. However, which Consumer receives which event +is not defined. The Provider is not obligated to provide the first caller the +first event unless it is the only caller. The Provider is not obligated to +ensure that the caller receiving the first event executes earlier than contexts +receiving later events. +.sp +.LP +Preservation of event ordering within an Event Stream is an important feature +of the DAT Event Model. Consumers are cautioned that overlapping or concurrent +calls to \fBdat_evd_dequeue()\fR from multiple contexts can undermine this +ordering information. After multiple contexts are involved, the Provider can +only guarantee the order that it delivers events into the EVD. The Provider +cannot guarantee that they are processed in the correct order. +.sp +.LP +Although calling \fBdat_evd_dequeue()\fR does not cause a context switch, the +Provider is under no obligation to prevent one. A context could successfully +complete a dequeue, and then reach the end of its timeslice, before returning +control to the Consumer code. Meanwhile, a context receiving a later event +could be executing. +.sp +.LP +The Event ordering is preserved when dequeueing is serialized. Potential +Consumer serialization methods include, but are not limited to, performing all +dequeueing from a single context or protecting dequeueing by way of lock or +semaphore. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard: uDAPL, 1.1, 1.2 +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBdat_cr_accept\fR(3DAT), \fBdat_cr_handoff\fR(3DAT), +\fBdat_cr_reject\fR(3DAT), \fBdat_ep_connect\fR(3DAT), +\fBdat_ep_dup_connect\fR(3DAT), \fBdat_ep_free\fR(3DAT), +\fBdat_evd_wait\fR(3DAT)\fBlibdat\fR(3LIB), \fBattributes\fR(5) diff --git a/usr/src/man/man3dat/dat_evd_disable.3dat b/usr/src/man/man3dat/dat_evd_disable.3dat new file mode 100644 index 0000000000..f680031c8f --- /dev/null +++ b/usr/src/man/man3dat/dat_evd_disable.3dat @@ -0,0 +1,92 @@ +'\" te +.\" This manual page is derived from the DAT/uDAPL 1.2 specification. +.\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH dat_evd_disable 3DAT "16 Jul 2004" "SunOS 5.11" "Direct Access Transport Library Functions" +.SH NAME +dat_evd_disable \- disable the Event Dispatcher +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ldat\fR [ \fIlibrary\fR\&.\|.\|. ] +#include <\fBdat/udat.h\fR> + +DAT_RETURN + dat_evd_disable( + IN DAT_EVD_HANDLE \fIevd_handle\fR + ) +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIevd_handle\fR\fR +.ad +.RS 14n +.rt +Handle for an instance of Event Dispatcher. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBdat_evd_disable()\fR function disables the Event Dispatcher so that the +arrival of an event does not affect the associated CNO. +.sp +.LP +If the Event Dispatcher is already disabled, this operation is no-op. +.sp +.LP +Events arriving on this EVD might cause waiters on the associated CNO to be +awakened after the return of this routine because an unblocking a CNO waiter is +already "in progress" at the time this routine is called or returned. +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBDAT_SUCCESS\fR\fR +.ad +.RS 22n +.rt +The operation was successful. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_HANDLE\fR\fR +.ad +.RS 22n +.rt +The \fIevd_handle\fR parameter is invalid. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard: uDAPL, 1.1, 1.2 +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBdat_evd_enable\fR(3DAT), \fBlibdat\fR(3LIB), \fBattributes\fR(5) diff --git a/usr/src/man/man3dat/dat_evd_enable.3dat b/usr/src/man/man3dat/dat_evd_enable.3dat new file mode 100644 index 0000000000..5baec69db0 --- /dev/null +++ b/usr/src/man/man3dat/dat_evd_enable.3dat @@ -0,0 +1,90 @@ +'\" te +.\" This manual page is derived from the DAT/uDAPL 1.2 specification. +.\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH dat_evd_enable 3DAT "16 Jul 2004" "SunOS 5.11" "Direct Access Transport Library Functions" +.SH NAME +dat_evd_enable \- enable the Event Dispatcher +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ldat\fR [ \fIlibrary\fR\&.\|.\|. ] +#include <\fBdat/udat.h\fR> + +DAT_RETURN + dat_evd_enable( + IN DAT_EVD_HANDLE \fIevd_handle\fR + ) +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIevd_handle\fR\fR +.ad +.RS 14n +.rt +Handle for an instance of Event Dispatcher. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBdat_evd_enable()\fR function enables the Event Dispatcher so that the +arrival of an event can trigger the associated CNO. The enabling and disabling +EVD has no effect on direct waiters on the EVD. However, direct waiters +effectively take ownership of the EVD, so that the specified CNO is not +triggered even if is enabled. +.sp +.LP +If the Event Dispatcher is already enabled, this operation is no-op. +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBDAT_SUCCESS\fR\fR +.ad +.RS 22n +.rt +The operation was successful. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_HANDLE\fR\fR +.ad +.RS 22n +.rt +The \fIevd_handle\fR parameter is invalid. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard: uDAPL, 1.1, 1.2 +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBdat_evd_disable\fR(3DAT), \fBlibdat\fR(3LIB), \fBattributes\fR(5) diff --git a/usr/src/man/man3dat/dat_evd_free.3dat b/usr/src/man/man3dat/dat_evd_free.3dat new file mode 100644 index 0000000000..c9c94760a4 --- /dev/null +++ b/usr/src/man/man3dat/dat_evd_free.3dat @@ -0,0 +1,118 @@ +'\" te +.\" This manual page is derived from the DAT/uDAPL 1.2 specification. +.\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH dat_evd_free 3DAT "16 Jul 2004" "SunOS 5.11" "Direct Access Transport Library Functions" +.SH NAME +dat_evd_free \- destroy an instance of the Event Dispatcher +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ldat\fR [ \fIlibrary\fR\&.\|.\|. ] +#include <\fBdat/udat.h\fR> + +DAT_RETURN + dat_evd_free ( + IN DAT_EVD_HANDLE \fIevd_handle\fR + ) +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIevd_handle\fR\fR +.ad +.RS 14n +.rt +Handle for an instance of the Event Dispatcher. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBdat_evd_free()\fR function destroys a specified instance of the Event +Dispatcher. +.sp +.LP +All events on the queue of the specified Event Dispatcher are lost. The +destruction of the Event Dispatcher instance does not have any effect on any +DAT Objects that originated an Event Stream that had fed events to the Event +Dispatcher instance. There should be no event streams feeding the Event +Dispatcher and no threads blocked on the Event Dispatcher when the EVD is being +closed as at the time when it was created. +.sp +.LP +Use of the handle of the destroyed Event Dispatcher in any consequent operation +fails. +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBDAT_SUCCESS\fR\fR +.ad +.RS 22n +.rt +The operation was successful. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_HANDLE\fR\fR +.ad +.RS 22n +.rt +The \fIevd_handle\fR parameter is invalid +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_STATE\fR\fR +.ad +.RS 22n +.rt +Invalid parameter. There are Event Streams associated with the Event Dispatcher +feeding it. +.RE + +.SH USAGE +.sp +.LP +Consumers are advised to destroy all Objects that originate Event Streams that +feed an instance of the Event Dispatcher before destroying it. An exception to +this rule is Event Dispatchers of an IA. +.sp +.LP +Freeing an IA automatically destroys all Objects associated with it directly +and indirectly, including Event Dispatchers. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard: uDAPL, 1.1, 1.2 +_ +MT-LevelUnsafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBlibdat\fR(3LIB), \fBattributes\fR(5) diff --git a/usr/src/man/man3dat/dat_evd_modify_cno.3dat b/usr/src/man/man3dat/dat_evd_modify_cno.3dat new file mode 100644 index 0000000000..f130a494ba --- /dev/null +++ b/usr/src/man/man3dat/dat_evd_modify_cno.3dat @@ -0,0 +1,128 @@ +'\" te +.\" This manual page is derived from the DAT/uDAPL 1.2 specification. +.\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH dat_evd_modify_cno 3DAT "16 Jul 2004" "SunOS 5.11" "Direct Access Transport Library Functions" +.SH NAME +dat_evd_modify_cno \- change the associated CNO for the Event Dispatcher +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ldat\fR [ \fIlibrary\fR\&.\|.\|. ] +#include <\fBdat/udat.h\fR> + +DAT_RETURN + dat_evd_modify_cno ( + IN DAT_EVD_HANDLE \fIevd_handle\fR, + IN DAT_CNO_HANDLE \fIcno_handle\fR + ) +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIevd_handle\fR\fR +.ad +.RS 14n +.rt +Handle for an instance of the Event Dispatcher. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcno_handle\fR\fR +.ad +.RS 14n +.rt +Handle for a CNO. The value of \fBDAT_NULL_HANDLE\fR specifies no CNO. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBdat_evd_modify_cno()\fR function changes the associated CNO for the +Event Dispatcher. +.sp +.LP +A Consumer can specify the value of \fBDAT_HANDLE_NULL\fR for \fIcno_handle\fR +to associate not CNO with the Event Dispatcher instance. +.sp +.LP +Upon completion of the \fBdat_evd_modify_cno()\fR operation, the passed IN new +CNO is used for notification. During the operation, an event arrival can be +delivered to the old or new CNO. If Notification is generated by EVD, it is +delivered to the new or old CNO. +.sp +.LP +If the EVD is enabled at the time \fBdat_evd_modify_cno()\fR is called, the +Consumer must be prepared to collect a notification event on the EVD's old CNO +as well as the new one. Checking immediately prior to calling +\fBdat_evd_modify_cno()\fR is not adequate. A notification could have been +generated after the prior check and before the completion of the change. +.sp +.LP +The Consumer can avoid the risk of missed notifications either by temporarily +disabling the EVD, or by checking the prior CNO after invoking this operation. +The Consumer can disable EVD before a \fBdat_evd_modify_cno()\fR call and +enable it afterwards. This ensures that any notifications from the EVD are +delivered to the new CNO only. +.sp +.LP +If this function is used to disassociate a CNO from the EVD, events arriving on +this EVD might cause waiters on that CNO to awaken after returning from this +routine because of unblocking a CNO waiter already "in progress" at the time +this routine is called. If this is the case, the events causing that unblocking +are present on the EVD upon return from the \fBdat_evd_modify_cno()\fR call and +can be dequeued at that time +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBDAT_SUCCESS\fR\fR +.ad +.RS 22n +.rt +The operation was successful. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_HANDLE\fR\fR +.ad +.RS 22n +.rt +Invalid DAT handle. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard: uDAPL, 1.1, 1.2 +_ +MT-LevelUnsafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBlibdat\fR(3LIB), \fBattributes\fR(5) diff --git a/usr/src/man/man3dat/dat_evd_post_se.3dat b/usr/src/man/man3dat/dat_evd_post_se.3dat new file mode 100644 index 0000000000..258af85bd3 --- /dev/null +++ b/usr/src/man/man3dat/dat_evd_post_se.3dat @@ -0,0 +1,135 @@ +'\" te +.\" This manual page is derived from the DAT/uDAPL 1.2 specification. +.\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH dat_evd_post_se 3DAT "16 Jul 2004" "SunOS 5.11" "Direct Access Transport Library Functions" +.SH NAME +dat_evd_post_se \- post Software event to the Event Dispatcher event queue +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ldat\fR [ \fIlibrary\fR\&.\|.\|. ] +#include <\fBdat/udat.h\fR> + +DAT_RETURN + dat_evd_post_se( + IN DAT_EVD_HANDLE \fIevd_handle\fR, + IN const DAT_EVENT *\fIevent\fR + ) +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIevd_handle\fR\fR +.ad +.RS 14n +.rt +Handle for an instance of the Event Dispatcher +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIevent\fR\fR +.ad +.RS 14n +.rt +A pointer to a Consumer created Software Event. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBdat_evd_post_se()\fR function posts Software events to the Event +Dispatcher event queue. This is analogous to event arrival on the Event +Dispatcher software Event Stream. The \fIevent\fR that the Consumer provides +adheres to the event format as defined in <\fBdat.h\fR>. The first element in +the \fIevent\fR provides the type of the event (\fBDAT_EVENT_TYPE_SOFTWARE\fR); +the rest provide the event-type-specific parameters. These parameters are +opaque to a Provider. Allocation and release of the memory referenced by the +\fIevent\fR pointer in a software event are the Consumer's responsibility. +.sp +.LP +There is no ordering between events from different Event Streams. All the +synchronization issues between multiple Consumer contexts trying to post events +to an Event Dispatcher instance simultaneously are left to a Consumer. +.sp +.LP +If the event queue is full, the operation is completed unsuccessfully and +returns \fBDAT_QUEUE_FULL\fR. The \fIevent\fR is not queued. The queue overflow +condition does takes place and, therefore, the asynchronous Event Dispatcher is +not effected. +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBDAT_SUCCESS\fR\fR +.ad +.RS 25n +.rt +The operation was successful. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_HANDLE\fR\fR +.ad +.RS 25n +.rt +The \fIevd_handle\fR parameter is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_PARAMETER\fR\fR +.ad +.RS 25n +.rt +The \fIevent\fR parameter is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_QUEUE_FULL\fR\fR +.ad +.RS 25n +.rt +The Event Dispatcher queue is full. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard: uDAPL, 1.1, 1.2 +_ +MT-LevelUnsafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBlibdat\fR(3LIB), \fBattributes\fR(5) diff --git a/usr/src/man/man3dat/dat_evd_query.3dat b/usr/src/man/man3dat/dat_evd_query.3dat new file mode 100644 index 0000000000..63e492249f --- /dev/null +++ b/usr/src/man/man3dat/dat_evd_query.3dat @@ -0,0 +1,127 @@ +'\" te +.\" This manual page is derived from the DAT/uDAPL 1.2 specification. +.\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH dat_evd_query 3DAT "16 Jul 2004" "SunOS 5.11" "Direct Access Transport Library Functions" +.SH NAME +dat_evd_query \- provide parameters of the Event Dispatcher, +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ldat\fR [ \fIlibrary\fR\&.\|.\|. ] +#include <\fBdat/udat.h\fR> + +DAT_RETURN + dat_evd_query ( + IN DAT_EVD_HANDLE \fIevd_handle\fR, + IN DAT_EVD_PARAM_MASK \fIevd_param_mask\fR, + OUT DAT_EVD_PARAM *\fIevd_param\fR + ) +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIevd_handle\fR\fR +.ad +.RS 18n +.rt +Handle for an instance of Event Dispatcher. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIevd_param_mask\fR\fR +.ad +.RS 18n +.rt +Mask for EVD parameters +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIevd_param\fR\fR +.ad +.RS 18n +.rt +Pointer to a Consumer-allocated structure that the Provider fills for +Consumer-requested parameters. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBdat_evd_query()\fR function provides to the Consumer parameters of the +Event Dispatcher, including the state of the EVD (enabled/disabled). The +Consumer passes in a pointer to the Consumer-allocated structures for EVD +parameters that the Provider fills. +.sp +.LP +The \fIevd_param_mask\fR parameter allows Consumers to specify which parameters +to query. The Provider returns values for \fIevd_param_mask\fR requested +parameters. The Provider can return values for any of the other parameters. +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBDAT_SUCCESS\fR\fR +.ad +.RS 25n +.rt +The operation was successful. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_HANDLE\fR\fR +.ad +.RS 25n +.rt +The \fIevd_handle\fR parameter is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_PARAMETER\fR\fR +.ad +.RS 25n +.rt +The \fIevd_param_mask\fR parameter is invalid. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard: uDAPL, 1.1, 1.2 +_ +MT-LevelUnsafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBlibdat\fR(3LIB), \fBattributes\fR(5) diff --git a/usr/src/man/man3dat/dat_evd_resize.3dat b/usr/src/man/man3dat/dat_evd_resize.3dat new file mode 100644 index 0000000000..c97665ef0a --- /dev/null +++ b/usr/src/man/man3dat/dat_evd_resize.3dat @@ -0,0 +1,141 @@ +'\" te +.\" This manual page is derived from the DAT/uDAPL 1.2 specification. +.\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH dat_evd_resize 3DAT "16 Jul 2004" "SunOS 5.11" "Direct Access Transport Library Functions" +.SH NAME +dat_evd_resize \- modify the size of the event queue of Event Dispatcher +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ldat\fR [ \fIlibrary\fR\&.\|.\|. ] +#include <\fBdat/udat.h\fR> + +DAT_RETURN + dat_evd_resize( + IN DAT_EVD_HANDLE \fIevd_handle\fR, + IN DAT_COUNT \fIevd_min_qlen\fR + ) +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIevd_handle\fR\fR +.ad +.RS 16n +.rt +Handle for an instance of Event Dispatcher. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIevd_min_qlen\fR\fR +.ad +.RS 16n +.rt +New number of events the Event Dispatcher event queue must hold. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBdat_evd_resize()\fR function modifies the size of the event queue of +Event Dispatcher. +.sp +.LP +Resizing of Event Dispatcher event queue should not cause any incoming or +current events on the event queue to be lost. If the number of entries on the +event queue is larger then the requested evd_min_qlen\fI\fR, the operation can +return \fBDAT_INVALID_STATE\fR and not change an instance of Event Dispatcher +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBDAT_SUCCESS\fR\fR +.ad +.RS 30n +.rt +The operation was successful. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_HANDLE\fR\fR +.ad +.RS 30n +.rt +The \fIevd_handle\fR parameter is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_PARAMETER\fR\fR +.ad +.RS 30n +.rt +The \fIevd_min_qlen\fR parameter is invalid +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INSUFFICIENT_RESOURCES\fR\fR +.ad +.RS 30n +.rt +The operation failed due to resource limitations +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_STATE\fR\fR +.ad +.RS 30n +.rt +Invalid parameter. The number of entries on the event queue of the Event +Dispatcher exceeds the requested event queue length. +.RE + +.SH USAGE +.sp +.LP +This operation is useful when the potential number of events that could be +placed on the event queue changes dynamically. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard: uDAPL, 1.1, 1.2 +_ +MT-LevelUnsafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBlibdat\fR(3LIB), \fBattributes\fR(5) diff --git a/usr/src/man/man3dat/dat_evd_set_unwaitable.3dat b/usr/src/man/man3dat/dat_evd_set_unwaitable.3dat new file mode 100644 index 0000000000..72e38b2133 --- /dev/null +++ b/usr/src/man/man3dat/dat_evd_set_unwaitable.3dat @@ -0,0 +1,99 @@ +'\" te +.\" This manual page is derived from the DAT/uDAPL 1.2 specification. +.\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH dat_evd_set_unwaitable 3DAT "16 Jul 2004" "SunOS 5.11" "Direct Access Transport Library Functions" +.SH NAME +dat_evd_set_unwaitable \- transition the Event Dispatcher into an unwaitable +state +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ldat\fR [ \fIlibrary\fR\&.\|.\|. ] +#include <\fBdat/udat.h\fR> + +DAT_RETURN + dat_evd_set_unwaitable( + IN DAT_EVD_HANDLE \fIevd_handle\fR + ) +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIevd_handle\fR\fR +.ad +.RS 14n +.rt +Handle for an instance of Event Dispatcher. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBdat_evd_set_unwaitable()\fR transitions the Event Dispatcher into an +unwaitable state. In this state, calls to \fBdat_evd_wait\fR(3DAT) return +synchronously with a \fBDAT_INVALID_STATE\fR error, and threads already blocked +in \fBdat_evd_wait()\fR are awakened and return with a \fBDAT_INVALID_STATE\fR +error without any further action by the Consumer. The actual state of the Event +Dispatcher is accessible through \fBdat_evd_query\fR(3DAT) and is +\fBDAT_EVD_UNWAITABLE\fR after the return of this operation. +.sp +.LP +This call does not affect a CNO associated with this EVD at all. Events +arriving on the EVD after it is set unwaitable still trigger the CNO (if +appropriate), and can be retrieved with \fBdat_evd_dequeue\fR(3DAT). Because +events can arrive normally on the EVD, the EVD might overflow; the Consumer is +expected to protect against this possibility. +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBDAT_SUCCESS\fR\fR +.ad +.RS 22n +.rt +The operation was successful. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_HANDLE\fR\fR +.ad +.RS 22n +.rt +The \fIevd_handle\fR parameter is invalid. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard: uDAPL, 1.1, 1.2 +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBdat_evd_clear_unwaitable\fR(3DAT), \fBdat_evd_dequeue\fR(3DAT), +\fBdat_evd_query\fR(3DAT), \fBdat_evd_wait\fR(3DAT), \fBlibdat\fR(3LIB), +\fBattributes\fR(5) diff --git a/usr/src/man/man3dat/dat_evd_wait.3dat b/usr/src/man/man3dat/dat_evd_wait.3dat new file mode 100644 index 0000000000..ebe9216dc4 --- /dev/null +++ b/usr/src/man/man3dat/dat_evd_wait.3dat @@ -0,0 +1,325 @@ +'\" te +.\" This manual page is derived from the DAT/uDAPL 1.2 specification. +.\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH dat_evd_wait 3DAT "16 Jul 2004" "SunOS 5.11" "Direct Access Transport Library Functions" +.SH NAME +dat_evd_wait \- remove first event from the Event Dispatcher event queue +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ldat\fR [ \fIlibrary\fR\&.\|.\|. ] +#include <\fBdat/udat.h\fR> + +DAT_RETURN + dat_evd_wait( + IN DAT_EVD_HANDLE \fIevd_handle\fR, + IN DAT_TIMEOUT \fItimeout\fR, + IN DAT_COUNT \fIthreshold\fR, + OUT DAT_EVENT *\fIevent\fR, + OUT DAT_COUNT *\fInmore\fR + ) +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIevd_handle\fR\fR +.ad +.RS 14n +.rt +Handle for an instance of the Event Dispatcher. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fItimeout\fR\fR +.ad +.RS 14n +.rt +The duration of time, in microseconds, that the Consumer is willing to wait for +the event. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIthreshold\fR\fR +.ad +.RS 14n +.rt +The number of events that should be on the EVD queue before the operation +should return with \fBDAT_SUCCESS\fR. The threshold must be at least 1. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIevent\fR\fR +.ad +.RS 14n +.rt +Pointer to the Consumer-allocated structure that the Provider fills with the +event data. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fInmore\fR\fR +.ad +.RS 14n +.rt +The snapshot of the queue size at the time of the operation return. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBdat_evd_wait()\fR function removes the first event from the Event +Dispatcher event queue and fills the Consumer-allocated \fIevent\fR structure +with event data. The first element in this structure provides the type of the +event; the rest provides the event type-specific parameters. The Consumer +should allocate an event structure big enough to hold any event that the Event +Dispatcher can deliver. +.sp +.LP +For all events, the Provider fills the \fIdat_event\fR that the Consumer +allocates. Therefore, for all events, all fields of \fIdat_event\fR are OUT +from the Consumer point of view. For \fBDAT_CONNECTION_REQUEST_EVENT\fR, the +Provider creates a Connection Request whose \fIcr_handle\fR is returned to the +Consumer in \fBDAT_CR_ARRIVAL_EVENT_DATA\fR. That object is destroyed by the +Provider as part of \fBdat_cr_accept\fR(3DAT), \fBdat_cr_reject\fR(3DAT), or +\fBdat_cr_handoff\fR(3DAT). The Consumer should not use \fIcr_handle\fR or any +of its parameters, including \fIprivate_data\fR, after one of these operations +destroys the Connection Request. +.sp +.LP +For \fBDAT_CONNECTION_EVENT_ESTABLISHED\fR for the Active side of connection +establishment, the Provider returns the pointer for \fIprivate_data\fR and the +\fIprivate_data_size\fR. For the Passive side, +\fBDAT_CONNECTION_EVENT_ESTABLISHED\fR event \fIprivate_data\fR is not defined +and \fIprivate_data_size\fR returns zero. The Provider is responsible for the +memory allocation and deallocation for \fIprivate_data\fR. The +\fIprivate_data\fR is valid until the Active side Consumer destroys the +connected Endpoint (\fBdat_ep_free\fR(3DAT)), or transitions the Endpoint into +Unconnected state so it is ready for the next connection. So, while the +Endpoint is in Connected, Disconnect Pending, or Disconnected state, the +\fIprivate_data\fR of \fBDAT_CONNECTION_REQUEST_EVENT\fR is still valid for +Active side Consumers. +.sp +.LP +Provider must pass to the Consumer the entire Private Data that the remote +Consumer provided for \fBdat_ep_connect\fR(3DAT), +\fBdat_ep_dup_connect\fR(3DAT), and \fBdat_cr_accept()\fR. If the Consumer +provides more data than the Provider and Transport can support (larger than IA +Attribute of \fImax_private_data_size\fR), \fBDAT_INVALID_PARAMETER\fR is +returned for that operation. +.sp +.LP +A Consumer that blocks performing a \fBdat_evd_wait()\fR on an Event Dispatcher +effectively takes exclusive ownership of that Event Dispatcher. Any other +dequeue operation (\fBdat_evd_wait()\fR or \fBdat_evd_dequeue\fR(3DAT)) on the +Event Dispatcher is rejected with a \fBDAT_INVALID_STATE\fR error code. +.sp +.LP +The CNO associated with the \fBevd_handle()\fR is not triggered upon event +arrival if there is a Consumer blocked on \fBdat_evd_wait()\fR on this Event +Dispatcher. +.sp +.LP +The \fItimeout\fR allows the Consumer to restrict the amount of time it is +blocked waiting for the event arrival. The value of \fBDAT_TIMEOUT_INFINITE\fR +indicates that the Consumer waits indefinitely for an event arrival. Consumers +should use extreme caution in using this value. +.sp +.LP +When \fItimeout\fR value is reached and the number of events on the EVD queue +is below the \fIthreshold\fR value, the operation fails and returns +\fBDAT_TIMEOUT_EXPIRED\fR. In this case, no event is dequeued from the EVD and +the return value for the \fIevent\fR argument is undefined. However, an +\fInmore\fR value is returned that specifies the snapshot of the number of the +events on the EVD queue that is returned. +.sp +.LP +The \fIthreshold\fR allows the Consumer to wait for a requested number of event +arrivals prior to waking the Consumer. If the value of the \fIthreshold\fR is +larger than the Event Dispatcher queue length, the operation fails with the +return \fBDAT_INVALID_PARAMETER\fR. If a non-positive value is specified for +\fIthreshold\fR, the operation fails and returns \fBDAT_INVALID_PARAMETER\fR. +.sp +.LP +If EVD is used by an Endpoint for a DTO completion stream that is configured +for a Consumer-controlled event Notification +(\fBDAT_COMPLETION_UNSIGNALLED_FLAG\fR or +\fBDAT_COMPLETION_SOLICITED_WAIT_FLAG\fR for Receive Completion Type for +Receives; \fBDAT_COMPLETION_UNSIGNALLED_FLAG\fR for Request Completion Type for +Send, RDMA Read, RDMA Write and RMR Bind), the \fIthreshold\fR value must be 1. +An attempt to specify some other value for \fIthreshold\fR for this case +results in \fBDAT_INVALID_STATE\fR. +.sp +.LP +The returned value of \fInmore\fR indicates the number of events left on the +Event Dispatcher queue after the \fBdat_evd_wait()\fR returns. If the operation +return value is \fBDAT_SUCCESS\fR, the \fInmore\fR value is at least the value +of (\fIthreshold\fR -1). Notice that \fInmore\fR is only a snapshot and the +number of events can be changed by the time the Consumer tries to dequeue +events with \fBdat_evd_wait()\fR with timeout of zero or with +\fBdat_evd_dequeue()\fR. +.sp +.LP +For returns other than \fBDAT_SUCCESS\fR, \fBDAT_TIMEOUT_EXPIRED\fR, and +\fBDAT_INTERRUPTED_CALL\fR, the returned value of \fInmore\fR is undefined. +.sp +.LP +The returned event that was posted from an Event Stream guarantees Consumers +that all events that were posted from the same Event Stream prior to the +returned event were already returned to a Consumer directly through a +\fBdat_evd_dequeue()\fR or \fBdat_evd_wait()\fR operation. +.sp +.LP +If the return value is neither \fBDAT_SUCCESS\fR nor \fBDAT_TIMEOUT_EXPIRED\fR, +then returned values of \fInmore\fR and event are undefined. If the return +value is \fBDAT_TIMEOUT_EXPIRED\fR, then the return value of event is +undefined, but the return value of \fInmore\fR is defined. If the return value +is \fBDAT_SUCCESS\fR, then the return values of \fInmore\fR and \fIevent\fR are +defined. +.sp +.LP +If this function is called on an EVD in an unwaitable state, or if +\fBdat_evd_set_unwaitable\fR(3DAT) is called on an EVD on which a thread is +blocked in this function, the function returns with \fBDAT_INVALID_STATE\fR. +.sp +.LP +The ordering of events dequeued by overlapping calls to \fBdat_evd_wait()\fR or +\fBdat_evd_dequeue()\fR is not specified. +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBDAT_SUCCESS\fR\fR +.ad +.RS 25n +.rt +The operation was successful. An event was returned to a Consumer. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_HANDLE\fR\fR +.ad +.RS 25n +.rt +The \fIevd_handle\fR parameter is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_PARAMETER\fR\fR +.ad +.RS 25n +.rt +The \fItimeout\fR or \fIthreshold\fR parameter is invalid. For example, +\fIthreshold\fR is larger than the EVD's \fIevd_min_qlen\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_ABORT\fR\fR +.ad +.RS 25n +.rt +The operation was aborted because IA was closed or EVD was destroyed +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_STATE\fR\fR +.ad +.RS 25n +.rt +One of the parameters was invalid for this operation. There is already a waiter +on the EVD, or the EVD is in an unwaitable state. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_TIMEOUT_EXPIRED\fR\fR +.ad +.RS 25n +.rt +The operation timed out. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INTERRUPTED_CALL\fR\fR +.ad +.RS 25n +.rt +The operation was interrupted by a signal. +.RE + +.SH USAGE +.sp +.LP +Consumers should be cautioned against using threshold combined with infinite +\fItimeout\fR. +.sp +.LP +Consumers should not mix different models for control of unblocking a waiter. +If the Consumer uses Notification Suppression or Solicited Wait to control the +Notification events for unblocking a waiter, the \fIthreshold\fR must be set to +1. If the Consumer uses \fIthreshold\fR to control when a waiter is unblocked, +\fBDAT_COMPLETION_UNSIGNALLED_FLAG\fR locally and +\fBDAT_COMPLETION_SOLICITED_WAIT\fR remotely shall not be used. By default, all +completions are Notification events. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard: uDAPL, 1.1, 1.2 +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBdat_cr_accept\fR(3DAT), \fBdat_cr_handoff\fR(3DAT), +\fBdat_cr_reject\fR(3DAT), \fBdat_ep_connect\fR(3DAT), +\fBdat_ep_dup_connect\fR(3DAT),\fBdat_ep_free\fR(3DAT), +\fBdat_evd_dequeue\fR(3DAT), \fBdat_evd_set_unwaitable\fR(3DAT), +\fBlibdat\fR(3LIB), \fBattributes\fR(5) diff --git a/usr/src/man/man3dat/dat_get_consumer_context.3dat b/usr/src/man/man3dat/dat_get_consumer_context.3dat new file mode 100644 index 0000000000..f5b62062e5 --- /dev/null +++ b/usr/src/man/man3dat/dat_get_consumer_context.3dat @@ -0,0 +1,102 @@ +'\" te +.\" This manual page is derived from the DAT/uDAPL 1.2 specification. +.\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH dat_get_consumer_context 3DAT "16 Jul 2004" "SunOS 5.11" "Direct Access Transport Library Functions" +.SH NAME +dat_get_consumer_context \- get Consumer context +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ldat\fR [ \fIlibrary\fR\&.\|.\|. ] +#include <\fBdat/udat.h\fR> + +DAT_RETURN + dat_get_consumer_context ( + IN DAT_HANDLE \fIdat_handle\fR, + OUT DAT_CONTEXT *\fIcontext\fR + ) +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIdat_handle\fR\fR +.ad +.RS 14n +.rt +Handle for a DAT Object associated with \fIcontext\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcontext\fR\fR +.ad +.RS 14n +.rt +Pointer to Consumer-allocated storage where the current value of the +\fIdat_handle\fR context will be stored. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBdat_get_consumer_context()\fR function gets the Consumer context from +the specified \fIdat_handle\fR. The \fIdat_handle\fR can be one of the +following handle types: \fBDAT_IA_HANDLE\fR, \fBDAT_EP_HANDLE\fR, +\fBDAT_EVD_HANDLE\fR, \fBDAT_CR_HANDLE\fR, \fBDAT_RSP_HANDLE\fR, +\fBDAT_PSP_HANDLE\fR, \fBDAT_PZ_HANDLE\fR, \fBDAT_LMR_HANDLE\fR, +\fBDAT_RMR_HANDLE\fR, or \fBDAT_CNO_HANDLE\fR. +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBDAT_SUCCESS\fR\fR +.ad +.RS 22n +.rt +The operation was successful. The Consumer context was successfully retrieved +from the specified handle. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_HANDLE\fR\fR +.ad +.RS 22n +.rt +The \fIdat_handle\fR parameter is invalid. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard: uDAPL, 1.1, 1.2 +_ +MT-LevelUnsafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBdat_set_consumer_context\fR(3DAT), \fBlibdat\fR(3LIB), \fBattributes\fR(5) diff --git a/usr/src/man/man3dat/dat_get_handle_type.3dat b/usr/src/man/man3dat/dat_get_handle_type.3dat new file mode 100644 index 0000000000..c22a0b122f --- /dev/null +++ b/usr/src/man/man3dat/dat_get_handle_type.3dat @@ -0,0 +1,115 @@ +'\" te +.\" This manual page is derived from the DAT/uDAPL 1.2 specification. +.\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH dat_get_handle_type 3DAT "16 Jul 2004" "SunOS 5.11" "Direct Access Transport Library Functions" +.SH NAME +dat_get_handle_type \- get handle type +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ldat\fR [ \fIlibrary\fR\&.\|.\|. ] +#include <\fBdat/udat.h\fR> + +DAT_RETURN + dat_get_handle_typet ( + IN DAT_HANDLE \fIdat_handle\fR, + OUT DAT_HANDLE_TYPE *\fIhandle_type\fR + ) +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIdat_handle\fR\fR +.ad +.RS 15n +.rt +Handle for a DAT Object. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIhandle_type\fR\fR +.ad +.RS 15n +.rt +Type of the handle of \fIdat_handle\fR. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBdat_get_handle_type()\fR function allows the Consumer to discover the +type of a DAT Object using its handle. +.sp +.LP +The \fIdat_handle\fR can be one of the following handle types: +\fBDAT_IA_HANDLE\fR, \fBDAT_EP_HANDLE\fR, \fBDAT_EVD_HANDLE\fR, +\fBDAT_CR_HANDLE\fR, \fBDAT_RSP_HANDLE\fR, \fBDAT_PSP_HANDLE\fR, +\fBDAT_PZ_HANDLE\fR, \fBDAT_LMR_HANDLE\fR, or \fBDAT_RMR_HANDLE\fR. +.sp +.LP +The \fIhandle_type\fR is one of the following handle types: +\fBDAT_HANDLE_TYPE_IA\fR, \fBDAT_HANDLE_TYPE_EP\fR, \fBDAT_HANDLE_TYPE_EVD\fR, +\fBDAT_HANDLE_TYPE_CR\fR, \fBDAT_HANDLE_TYPE_PSP\fR, \fBDAT_HANDLE_TYPE_RSP\fR, +\fBDAT_HANDLE_TYPE_PZ\fR, \fBDAT_HANDLE_TYPE_LMR\fR, \fBDAT_HANDLE_TYPE_RMR\fR, +or \fBDAT_HANDLE_TYPE_CNO\fR. +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBDAT_SUCCESS\fR\fR +.ad +.RS 22n +.rt +The operation was successful. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_HANDLE\fR\fR +.ad +.RS 22n +.rt +The \fIdat_handle\fR parameter is invalid. +.RE + +.SH USAGE +.sp +.LP +Consumers can use this operation to determine the type of Object being +returned. This is needed for calling an appropriate query or any other +operation on the Object handle. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard: uDAPL, 1.1, 1.2 +_ +MT-LevelUnsafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBlibdat\fR(3LIB), \fBattributes\fR(5) diff --git a/usr/src/man/man3dat/dat_ia_close.3dat b/usr/src/man/man3dat/dat_ia_close.3dat new file mode 100644 index 0000000000..51d5c290b4 --- /dev/null +++ b/usr/src/man/man3dat/dat_ia_close.3dat @@ -0,0 +1,233 @@ +'\" te +.\" This manual page is derived from the DAT/uDAPL 1.2 specification. +.\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH dat_ia_close 3DAT "16 Jul 2004" "SunOS 5.11" "Direct Access Transport Library Functions" +.SH NAME +dat_ia_close \- close an IA +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ldat\fR [ \fIlibrary\fR\&.\|.\|. ] +#include <\fBdat/udat.h\fR> + +DAT_RETURN + dat_ia_close ( + IN DAT_IA_HANDLE \fIia_handle\fR, + IN DAT_CLOSE_FLAGS \fIia_flags\fR + ) +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIia_handle\fR\fR +.ad +.RS 13n +.rt +Handle for an instance of a DAT IA. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIia_flags\fR\fR +.ad +.RS 13n +.rt +Flags for IA closure. Flag definitions are: +.sp +.ne 2 +.mk +.na +\fB\fBDAT_CLOSE_ABRUPT_FLAG\fR\fR +.ad +.RS 27n +.rt +Abrupt close. Abrupt cascading close of IA including all Consumer created DAT +objects. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_CLOSE_GRACEFUL_FLAG\fR\fR +.ad +.RS 27n +.rt +Graceful close. Closure is successful only if all DAT objects created by the +Consumer have been freed before the graceful closure call. +.RE + +Default value of \fBDAT_CLOSE_DEFAULT\fR = \fBDAT_CLOSE_ABRUPT_FLAG\fR +represents abrupt closure of IA. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBdat_ia_close()\fR function closes an IA (destroys an instance of the +Interface Adapter). +.sp +.LP +The\fI ia_flags\fR specify whether the Consumer wants abrupt or graceful close. +.sp +.LP +The abrupt close does a phased, cascading destroy. All DAT Objects associated +with an IA instance are destroyed. These include all the connection oriented +Objects: public and reserved Service Points; Endpoints, Connection Requests, +LMRs (including lmr_contexts), RMRs (including rmr_contexts), Event +Dispatchers, CNOs, and Protection Zones. All the waiters on all CNOs, including +the OS Wait Proxy Agents, are unblocked with the DAT_HANDLE_NULL handle returns +for an unblocking EVD. All direct waiters on all EVDs are also unblocked and +return with DAT_ABORT. +.sp +.LP +The graceful close does a destroy only if the Consumer has done a cleanup of +all DAT objects created by the Consumer with the exception of the asynchronous +EVD. Otherwise, the operation does not destroy the IA instance and returns the +\fBDAT_INVALID_STATE\fR. +.sp +.LP +If async EVD was created as part of the of \fBdat_ia_open\fR(3DAT), +\fBdat_ia_close()\fR must destroy it. If \fIasync_evd_handle\fR was passed in +by the Consumer at \fBdat_ia_open()\fR, this handle is not destroyed. This is +applicable to both abrupt and graceful \fIia_flags\fR values. +.sp +.LP +Because the Consumer did not create async EVD explicitly, the Consumer does not +need to destroy it for graceful close to succeed. +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBDAT_SUCCESS\fR\fR +.ad +.RS 30n +.rt +The operation was successful. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INSUFFICIENT_RESOURCES\fR\fR +.ad +.RS 30n +.rt +The operation failed due to resource limitations. This is a catastrophic error. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_HANDLE\fR\fR +.ad +.RS 30n +.rt +Invalid DAT handle; \fIia_handle\fR is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_PARAMETER\fR\fR +.ad +.RS 30n +.rt +Invalid parameter; \fIia_flags\fR is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_STATE\fR\fR +.ad +.RS 30n +.rt +Parameter in an invalid state. IA instance has Consumer-created objects +associated with it. +.RE + +.SH USAGE +.sp +.LP +The \fBdat_ia_close()\fR function is the root cleanup method for the Provider, +and, thus, all Objects. +.sp +.LP +Consumers are advised to explicitly destroy all Objects they created prior to +closing the IA instance, but can use this function to clean up everything +associated with an open instance of IA. This allows the Consumer to clean up in +case of errors. +.sp +.LP +Note that an abrupt close implies destruction of EVDs and CNOs. Just as with +explicit destruction of an EVD or CNO, the Consumer should take care to avoid a +race condition where a Consumer ends up attempting to wait on an EVD or CNO +that has just been deleted. +.sp +.LP +The techniques described in \fBdat_cno_free\fR(3DAT) and +\fBdat_evd_free\fR(3DAT) can be used for these purposes. +.sp +.LP +If the Consumer desires to shut down the IA as quickly as possible, the +Consumer can call dat_ia_close(abrupt) without unblocking CNO and EVD waiters +in an orderly fashion. There is a slight chance that an invalidated DAT handle +will cause a memory fault for a waiter. But this might be an acceptable +behavior, especially if the Consumer is shutting down the process. +.sp +.LP +No provision is made for blocking on event completion or pulling events from +queues. +.sp +.LP +This is the general cleanup and last resort method for Consumer recovery. An +implementation must provide for successful completion under all conditions, +avoiding hidden resource leakage (dangling memory, zombie processes, and so on) +eventually leading to a reboot of the operating system. +.sp +.LP +The \fBdat_ia_close()\fR function deletes all Objects that were created using +the IA handle. +.sp +.LP +The \fBdat_ia_close()\fR function can decrement a reference count for the +Provider Library that is incremented by \fBdat_ia_open()\fR to ensure that the +Provider Library cannot be removed when it is in use by a DAT Consumer. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard: uDAPL, 1.1, 1.2 +_ +MT-LevelUnsafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBdat_cno_free\fR(3DAT), \fBdat_evd_free\fR(3DAT), \fBdat_ia_open\fR(3DAT), +\fBlibdat\fR(3LIB), \fBattributes\fR(5) diff --git a/usr/src/man/man3dat/dat_ia_open.3dat b/usr/src/man/man3dat/dat_ia_open.3dat new file mode 100644 index 0000000000..2acfb0525b --- /dev/null +++ b/usr/src/man/man3dat/dat_ia_open.3dat @@ -0,0 +1,255 @@ +'\" te +.\" This manual page is derived from the DAT/uDAPL 1.2 specification. +.\" Portions Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH dat_ia_open 3DAT "28 Jan 2009" "SunOS 5.11" "Direct Access Transport Library Functions" +.SH NAME +dat_ia_open \- open an Interface Adapter (IA) +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ldat\fR [ \fIlibrary\fR\&.\|.\|. ] +#include <\fBdat/udat.h\fR> + +DAT_RETURN + dat_ia_open ( + IN const DAT_NAME_PTR \fIia_name_ptr\fR, + IN DAT_COUNT \fIasync_evd_min_qlen\fR, + INOUT DAT_EVD_HANDLE *\fIasync_evd_handle\fR, + OUT DAT_IA_HANDLE *\fIia_handle\fR + ) +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIia_name_ptr\fR\fR +.ad +.RS 22n +.rt +Symbolic name for the IA to be opened. The name should be defined by the +Provider registration. +.sp +If the name is prefixed by the string \fBRO_AWARE_\fR, then the prefix is +removed prior to being passed down and the existence of the prefix indicates +that the application has been coded to correctly deal with relaxed ordering +constraints. If the prefix is not present and the platform on which the +application is running is utilizing relaxed ordering, the open will fail with +\fBDAT_INVALID_PARAMETER\fR (with \fBDAT_SUBTYPE_STATUS\fR of +\fBDAT_INVALID_RO_COOKIE\fR). This setting also affects +\fBdat_lmr_create\fR(3DAT). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIasync_evd_min_qlen\fR\fR +.ad +.RS 22n +.rt +Minimum length of the Asynchronous Event Dispatcher queue. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIasync_evd_handle\fR\fR +.ad +.RS 22n +.rt +Pointer to a handle for an Event Dispatcher for asynchronous events generated +by the IA. This parameter can be \fBDAT_EVD_ASYNC_EXISTS\fR to indicate that +there is already EVD for asynchronous events for this Interface Adapter or +\fBDAT_HANDLE_NULL\fR for a Provider to generate EVD for it. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIia_handle\fR\fR +.ad +.RS 22n +.rt +Handle for an open instance of a DAT IA. This handle is used with other +functions to specify a particular instance of the IA. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBdat_ia_open()\fR function opens an IA by creating an IA instance. +Multiple instances (opens) of an IA can exist. +.sp +.LP +The value of \fBDAT_HANDLE_NULL\fR for \fIasync_evd_handle\fR +(*\fIasync_evd_handle\fR == \fBDAT_HANDLE_NULL\fR) indicates that the default +Event Dispatcher is created with the requested \fIasync_evd_min_qlen\fR. The +\fIasync_evd_handle\fR returns the handle of the created Asynchronous Event +Dispatcher. The first Consumer that opens an IA must use \fBDAT_HANDLE_NULL\fR +because no EVD can yet exist for the requested \fIia_name_ptr\fR. +.sp +.LP +The Asynchronous Event Dispatcher (\fIasync_evd_handle\fR) is created with no +CNO (\fBDAT_HANDLE_NULL\fR). Consumers can change these values using +\fBdat_evd_modify_cno\fR(3DAT). The Consumer can modify parameters of the Event +Dispatcher using \fBdat_evd_resize\fR(3DAT) and \fBdat_evd_modify_cno()\fR. +.sp +.LP +The Provider is required to provide a queue size at least equal to +\fIasync_evd_min_qlen\fR, but is free to provide a larger queue size or +dynamically enlarge the queue when needed. The Consumer can determine the +actual queue size by querying the created Event Dispatcher instance. +.sp +.LP +If \fIasync_evd_handle\fR is not \fBDAT_HANDLE_NULL\fR, the Provider does not +create an Event Dispatcher for an asynchronous event and the Provider ignores +the \fIasync_evd_min_qlen\fR value. The \fIasync_evd_handle\fR value passed in +by the Consumer must be an asynchronous Event Dispatcher created for the same +Provider (\fIia_name_ptr\fR). The Provider does not have to check for the +validity of the Consumer passed in \fIasync_evd_handle\fR. It is the Consumer +responsibility to guarantee that \fIasync_evd_handle\fR is valid and for this +Provider. How the \fIasync_evd_handle\fR is passed between DAT Consumers is out +of scope of the DAT specification. If the Provider determines that the +Consumer-provided \fIasync_evd_handle\fR is invalid, the operation fails and +returns \fBDAT_INVALID_HANDLE\fR. The \fIasync_evd_handle\fR remains unchanged, +so the returned \fIasync_evd_handle\fR is the same the Consumer passed in. All +asynchronous notifications for the open instance of the IA are directed by the +Provider to the Consumer passed in Asynchronous Event Dispatcher specified by +\fIasync_evd_handle\fR. +.sp +.LP +Consumer can specify the value of \fBDAT_EVD_ASYNC_EXISTS\fR to indicate that +there exists an event dispatcher somewhere else on the host, in user or kernel +space, for asynchronous event notifications. It is up to the Consumer to ensure +that this event dispatcher is unique and unambiguous. A special handle may be +returned for the Asynchronous Event Dispatcher for this scenario, +\fBDAT_EVD_OUT_OF_SCOPE\fR, to indicate that there is a default Event +Dispatcher assigned for this Interface Adapter, but that it is not in a scope +where this Consumer may directly invoke it. +.sp +.LP +The Asynchronous Event Dispatcher is an Object of both the Provider and IA. +Each Asynchronous Event Dispatcher bound to an IA instance is notified of all +asynchronous events, such that binding multiple Asynchronous Event Dispatchers +degrades performance by duplicating asynchronous event notifications for all +Asynchronous Event Dispatchers. Also, transport and memory resources can be +consumed per Event Dispatcher bound to an IA +.sp +.LP +As with all Event Dispatchers, the Consumer is responsible for synchronizing +access to the event queue. +.sp +.LP +Valid IA names are obtained from \fBdat_registry_list_providers\fR(3DAT). +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBDAT_SUCCESS\fR\fR +.ad +.RS 30n +.rt +The operation was successful. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INSUFFICIENT_RESOURCES\fR\fR +.ad +.RS 30n +.rt +The operation failed due to resource limitations. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_PARAMETER\fR\fR +.ad +.RS 30n +.rt +Invalid parameter. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_PROVIDER_NOT_FOUND\fR\fR +.ad +.RS 30n +.rt +The specified provider was not registered in the registry. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_HANDLE\fR\fR +.ad +.RS 30n +.rt +Invalid DAT handle; async_evd_handle is invalid. +.RE + +.SH USAGE +.sp +.LP +The \fBdat_ia_open()\fR function is the root method for the Provider, and, +thus, all Objects. It is the root handle through which the Consumer obtains all +other DAT handles. When the Consumer closes its handle, all its DAT Objects are +released. +.sp +.LP +The \fBdat_ia_open()\fR function is the workhorse method that provides an IA +instance. It can also initialize the Provider library or do any other +registry-specific functions. +.sp +.LP +The \fBdat_ia_open()\fR function creates a unique handle for the IA to the +Consumer. All further DAT Objects created for this Consumer reference this +handle as their owner. +.sp +.LP +The \fBdat_ia_open()\fR function can use a reference count for the Provider +Library to ensure that the Provider Library cannot be removed when it is in use +by a DAT Consumer. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +_ +MT-LevelSafe +_ +StandarduDAPL, 1.1, 1.2 (except \fBRO_AWARE_\fR) +.TE + +.SH SEE ALSO +.sp +.LP +\fBdat_evd_modify_cno\fR(3DAT), \fBdat_evd_resize\fR(3DAT), +\fBdat_ia_close\fR(3DAT), \fBdat_registry_list_providers\fR(3DAT), +\fBlibdat\fR(3LIB), \fBattributes\fR(5) diff --git a/usr/src/man/man3dat/dat_ia_query.3dat b/usr/src/man/man3dat/dat_ia_query.3dat new file mode 100644 index 0000000000..01bb273501 --- /dev/null +++ b/usr/src/man/man3dat/dat_ia_query.3dat @@ -0,0 +1,750 @@ +'\" te +.\" This manual page is derived from the DAT/uDAPL 1.2 specification. +.\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH dat_ia_query 3DAT "16 Jul 2004" "SunOS 5.11" "Direct Access Transport Library Functions" +.SH NAME +dat_ia_query \- query an IA +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ldat\fR [ \fIlibrary\fR\&.\|.\|. ] +#include <\fBdat/udat.h\fR> + +DAT_RETURN + dat_ia_query ( + IN DAT_IA_HANDLE \fIia_handle\fR, + OUT DAT_EVD_HANDLE *\fIasync_evd_handle\fR, + IN DAT_IA_ATTR_MASK \fIia_attr_mask\fR, + OUT DAT_IA_ATTR *\fIia_attributes\fR, + IN DAT_PROVIDER_ATTR_MASK \fIprovider_attr_mask\fR, + OUT DAT_PROVIDER_ATTR *\fIprovider_attributes\fR + ) +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIia_handle\fR\fR +.ad +.RS 23n +.rt +Handle for an open instance of an IA. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIasync_evd_handle\fR\fR +.ad +.RS 23n +.rt +Handle for an Event Dispatcher for asynchronous events generated by the IA. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIia_attr_mask\fR\fR +.ad +.RS 23n +.rt +Mask for the \fIia_attributes\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIia_attributes\fR\fR +.ad +.RS 23n +.rt +Pointer to a Consumer-allocated structure that the Provider fills with IA +attributes. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIprovider_attr_mask\fR\fR +.ad +.RS 23n +.rt +Mask for the \fIprovider_attributes\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIprovider_attributes\fR\fR +.ad +.RS 23n +.rt +Pointer to a Consumer-allocated structure that the Provider fills with Provider +attributes. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBdat_ia_query()\fR functions provides the Consumer with the IA +parameters, as well as the IA and Provider attributes. Consumers pass in +pointers to Consumer-allocated structures for the IA and Provider attributes +that the Provider fills. +.sp +.LP +The \fIia_attr_mask\fR and \fIprovider_attr_mask\fR parameters allow the +Consumer to specify which attributes to query. The Provider returns values for +requested attributes. The Provider can also return values for any of the other +attributes. +.SS "Interface Adapter Attributes" +.sp +.LP +The IA attributes are common to all open instances of the IA. DAT defines a +method to query the IA attributes but does not define a method to modify them. +.sp +.LP +If IA is multiported, each port is presented to a Consumer as a separate IA. +.sp +.ne 2 +.mk +.na +\fBAdapter name:\fR +.ad +.br +.na +\fB\fR +.ad +.sp .6 +.RS 4n +The name of the IA controlled by the Provider. The same as \fIia_name_ptr\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fBVendor name:\fR +.ad +.sp .6 +.RS 4n +Vendor if IA hardware. +.RE + +.sp +.ne 2 +.mk +.na +\fBHW version major:\fR +.ad +.sp .6 +.RS 4n +Major version of IA hardware. +.RE + +.sp +.ne 2 +.mk +.na +\fBHW version minor:\fR +.ad +.sp .6 +.RS 4n +Minor version of IA hardware. +.RE + +.sp +.ne 2 +.mk +.na +\fBFirmware version major:\fR +.ad +.sp .6 +.RS 4n +Major version of IA firmware. +.RE + +.sp +.ne 2 +.mk +.na +\fBFirmware version minor:\fR +.ad +.sp .6 +.RS 4n +Minor version of IA firmware. +.RE + +.sp +.ne 2 +.mk +.na +\fBIA_address_ptr:\fR +.ad +.sp .6 +.RS 4n +An address of the interface Adapter. +.RE + +.sp +.ne 2 +.mk +.na +\fBMax EPs:\fR +.ad +.sp .6 +.RS 4n +Maximum number of Endpoints that the IA can support. This covers all Endpoints +in all states, including the ones used by the Providers, zero or more +applications, and management. +.RE + +.sp +.ne 2 +.mk +.na +\fBMax DTOs per EP:\fR +.ad +.sp .6 +.RS 4n +Maximum number of DTOs and RMR_binds that any Endpoint can support for a single +direction. This means the maximum number of outstanding and in-progress Send, +RDMA Read, RDMA Write DTOs, and RMR Binds at any one time for any Endpoint; and +maximum number of outstanding and in-progress Receive DTOs at any one time for +any Endpoint. +.RE + +.sp +.ne 2 +.mk +.na +\fBMax incoming RDMA Reads per EP:\fR +.ad +.sp .6 +.RS 4n +Maximum number of RDMA Reads that can be outstanding per (connected) Endpoint +with the IA as the target. +.RE + +.sp +.ne 2 +.mk +.na +\fBMax outgoing RDMA Reads per EP:\fR +.ad +.sp .6 +.RS 4n +Maximum number of RDMA Reads that can be outstanding per (connected) Endpoint +with the IA as the originator. +.RE + +.sp +.ne 2 +.mk +.na +\fBMax EVDs:\fR +.ad +.sp .6 +.RS 4n +Maximum number of Event Dispatchers that an IA can support. An IA cannot +support an Event Dispatcher directly, but indirectly by Transport-specific +Objects, for example, Completion Queues for Infiniband\(tm and VI. The Event +Dispatcher Objects can be shared among multiple Providers and similar Objects +from other APIs, for example, Event Queues for uDAPL. +.RE + +.sp +.ne 2 +.mk +.na +\fBMax EVD queue size:\fR +.ad +.sp .6 +.RS 4n +Maximum size of the EVD queue supported by an IA. +.RE + +.sp +.ne 2 +.mk +.na +\fBMax IOV segments per DTO:\fR +.ad +.sp .6 +.RS 4n +Maximum entries in an IOV list that an IA supports. Notice that this number +cannot be explicit but must be implicit to transport-specific Object entries. +For example, for IB, it is the maximum number of scatter/gather entries per +Work Request, and for VI it is the maximum number of data segments per VI +Descriptor. +.RE + +.sp +.ne 2 +.mk +.na +\fBMax LMRs:\fR +.ad +.sp .6 +.RS 4n +Maximum number of Local Memory Regions IA supports among all Providers and +applications of this IA. +.RE + +.sp +.ne 2 +.mk +.na +\fBMax LMR block size:\fR +.ad +.sp .6 +.RS 4n +Maximum contiguous block that can be registered by the IA. +.RE + +.sp +.ne 2 +.mk +.na +\fBMac LMR VA:\fR +.ad +.sp .6 +.RS 4n +Highest valid virtual address within the context of an LMR. Frequently, IAs on +32-bit architectures support only 32-bit local virtual addresses. +.RE + +.sp +.ne 2 +.mk +.na +\fBMax PZs:\fR +.ad +.sp .6 +.RS 4n +Maximum number of Protection Zones that the IA supports. +.RE + +.sp +.ne 2 +.mk +.na +\fBMax MTU size:\fR +.ad +.sp .6 +.RS 4n +Maximum message size supported by the IA +.RE + +.sp +.ne 2 +.mk +.na +\fBMax RDMA size:\fR +.ad +.sp .6 +.RS 4n +Maximum RDMA size supported by the IA +.RE + +.sp +.ne 2 +.mk +.na +\fBMax RMRs:\fR +.ad +.sp .6 +.RS 4n +Maximum number of RMRs an IA supports among all Providers and applications of +this IA. +.RE + +.sp +.ne 2 +.mk +.na +\fBMax RMR target address:\fR +.ad +.sp .6 +.RS 4n +Highest valid target address with the context of a local RMR. Frequently, IAs +on 32-bit architectures support only 32-bit local virtual addresses. +.RE + +.sp +.ne 2 +.mk +.na +\fBNum transport attributes:\fR +.ad +.sp .6 +.RS 4n +Number of transport-specific attributes. +.RE + +.sp +.ne 2 +.mk +.na +\fBTransport-specific attributes:\fR +.ad +.sp .6 +.RS 4n +Array of transport-specific attributes. Each entry has the format of +\fBDAT_NAMED_ATTR\fR, which is a structure with two elements. The first element +is the name of the attribute. The second element is the value of the attribute +as a string. +.RE + +.sp +.ne 2 +.mk +.na +\fBNum vendor attributes:\fR +.ad +.sp .6 +.RS 4n +Number of vendor-specific attributes. +.RE + +.sp +.ne 2 +.mk +.na +\fBVendor-specific attributes:\fR +.ad +.sp .6 +.RS 4n +Array of vendor-specific attributes. Each entry has the format of +\fBDAT_NAMED_ATTR\fR, which is a structure with two elements. The first element +is the name of the attribute. The second element is the value of the attribute +as a string. +.RE + +.SS "DAPL Provider Attributes" +.sp +.LP +The provider attributes are specific to the open instance of the IA. DAT +defines a method to query Provider attributes but does not define a method to +modify them. +.sp +.ne 2 +.mk +.na +\fBProvider name:\fR +.ad +.sp .6 +.RS 4n +Name of the Provider vendor. +.RE + +.sp +.ne 2 +.mk +.na +\fBProvider version major:\fR +.ad +.sp .6 +.RS 4n +Major Version of uDAPL Provider. +.RE + +.sp +.ne 2 +.mk +.na +\fBProvider version minor:\fR +.ad +.sp .6 +.RS 4n +Minor Version of uDAPL Provider. +.RE + +.sp +.ne 2 +.mk +.na +\fBDAPL API version major:\fR +.ad +.sp .6 +.RS 4n +Major Version of uDAPL API supported. +.RE + +.sp +.ne 2 +.mk +.na +\fBDAPL API version minor:\fR +.ad +.sp .6 +.RS 4n +Minor Version of uDAPL API supported. +.RE + +.sp +.ne 2 +.mk +.na +\fBLMR memory types supported:\fR +.ad +.sp .6 +.RS 4n +Memory types that LMR Create supports for memory registration. This value is a +union of LMR Memory Types \fBDAT_MEM_TYPE_VIRTUAL\fR, \fBDAT_MEM_TYPE_LMR\fR, +and \fBDAT_MEM_TYPE_SHARED_VIRTUAL\fR that the Provider supports. All Providers +must support the following Memory Types: \fBDAT_MEM_TYPE_VIRTUAL\fR, +\fBDAT_MEM_TYPE_LMR\fR, and \fBDAT_MEM_TYPE_SHARED_VIRTUAL\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fBIOV ownership:\fR +.ad +.sp .6 +.RS 4n +An enumeration flag that specifies the ownership of the local buffer +description (IOV list) after post DTO returns. The three values are as follows: +.RS +4 +.TP +.ie t \(bu +.el o +\fBDAT_IOV_CONSUMER\fR indicates that the Consumer has the ownership of the +local buffer description after a post returns. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +\fBDAT_IOV_PROVIDER_NOMOD\fR indicates that the Provider still has ownership of +the local buffer description of the DTO when the post DTO returns, but the +Provider does not modify the buffer description. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +\fBDAT_IOV_PROVIDER_MOD\fR indicates that the Provider still has ownership of +the local buffer description of the DTO when the post DTO returns and can +modify the buffer description. +.RE +In any case, the Consumer obtains ownership of the local buffer description +after the DTO transfer is completed and the Consumer is notified through a DTO +completion event. +.RE + +.sp +.ne 2 +.mk +.na +\fBQOS supported:\fR +.ad +.sp .6 +.RS 4n +The union of the connection QOS supported by the Provider. +.RE + +.sp +.ne 2 +.mk +.na +\fBCompletion flags supported:\fR +.ad +.sp .6 +.RS 4n +The following values for the completion flag \fBDAT_COMPLETION_FLAGS\fR are +supported by the Provider: \fBDAT_COMPLETION_SUPPRESS_FLAG\fR, +\fBDAT_COMPLETION_UNSIGNALLED_FLAG\fR, +\fBDAT_COMPLETION_SOLICITED_WAIT_FLAG\fR, and +\fBDAT_COMPLETION_BARRIER_FENCE_FLAG\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fBThread safety:\fR +.ad +.sp .6 +.RS 4n +Provider Library thread safe or not. The Provider Library is not required to be +thread safe. +.RE + +.sp +.ne 2 +.mk +.na +\fBMax private data size:\fR +.ad +.sp .6 +.RS 4n +Maximum size of private data the Provider supports. This value is at least 64 +bytes. +.RE + +.sp +.ne 2 +.mk +.na +\fBMultipathing support:\fR +.ad +.sp .6 +.RS 4n +Capability of the Provider to support Multipathing for connection +establishment. +.RE + +.sp +.ne 2 +.mk +.na +\fBEP creator for PSP:\fR +.ad +.sp .6 +.RS 4n +Indicator for who can create an Endpoint for a Connection Request. For the +Consumer it is \fBDAT_PSP_CREATES_EP_NEVER\fR. For the Provider it is +\fBDAT_PSP_CREATES_EP_ALWAYS\fR. For both it is +\fBDAT_PSP_CREATES_EP_IFASKED\fR. This attribute is used for Public Service +Point creation. +.RE + +.sp +.ne 2 +.mk +.na +\fBPZ support:\fR +.ad +.sp .6 +.RS 4n +Indicator of what kind of protection the Provider's PZ provides. +.RE + +.sp +.ne 2 +.mk +.na +\fBOptimal Buffer Alignment:\fR +.ad +.sp .6 +.RS 4n +Local and remote DTO buffer alignment for optimal performance on the Platform. +The \fBDAT_OPTIMAL_ALIGMNEMT\fR must be divisible by this attribute value. The +maximum allowed value is \fBDAT_OPTIMAL_ALIGMNEMT\fR, or 256. +.RE + +.sp +.ne 2 +.mk +.na +\fBEVD stream merging support:\fR +.ad +.sp .6 +.RS 4n +A 2D binary matrix where each row and column represent an event stream type. +Each binary entry is 1 if the event streams of its row and column can be fed to +the same EVD, and 0 otherwise. +.sp +More than two different event stream types can feed the same EVD if for each +pair of the event stream types the entry is 1. +.sp +The Provider should support merging of all event stream types. +.sp +The Consumer should check this attribute before requesting an EVD that merges +multiple event stream types. +.RE + +.sp +.ne 2 +.mk +.na +\fBNum provider attributes:\fR +.ad +.sp .6 +.RS 4n +Number of Provider-specific attributes. +.RE + +.sp +.ne 2 +.mk +.na +\fBProvider-specific attributes:\fR +.ad +.sp .6 +.RS 4n +Array of Provider-specific attributes. Each entry has the format of +\fBDAT_NAMED_ATTR\fR, which is a structure with two elements. The first element +is the name of the attribute. The second element is the value of the attribute +as a string. +.RE + +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBDAT_SUCCESS\fR\fR +.ad +.RS 25n +.rt +The operation was successful. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_PARAMETER\fR\fR +.ad +.RS 25n +.rt +Invalid parameter; +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_HANDLE\fR\fR +.ad +.RS 25n +.rt +Invalid DAT handle; ia_handle is invalid. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard: uDAPL, 1.1, 1.2 +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBlibdat\fR(3LIB), \fBattributes\fR(5) diff --git a/usr/src/man/man3dat/dat_lmr_create.3dat b/usr/src/man/man3dat/dat_lmr_create.3dat new file mode 100644 index 0000000000..2ad480f60b --- /dev/null +++ b/usr/src/man/man3dat/dat_lmr_create.3dat @@ -0,0 +1,455 @@ +'\" te +.\" This manual page is derived from the DAT/uDAPL 1.2 specification. +.\" Portions Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH dat_lmr_create 3DAT "28 Jan 2009" "SunOS 5.11" "Direct Access Transport Library Functions" +.SH NAME +dat_lmr_create \- register a memory region with an IA +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ldat\fR [ \fIlibrary\fR\&.\|.\|. ] +#include <\fBdat/udat.h\fR> + +DAT_RETURN + dat_lmr_create ( + IN DAT_IA_HANDLE ia_handle, + IN DAT_MEM_TYPE mem_type, + IN DAT_REGION_DESCRIPTION region_description, + IN DAT_VLEN length, + IN DAT_PZ_HANDLE pz_handle, + IN DAT_MEM_PRIV_FLAGS mem_privileges, + OUT DAT_LMR_HANDLE *lmr_handle, + OUT DAT_LMR_CONTEXT *lmr_context, + OUT DAT_RMR_CONTEXT *rmr_context, + OUT DAT_VLEN *registered_size, + OUT DAT_VADDR *registered_address + ) +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIia_handle\fR\fR +.ad +.sp .6 +.RS 4n +Handle for an open instance of the IA. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fImem_type\fR\fR +.ad +.sp .6 +.RS 4n +Type of memory to be registered. The following list outlines the memory type +specifications. +.sp +.ne 2 +.mk +.na +\fB\fBDAT_MEM_TYPE_VIRTUAL\fR\fR +.ad +.sp .6 +.RS 4n +Consumer virtual memory. +.sp +Region description: A pointer to a contiguous user virtual range. +.sp +Length: Length of the Memory Region. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_MEM_TYPE_SO_VIRTUAL\fR\fR +.ad +.sp .6 +.RS 4n +Consumer virtual memory with strong memory ordering. This type is a Solaris +specific addition. If the \fIia_handle\fR was opened without \fBRO_AWARE_\fR +(see \fBdat_ia_open\fR(3DAT)), then type \fBDAT_MEM_TYPE_VIRTUAL\fR is +implicitly converted to this type. +.sp +Region description: A pointer to a contiguous user virtual range. +.sp +Length: Length of the Memory Region. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_MEM_TYPE_LMR\fR\fR +.ad +.sp .6 +.RS 4n +LMR. +.sp +Region description: An LMR_handle. +.sp +Length: Length parameter is ignored. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_MEM_TYPE_SHARED_VIRTUAL\fR\fR +.ad +.sp .6 +.RS 4n +Shared memory region. All DAT Consumers of the same uDAPL Provider specify the +same Consumer cookie to indicate who is sharing the shared memory region. This +supports a peer-to-peer model of shared memory. All DAT Consumers of the shared +memory must allocate the memory region as shared memory using Platform-specific +primitives. +.sp +Region description: A structure with 2 elements, where the first one is of type +\fBDAT_LMR_COOKIE\fR and is a unique identifier of the shared memory region, +and the second one is a pointer to a contiguous user virtual range. +.sp +Length: Length of the Memory Region +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIregion_description\fR\fR +.ad +.sp .6 +.RS 4n +Pointer to type-specific data describing the memory in the region to be +registered. The type is derived from the \fImem_type\fR parameter. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIlength\fR\fR +.ad +.sp .6 +.RS 4n +Length parameter accompanying the region_description. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIpz_handle\fR\fR +.ad +.sp .6 +.RS 4n +Handle for an instance of the Protection Zone. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fImem_privileges:\fR\fR +.ad +.sp .6 +.RS 4n +Consumer-requested memory access privileges for the registered local memory +region. The Default value is \fBDAT_MEM_PRIV_NONE_FLAG\fR. The constant value +\fBDAT_MEM_PRIV_ALL_FLAG\fR = 0x33, which specifies both Read and Write +privileges, is also defined. Memory privilege definitions are as follows: +.sp +.ne 2 +.mk +.na +\fBLocal Read\fR +.ad +.RS 16n +.rt +\fBDAT_MEM_PRIV_LOCAL_READ_FLAG\fR +.sp +.ne 2 +.mk +.na +\fB0x01\fR +.ad +.RS 8n +.rt +Local read access requested. +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fBLocal Write\fR +.ad +.RS 16n +.rt +\fBDAT_MEM_PRIV_LOCAL_WRITE_FLAG\fR +.sp +.ne 2 +.mk +.na +\fB0x10\fR +.ad +.RS 8n +.rt +Local write access requested. +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fBRemote Read\fR +.ad +.RS 16n +.rt +\fBDAT_MEM_PRIV_REMOTE_READ_FLAG\fR +.sp +.ne 2 +.mk +.na +\fB0x02\fR +.ad +.RS 8n +.rt +Remote read access requested. +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fBRemote Write\fR +.ad +.RS 16n +.rt +\fBDAT_MEM_PRIV_REMOTE_WRITE_FLAG\fR +.sp +.ne 2 +.mk +.na +\fB0x20\fR +.ad +.RS 8n +.rt +Remote write access requested. +.RE + +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIlmr_handle\fR\fR +.ad +.sp .6 +.RS 4n +Handle for the created instance of the LMR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIlmr_context\fR\fR +.ad +.sp .6 +.RS 4n +Context for the created instance of the LMR to use for DTO local buffers. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIregistered_size\fR\fR +.ad +.sp .6 +.RS 4n +Actual memory size registered by the Provider. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIregistered_address\fR\fR +.ad +.sp .6 +.RS 4n +Actual base address of the memory registered by the Provider. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBdat_lmr_create()\fR function registers a memory region with an IA. The +specified buffer must have been previously allocated and pinned by the uDAPL +Consumer on the platform. The Provider must do memory pinning if needed, which +includes whatever OS-dependent steps are required to ensure that the memory is +available on demand for the Interface Adapter. uDAPL does not require that the +memory never be swapped out; just that neither the hardware nor the Consumer +ever has to deal with it not being there. The created \fIlmr_context\fR can be +used for local buffers of DTOs and for binding RMRs, and \fIlmr_handle\fR can +be used for creating other LMRs. For uDAPL the scope of the \fIlmr_context\fR +is the address space of the DAT Consumer. +.sp +.LP +The return values of \fIregistered_size\fR and \fIregistered_address\fR +indicate to the Consumer how much the contiguous region of Consumer virtual +memory was registered by the Provider and where the region starts in the +Consumer virtual address. +.sp +.LP +The \fImem_type\fR parameter indicates to the Provider the kind of memory to be +registered, and can take on any of the values defined in the table in the +PARAMETERS section. +.sp +.LP +The \fIpz_handle\fR parameter allows Consumers to restrict local accesses to +the registered LMR by DTOs. +.sp +.LP +\fBDAT_LMR_COOKIE\fR is a pointer to a unique identifier of the shared memory +region of the \fBDAT_MEM_TYPE_SHARED_VIRTUAL\fR DAT memory type. The identifier +is an array of 40 bytes allocated by the Consumer. The Provider must check the +entire 40 bytes and shall not interpret it as a null-terminated string. +.sp +.LP +The return value of \fIrmr_context\fR can be transferred by the local Consumer +to a Consumer on a remote host to be used for an RDMA DTO. +.sp +.LP +If \fImem_privileges\fR does not specify remote Read and Write privileges, +\fIrmr_context\fR is not generated and \fINULL\fR is returned. No remote +privileges are given for Memory Region unless explicitly asked for by the +Consumer. +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBDAT_SUCCESS\fR\fR +.ad +.RS 30n +.rt +The operation was successful. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_UNSUFFICIENT_RESOURCES\fR\fR +.ad +.RS 30n +.rt +The operation failed due to resource limitations. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_PARAMETER\fR\fR +.ad +.RS 30n +.rt +Invalid parameter. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_HANDLE\fR\fR +.ad +.RS 30n +.rt +Invalid DAT handle. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_STATE\fR\fR +.ad +.RS 30n +.rt +Parameter in an invalid state. For example, shared virtual buffer was not +created shared by the platform. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_MODEL_NOT_SUPPORTED\fR\fR +.ad +.RS 30n +.rt +The requested Model was not supported by the Provider. For example, requested +Memory Type was not supported by the Provider. +.RE + +.SH USAGE +.sp +.LP +Consumers can create an LMR over the existing LMR memory with different +Protection Zones and privileges using previously created IA translation table +entries. +.sp +.LP +The Consumer should use \fIrmr_context\fR with caution. Once advertised to a +remote peer, the \fIrmr_context\fR of the LMR cannot be invalidated. The only +way to invalidate it is to destroy the LMR with \fBdat_lmr_free\fR(3DAT). +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +_ +MT-LevelSafe +_ +StandardT{ +uDAPL, 1.1, 1.2 (except \fBDAT_MEM_TYPE_SO_VIRTUAL\fR) +T} +.TE + +.SH SEE ALSO +.sp +.LP +\fBdat_lmr_free\fR(3DAT), \fBlibdat\fR(3LIB), \fBattributes\fR(5) diff --git a/usr/src/man/man3dat/dat_lmr_free.3dat b/usr/src/man/man3dat/dat_lmr_free.3dat new file mode 100644 index 0000000000..47babd280b --- /dev/null +++ b/usr/src/man/man3dat/dat_lmr_free.3dat @@ -0,0 +1,112 @@ +'\" te +.\" This manual page is derived from the DAT/uDAPL 1.2 specification. +.\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH dat_lmr_free 3DAT "16 Jul 2004" "SunOS 5.11" "Direct Access Transport Library Functions" +.SH NAME +dat_lmr_free \- destroy an instance of the LMR +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ldat\fR [ \fIlibrary\fR\&.\|.\|. ] +#include <\fBdat/udat.h\fR> + +DAT_RETURN + dat_lmr_free ( + IN DAT_LMR_HANDLE lmr_handle + ) +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIlmr_handle:\fR\fR +.ad +.RS 15n +.rt +Handle for an instance of LMR to be destroyed. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBdat_lmr_free()\fR function destroys an instance of the LMR. The LMR +cannot be destroyed if it is in use by an RMR. The operation does not +deallocate the memory region or unpin memory on a host. +.sp +.LP +Use of the handle of the destroyed LMR in any subsequent operation except for +\fBdat_lmr_free()\fR fails. Any DTO operation that uses the destroyed LMR after +the \fBdat_lmr_free()\fR is completed shall fail and report a protection +violation. The use of \fIrmr_context\fR of the destroyed LMR by a remote peer +for an RDMA DTO results in an error and broken connection on which it was used. +Any remote RDMA operation that uses the destroyed LMR rmr_context\fI\fR, whose +Transport-specific request arrived to the local host after the +\fBdat_lmr_free()\fR has completed, fails and reports a protection violation. +Remote RDMA operation that uses the destroyed LMR \fIrmr_context\fR, whose +Transport-specific request arrived to the local host prior to the +\fBdat_lmr_free()\fR returns, might or might not complete successfully. If it +fails, \fBDAT_DTO_ERR_REMOTE_ACCESS\fR is reported in +\fBDAT_DTO_COMPLETION_STATUS\fR for the remote RDMA DTO and the connection is +broken. +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBDAT_SUCCESS\fR\fR +.ad +.RS 22n +.rt +The operation was successful. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_HANDLE\fR\fR +.ad +.RS 22n +.rt +The \fIlmr_handle\fR parameter is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_STATE\fR\fR +.ad +.RS 22n +.rt +Parameter in an invalid state; LMR is in use by an RMR instance. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard: uDAPL, 1.1, 1.2 +_ +MT-LevelUnsafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBlibdat\fR(3LIB), \fBattributes\fR(5) diff --git a/usr/src/man/man3dat/dat_lmr_query.3dat b/usr/src/man/man3dat/dat_lmr_query.3dat new file mode 100644 index 0000000000..09eadcff45 --- /dev/null +++ b/usr/src/man/man3dat/dat_lmr_query.3dat @@ -0,0 +1,126 @@ +'\" te +.\" This manual page is derived from the DAT/uDAPL 1.2 specification. +.\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH dat_lmr_query 3DAT "16 Jul 2004" "SunOS 5.11" "Direct Access Transport Library Functions" +.SH NAME +dat_lmr_query \- provide LMR parameters +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ldat\fR [ \fIlibrary\fR\&.\|.\|. ] +#include <\fBdat/udat.h\fR> + +DAT_RETURN + dat_lmr_query ( + IN DAT_LMR_HANDLE lmr_handle, + IN DAT_LMR_PARAM_MASK lmr_param_mask, + OUT DAT_LMR_PARAM *lmr_param + ) +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIlmr_handle\fR\fR +.ad +.RS 18n +.rt +Handle for an instance of the LMR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIlmr_param_mask\fR\fR +.ad +.RS 18n +.rt +Mask for LMR parameters. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIlmr_param\fR\fR +.ad +.RS 18n +.rt +Pointer to a Consumer-allocated structure that the Provider fills with LMR +parameters. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBdat_lmr_query()\fR function provides the Consumer LMR parameters. The +Consumer passes in a pointer to the Consumer-allocated structures for LMR +parameters that the Provider fills. +.sp +.LP +The \fIlmr_param_mask\fR parameter allows Consumers to specify which parameters +to query. The Provider returns values for \fIlmr_param_mask\fR requested +parameters. The Provider can return values for any other parameters. +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBDAT_SUCCESS\fR\fR +.ad +.RS 25n +.rt +The operation was successful. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_PARAMETER\fR\fR +.ad +.RS 25n +.rt +The \fIlmr_param_mask\fR function is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_HANDLE\fR\fR +.ad +.RS 25n +.rt +The \fIlmr_handle\fR function is invalid. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard: uDAPL, 1.1, 1.2 +_ +MT-LevelUnsafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBlibdat\fR(3LIB), \fBattributes\fR(5) diff --git a/usr/src/man/man3dat/dat_lmr_sync_rdma_read.3dat b/usr/src/man/man3dat/dat_lmr_sync_rdma_read.3dat new file mode 100644 index 0000000000..a5aef976be --- /dev/null +++ b/usr/src/man/man3dat/dat_lmr_sync_rdma_read.3dat @@ -0,0 +1,178 @@ +'\" te +.\" This manual page is derived from the DAT/uDAPL 1.2 specification. +.\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH dat_lmr_sync_rdma_read 3DAT "16 Jul 2004" "SunOS 5.11" "Direct Access Transport Library Functions" +.SH NAME +dat_lmr_sync_rdma_read \- synchronize local memory with RDMA read on +non-coherent memory +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ldat\fR [ \fIlibrary\fR\&.\|.\|. ] +#include <\fBdat/udat.h\fR> + +DAT_RETURN + dat_lmr_sync_rdma_read ( + IN DAT_IA_HANDLE ia_handle, + IN const DAT_LMR_TRIPLET *local_segments, + IN DAT_VLEN num_segments + ) +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIia_handle\fR\fR +.ad +.RS 18n +.rt +A handle for an open instance of the IA. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIlocal_segments\fR\fR +.ad +.RS 18n +.rt +An array of buffer segments. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fInum_segments\fR\fR +.ad +.RS 18n +.rt +The number of segments in the \fIlocal_segments\fR argument. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBdat_lmr_sync_rdma_read()\fR function makes memory changes visible to an +incoming RDMA Read operation. This operation guarantees consistency by locally +flushing the non-coherent cache prior to it being retrieved by remote peer RDMA +read operations. +.sp +.LP +The \fBdat_lmr_sync_rdma_read()\fR function is needed if and only if the +Provider attribute specifies that this operation is needed prior to an incoming +RDMA Read operation. The Consumer must call \fBdat_lmr_sync_rdma_read()\fR +after modifying data in a memory range in this region that will be the target +of an incoming RDMA Read operation. The \fBdat_lmr_sync_rdma_read()\fR function +must be called after the Consumer has modified the memory range but before the +RDMA Read operation begins. The memory range that will be accessed by the RDMA +read operation must be supplied by the caller in the \fIlocal_segments\fR +array. After this call returns, the RDMA Read operation can safely see the +modified contents of the memory range. It is permissible to batch +synchronizations for multiple RDMA Read operations in a single call by passing +a \fIlocal_segments\fR array that includes all modified memory ranges. The +\fIlocal_segments\fR entries need not contain the same LMR and need not be in +the same Protection Zone. +.sp +.LP +If the Provider attribute specifying that this operation is required attempts +to read from a memory range that is not properly synchronized using +\fBdat_lmr_sync_rdma_read()\fR, the returned contents are undefined. +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBDAT_SUCCESS\fR\fR +.ad +.RS 25n +.rt +The operation was successful. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_HANDLE\fR\fR +.ad +.RS 25n +.rt +The DAT handle is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_PARAMETER\fR\fR +.ad +.RS 25n +.rt +One of the parameters is invalid. For example, the address range for a local +segment fell outside the boundaries of the corresponding Local Memory Region or +the LMR handle was invalid. +.RE + +.SH USAGE +.sp +.LP +Determining when an RDMA Read will start and what memory range it will read is +the Consumer's responsibility. One possibility is to have the Consumer that is +modifying memory call \fBdat_lmr_sync_rdma_read()\fR and then post a Send DTO +message that identifies the range in the body of the Send. The Consumer wanting +to perform the RDMA Read can receive this message and know when it is safe to +initiate the RDMA Read operation. +.sp +.LP +This call ensures that the Provider receives a coherent view of the buffer +contents upon a subsequent remote RDMA Read operation. After the call +completes, the Consumer can be assured that all platform-specific buffer and +cache updates have been performed, and that the LMR range has consistency with +the Provider hardware. Any subsequent write by the Consumer can void this +consistency. The Provider is not required to detect such access. +.sp +.LP +The action performed on the cache before the RDMA Read depends on the cache +type: +.RS +4 +.TP +.ie t \(bu +.el o +I/O noncoherent cache will be invalidated. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +CPU noncoherent cache will be flushed. +.RE +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard: uDAPL, 1.2 +_ +MT-LevelUnsafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBdat_lmr_sync_rdma_write\fR(3DAT), \fBlibdat\fR(3LIB), \fBattributes\fR(5) diff --git a/usr/src/man/man3dat/dat_lmr_sync_rdma_write.3dat b/usr/src/man/man3dat/dat_lmr_sync_rdma_write.3dat new file mode 100644 index 0000000000..f806c75567 --- /dev/null +++ b/usr/src/man/man3dat/dat_lmr_sync_rdma_write.3dat @@ -0,0 +1,188 @@ +'\" te +.\" This manual page is derived from the DAT/uDAPL 1.2 specification. +.\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH dat_lmr_sync_rdma_write 3DAT "16 Jul 2004" "SunOS 5.11" "Direct Access Transport Library Functions" +.SH NAME +dat_lmr_sync_rdma_write \- synchronize local memory with RDMA write on +non-coherent memory +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ldat\fR [ \fIlibrary\fR\&.\|.\|. ] +#include <\fBdat/udat.h\fR> + +DAT_RETURN + dat_lmr_sync_rdma_write ( + IN DAT_IA_HANDLE ia_handle, + IN const DAT_LMR_TRIPLET *local_segments, + IN DAT_VLEN num_segments + ) +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIia_handle\fR\fR +.ad +.RS 18n +.rt +A handle for an open instance of the IA. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIlocal_segments\fR\fR +.ad +.RS 18n +.rt +An array of buffer segments. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fInum_segments\fR\fR +.ad +.RS 18n +.rt +The number of segments in the \fIlocal_segments\fR argument. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBdat_lmr_sync_rdma_write()\fR function makes effects of an incoming RDMA +Write operation visible to the Consumer. This operation guarantees consistency +by locally invalidating the non-coherent cache whose buffer has been populated +by remote peer RDMA write operations. +.sp +.LP +The \fBdat_lmr_sync_rdma_write()\fR function is needed if and only if the +Provider attribute specifies that this operation is needed after an incoming +RDMA Write operation. The Consumer must call \fBdat_lmr_sync_rdma_write()\fR +before reading data from a memory range in this region that was the target of +an incoming RDMA Write operation. The \fBdat_lmr_sync_rdma_write()\fR function +must be called after the RDMA Write operation completes, and the memory range +that was modified by the RDMA Write must be supplied by the caller in the +\fIlocal_ segments\fR array. After this call returns, the Consumer may safely +see the modified contents of the memory range. It is permissible to batch +synchronizations of multiple RDMA Write operations in a single call by passing +a \fIlocal_segments\fR array that includes all modified memory ranges. The +\fIlocal_segments\fR entries need not contain the same LMR and need not be in +the same Protection Zone. +.sp +.LP +The Consumer must also use \fBdat_lmr_sync_rdma_write()\fR when performing +local writes to a memory range that was or will be the target of incoming RDMA +writes. After performing the local write, the Consumer must call +\fBdat_lmr_sync_rdma_write()\fR before the RDMA Write is initiated. +Conversely, after an RDMA Write completes, the Consumer must call +\fBdat_lmr_sync_rdma_write()\fR before performing a local write to the same +range. +.sp +.LP +If the Provider attribute specifies that this operation is needed and the +Consumer attempts to read from a memory range in an LMR without properly +synchronizing using \fBdat_lmr_sync_rdma_write()\fR, the returned contents are +undefined. If the Consumer attempts to write to a memory range without properly +synchronizing, the contents of the memory range become undefined. +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBDAT_SUCCESS\fR\fR +.ad +.RS 25n +.rt +The operation was successful. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_HANDLE\fR\fR +.ad +.RS 25n +.rt +The DAT handle is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_PARAMETER\fR\fR +.ad +.RS 25n +.rt +One of the parameters is invalid. For example, the address range for a local +segment fell outside the boundaries of the corresponding Local Memory Region or +the LMR handle was invalid. +.RE + +.SH USAGE +.sp +.LP +Determining when an RDMA Write completes and determining which memory range was +modified is the Consumer's responsibility. One possibility is for the RDMA +Write initiator to post a Send DTO message after each RDMA Write that +identifies the range in the body of the Send. The Consumer at the target of the +RDMA Write can receive the message and know when and how to call +\fBdat_lmr_sync_rdma_write()\fR. +.sp +.LP +This call ensures that the Provider receives a coherent view of the buffer +contents after a subsequent remote RDMA Write operation. After the call +completes, the Consumer can be assured that all platform-specific buffer and +cache updates have been performed, and that the LMR range has consistency with +the Provider hardware. Any subsequent read by the Consumer can void this +consistency. The Provider is not required to detect such access. +.sp +.LP +The action performed on the cache before the RDMA Write depends on the cache +type: +.RS +4 +.TP +.ie t \(bu +.el o +I/O noncoherent cache will be flushed. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +CPU noncoherent cache will be invalidated. +.RE +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard: uDAPL, 1.2 +_ +MT-LevelUnsafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBdat_lmr_sync_rdma_read\fR(3DAT), \fBlibdat\fR(3LIB), \fBattributes\fR(5) diff --git a/usr/src/man/man3dat/dat_provider_fini.3dat b/usr/src/man/man3dat/dat_provider_fini.3dat new file mode 100644 index 0000000000..22b26738f1 --- /dev/null +++ b/usr/src/man/man3dat/dat_provider_fini.3dat @@ -0,0 +1,79 @@ +'\" te +.\" This manual page is derived from the DAT/uDAPL 1.2 specification. +.\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH dat_provider_fini 3DAT "16 Jul 2004" "SunOS 5.11" "Direct Access Transport Library Functions" +.SH NAME +dat_provider_fini \- disassociate the Provider from a given IA name +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ldat\fR [ \fIlibrary\fR\&.\|.\|. ] +#include <\fBdat/udat.h\fR> + +void + dat_provider_fini ( + IN const DAT_PROVIDER_INFO *provider_info + ) +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIprovider_info\fR\fR +.ad +.RS 17n +.rt +The information that was provided when dat_provider_init was called. +.RE + +.SH DESCRIPTION +.sp +.LP +A destructor the Registry calls on a Provider before it disassociates the +Provider from a given IA name. +.sp +.LP +The Provider can use this method to undo any initialization it performed when +\fBdat_provider_init\fR(3DAT) was called for the same IA name. The Provider's +implementation of this method should call +\fBdat_registry_remove_provider\fR(3DAT) to unregister its IA Name. If it does +not, the Registry might remove the entry itself. +.sp +.LP +This method can be called for a given IA name at any time after all open +instances of that IA are closed, and is certainly called before the Registry +unloads the Provider library. However, it is not called more than once without +an intervening call to \fBdat_provider_init()\fR for that IA name. +.SH RETURN VALUES +.sp +.LP +No values are returned. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard: uDAPL, 1.1, 1.2 +_ +MT-Level +.TE + +.SH SEE ALSO +.sp +.LP +\fBdat_provider_init\fR(3DAT), \fBdat_registry_remove_provider\fR(3DAT), +\fBlibdat\fR(3LIB), \fBattributes\fR(5) diff --git a/usr/src/man/man3dat/dat_provider_init.3dat b/usr/src/man/man3dat/dat_provider_init.3dat new file mode 100644 index 0000000000..10d924f513 --- /dev/null +++ b/usr/src/man/man3dat/dat_provider_init.3dat @@ -0,0 +1,120 @@ +'\" te +.\" This manual page is derived from the DAT/uDAPL 1.2 specification. +.\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH dat_provider_init 3DAT "16 Jul 2004" "SunOS 5.11" "Direct Access Transport Library Functions" +.SH NAME +dat_provider_init \- locate the Provider in the Static Registry +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ldat\fR [ \fIlibrary\fR\&.\|.\|. ] +#include <\fBdat/udat.h\fR> + +void + dat_provider_init ( + IN const DAT_PROVIDER_INFO *provider_info, + IN const char * instance_data + ) +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIprovider_info\fR\fR +.ad +.RS 17n +.rt +The information that was provided by the Consumer to locate the Provider in the +Static Registry. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIinstance_data\fR\fR +.ad +.RS 17n +.rt +The instance data string obtained from the entry found in the Static Registry +for the Provider. +.RE + +.SH DESCRIPTION +.sp +.LP +A constructor the Registry calls on a Provider before the first call to +\fBdat_ia_open\fR(3DAT) for a given IA name when the Provider is auto-loaded. +An application that explicitly loads a Provider on its own can choose to use +\fBdat_provider_init()\fR just as the Registry would have done for an +auto-loaded Provider. +.sp +.LP +The Provider's implementation of this method must call +\fBdat_registry_add_provider\fR(3DAT), using the IA name in the +\fBprovider_info.ia_name\fR field, to register itself with the Dynamic +Registry. The implementation must not register other IA names at this time. +Otherwise, the Provider is free to perform any initialization it finds useful +within this method. +.sp +.LP +This method is called before the first call to \fBdat_ia_open()\fR for a given +IA name after one of the following has occurred: +.RS +4 +.TP +.ie t \(bu +.el o +The Provider library was loaded into memory. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +The Registry called \fBdat_provider_fini\fR(3DAT) for that IA name. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +The Provider called \fBdat_registry_remove_provider\fR(3DAT) for that IA name +(but it is still the Provider indicated in the Static Registry). +.RE +.sp +.LP +If this method fails, it should ensure that it does not leave its entry in the +Dynamic Registry. +.SH RETURN VALUES +.sp +.LP +No values are returned. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard: uDAPL, 1.1, 1.2 +_ +MT-Level +.TE + +.SH SEE ALSO +.sp +.LP +\fBdat_ia_open\fR(3DAT), \fBdat_provider_fini\fR(3DAT), +\fBdat_registry_add_provider\fR(3DAT), +\fBdat_registry_remove_provider\fR(3DAT), \fBlibdat\fR(3LIB), +\fBattributes\fR(5) diff --git a/usr/src/man/man3dat/dat_psp_create.3dat b/usr/src/man/man3dat/dat_psp_create.3dat new file mode 100644 index 0000000000..ea42c05a03 --- /dev/null +++ b/usr/src/man/man3dat/dat_psp_create.3dat @@ -0,0 +1,386 @@ +'\" te +.\" This manual page is derived from the DAT/uDAPL 1.2 specification. +.\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH dat_psp_create 3DAT "16 Jul 2004" "SunOS 5.11" "Direct Access Transport Library Functions" +.SH NAME +dat_psp_create \- create a persistent Public Service Point +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ldat\fR [ \fIlibrary\fR\&.\|.\|. ] +#include <\fBdat/udat.h\fR> + +DAT_RETURN + dat_psp_create( + IN DAT_IA_HANDLE \fIia_handle\fR, + IN DAT_CONN_QUAL \fIconn_qual\fR, + IN DAT_EVD_HANDLE \fIevd_handle\fR, + IN DAT_PSP_FLAGS \fIpsp_flags\fR, + OUT DAT_PSP_HANDLE *\fIpsp_handle\fR + ) +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIia_handle\fR\fR +.ad +.RS 14n +.rt +Handle for an instance of DAT IA. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIconn_qual\fR\fR +.ad +.RS 14n +.rt +Connection Qualifier of the IA on which the Public Service Point is listening. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIevd_handle\fR\fR +.ad +.RS 14n +.rt +Event Dispatcher that provides the Connection Requested Events to the Consumer. +The size of the event queue for the Event Dispatcher controls the size of the +backlog for the created Public Service Point. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIpsp_flags\fR\fR +.ad +.RS 14n +.rt +Flag that indicates whether the Provider or Consumer creates an Endpoint per +arrived Connection Request. The value of \fBDAT_PSP_PROVIDER\fR indicates that +the Consumer wants to get an Endpoint from the Provider; a value of +\fBDAT_PSP_CONSUMER\fR means the Consumer does not want the Provider to provide +an Endpoint for each arrived Connection Request. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIpsp_handle\fR\fR +.ad +.RS 14n +.rt +Handle to an opaque Public Service Point. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBdat_psp_create()\fR function creates a persistent Public Service Point +that can receive multiple requests for connection and generate multiple +Connection Request instances that are delivered through the specified Event +Dispatcher in Notification events. +.sp +.LP +The \fBdat_psp_create()\fR function is blocking. When the Public Service Point +is created, \fBDAT_SUCCESS\fR is returned and \fIpsp_handle\fR contains a +handle to an opaque Public Service Point Object. +.sp +.LP +There is no explicit backlog for a Public Service Point. Instead, Consumers can +control the size of backlog through the queue size of the associated Event +Dispatcher. +.sp +.LP +The \fIpsp_flags\fR parameter allows Consumers to request that the Provider +create an implicit Endpoint for each incoming Connection Request, or request +that the Provider should not create one per Connection Request. If the Provider +cannot satisfy the request, the operation shall fail and +\fBDAT_MODEL_NOT_SUPPORTED\fR is returned. +.sp +.LP +All Endpoints created by the Provider have \fBDAT_HANDLE_NULL\fR for the +Protection Zone and all Event Dispatchers. The Provider sets up Endpoint +attributes to match the Active side connection request. The Consumer can change +Endpoint parameters. Consumers should change Endpoint parameters, especially PZ +and EVD, and are advised to change parameters for local accesses prior to the +connection request acceptance with the Endpoint. +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBDAT_SUCCESS\fR\fR +.ad +.RS 30n +.rt +The operation was successful. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INSUFFICIENT_RESOURCES\fR\fR +.ad +.RS 30n +.rt +The operation failed due to resource limitations. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_HANDLE\fR\fR +.ad +.RS 30n +.rt +The \fIia_handle\fR or \fIevd_handle\fR parameter is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_PARAMETER\fR\fR +.ad +.RS 30n +.rt +The \fIconn_qual\fR or \fIpsp_flags\fR parameter is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_CONN_QUAL_IN_USE\fR\fR +.ad +.RS 30n +.rt +The specified Connection Qualifier was in use. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_MODEL_NOT_SUPPORTED\fR\fR +.ad +.RS 30n +.rt +The requested Model was not supported by the Provider. +.RE + +.SH USAGE +.sp +.LP +Two uses of a Public Service Point are as follows: +.sp +.ne 2 +.mk +.na +\fBModel 1\fR +.ad +.RS 11n +.rt +For this model, the Provider manipulates a pool of Endpoints for a Public +Service Point. The Provider can use the same pool for more than one Public +Service Point. +.RS +4 +.TP +.ie t \(bu +.el o +The DAT Consumer creates a Public Service Point with a \fIflag\fR set to +\fBDAT_PSP_PROVIDER\fR. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +The Public Service Point does the following: +.RS +4 +.TP +.ie t \(bu +.el o +Collects native transport information reflecting a received Connection Reques +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Creates an instance of Connection Reques +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Creates a Connection Request Notice (event) that includes the Connection +Request instance (thatwhich includes, among others, Public Service Point, its +Connection Qualifier, Provider-generated Local Endpoint, and information about +remote Endpoint) +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Delivers the Connection Request Notice to the Consumer-specified target (CNO) +\fIevd_handle\fR +.sp +The Public Service Point is persistent and continues to listen for incoming +requests for connection. +.RE +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Upon receiving a connection request, or at some time subsequent to that, the +DAT Consumer can modify the provided local Endpoint to match the Connection +Request and must either \fBaccept()\fR or \fBreject()\fR the pending Connection +Request. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +If accepted, the provided Local Endpoint is now in a "connected" state and is +fully usable for this connection, pending only any native transport mandated +RTU (ready-to-use) messages. This includes binding it to the IA port if that +was not done previously. The Consumer is notified that the Endpoint is in +Connected state by a Connection Established Event on the Endpoint +\fIconnect_evd_handle\fR. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +If rejected, control of the Local Endpoint point is returned back to the +Provider and its \fIep_handle\fR is no longer usable by the Consumer. +.RE +.RE + +.sp +.ne 2 +.mk +.na +\fBModel 2\fR +.ad +.RS 11n +.rt +For this model, the Consumer manipulates a pool of Endpoints. Consumers can use +the same pool for more than one Service Point. +.RS +4 +.TP +.ie t \(bu +.el o +DAT Consumer creates a Public Service Point with a \fIflag\fR set to +\fBDAT_PSP_CONSUMER\fR. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Public Service Point: +.RS +4 +.TP +.ie t \(bu +.el o +Collects native transport information reflecting a received Connection Request +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Creates an instance of Connection Request +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Creates a Connection Request Notice (event) that includes the Connection +Request instance (which includes, among others, Public Service Point, its +Connection Qualifier, Provider-generated Local Endpoint and information about +remote Endpoint) +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Delivers the Connection Request Notice to the Consumer-specified target (CNO) +\fIevd_handle\fR +.sp +The Public Service Point is persistent and continues to listen for incoming +requests for connection. +.RE +.RE +.RS +4 +.TP +.ie t \(bu +.el o +The Consumer creates a pool of Endpoints that it uses for accepting Connection +Requests. Endpoints can be created and modified at any time prior to accepting +a Connection Request with that Endpoint. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Upon receiving a connection request or at some time subsequent to that, the DAT +Consumer can modify its local Endpoint to match the Connection Request and must +either \fBaccept()\fR or \fBreject()\fR the pending Connection Request. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +If accepted, the provided Local Endpoint is now in a "connected" state and is +fully usable for this connection, pending only any native transport mandated +RTU messages. This includes binding it to the IA port if that was not done +previously. The Consumer is notified that the Endpoint is in Connected state by +a Connection Established Event on the Endpoint \fIconnect_evd_handle\fR. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +If rejected, the Consumer does not have to provide any Endpoint for +\fBdat_cr_reject\fR(3DAT). +.RE +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard: uDAPL, 1.1, 1.2 +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBdat_cr_reject\fR(3DAT), \fBlibdat\fR(3LIB), \fBattributes\fR(5) diff --git a/usr/src/man/man3dat/dat_psp_create_any.3dat b/usr/src/man/man3dat/dat_psp_create_any.3dat new file mode 100644 index 0000000000..2bf7c8a03c --- /dev/null +++ b/usr/src/man/man3dat/dat_psp_create_any.3dat @@ -0,0 +1,223 @@ +'\" te +.\" This manual page is derived from the DAT/uDAPL 1.2 specification. +.\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH dat_psp_create_any 3DAT "16 Jul 2004" "SunOS 5.11" "Direct Access Transport Library Functions" +.SH NAME +dat_psp_create_any \- create a persistent Public Service Point +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ldat\fR [ \fIlibrary\fR\&.\|.\|. ] +#include <\fBdat/udat.h\fR> + +DAT_RETURN + dat_psp_create_any( + IN DAT_IA_HANDLE \fIia_handle\fR, + IN DAT_CONN_QUAL \fIconn_qual\fR, + IN DAT_EVD_HANDLE \fIevd_handle\fR, + IN DAT_PSP_FLAGS \fIpsp_flags\fR, + OUT DAT_PSP_HANDLE *\fIpsp_handle\fR + ) +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIia_handle\fR\fR +.ad +.RS 14n +.rt +Handle for an instance of DAT IA. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIconn_qual\fR\fR +.ad +.RS 14n +.rt +Connection Qualifier of the IA on which the Public Service Point is listening. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIevd_handle\fR\fR +.ad +.RS 14n +.rt +Event Dispatcher that provides the Connection Requested Events to the Consumer. +The size of the event queue for the Event Dispatcher controls the size of the +backlog for the created Public Service Point. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIpsp_flags\fR\fR +.ad +.RS 14n +.rt +Flag that indicates whether the Provider or Consumer creates an Endpoint per +arrived Connection Request. The value of \fBDAT_PSP_PROVIDER\fR indicates that +the Consumer wants to get an Endpoint from the Provider; a value of +\fBDAT_PSP_CONSUMER\fR means the Consumer does not want the Provider to provide +an Endpoint for each arrived Connection Request. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIpsp_handle\fR\fR +.ad +.RS 14n +.rt +Handle to an opaque Public Service Point. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBdat_psp_create_any()\fR function creates a persistent Public Service +Point that can receive multiple requests for connection and generate multiple +Connection Request instances that are delivered through the specified Event +Dispatcher in Notification events. +.sp +.LP +The \fBdat_psp_create_any()\fR function allocates an unused Connection +Qualifier, creates a Public Service point for it, and returns both the +allocated Connection Qualifier and the created Public Service Point to the +Consumer. +.sp +.LP +The allocated Connection Qualifier should be chosen from "nonprivileged" ports +that are not currently used or reserved by any user or kernel Consumer or host +ULP of the IA. The format of allocated Connection Qualifier returned is +specific to IA transport type. +.sp +.LP +The \fBdat_psp_create_any()\fR function is blocking. When the Public Service +Point is created, \fBDAT_SUCCESS\fR is returned, \fIpsp_handle\fR contains a +handle to an opaque Public Service Point Object, and \fIconn_qual\fR contains +the allocated Connection Qualifier. When return is not \fBDAT_SUCCESS\fR, +\fIpsp_handle\fR and \fIconn_qual\fR return values are undefined. +.sp +.LP +There is no explicit backlog for a Public Service Point. Instead, Consumers can +control the size of backlog through the queue size of the associated Event +Dispatcher. +.sp +.LP +The \fIpsp_flags\fR parameter allows Consumers to request that the Provider +create an implicit Endpoint for each incoming Connection Request, or request +that the Provider should not create one per Connection Request. If the Provider +cannot satisfy the request, the operation shall fail and +\fBDAT_MODEL_NOT_SUPPORTED\fR is returned. +.sp +.LP +All Endpoints created by the Provider have \fBDAT_HANDLE_NULL\fR for the +Protection Zone and all Event Dispatchers. The Provider sets up Endpoint +attributes to match the Active side connection request. The Consumer can change +Endpoint parameters. Consumers should change Endpoint parameters, especially PZ +and EVD, and are advised to change parameters for local accesses prior to the +connection request acceptance with the Endpoint. +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBDAT_SUCCESS\fR\fR +.ad +.RS 30n +.rt +The operation was successful. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INSUFFICIENT_RESOURCES\fR\fR +.ad +.RS 30n +.rt +The operation failed due to resource limitations. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_HANDLE\fR\fR +.ad +.RS 30n +.rt +The \fIia_handle\fR or \fIevd_handle\fR parameter is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_PARAMETER\fR\fR +.ad +.RS 30n +.rt +The \fIconn_qual\fR or \fIpsp_flags\fR parameter is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_CONN_QUAL_UNAVAILABLE\fR\fR +.ad +.RS 30n +.rt +No Connection Qualifiers available. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_MODEL_NOT_SUPPORTED\fR\fR +.ad +.RS 30n +.rt +The requested Model was not supported by the Provider. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard: uDAPL, 1.1, 1.2 +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBlibdat\fR(3LIB), \fBattributes\fR(5) diff --git a/usr/src/man/man3dat/dat_psp_free.3dat b/usr/src/man/man3dat/dat_psp_free.3dat new file mode 100644 index 0000000000..c8a2f2a0a1 --- /dev/null +++ b/usr/src/man/man3dat/dat_psp_free.3dat @@ -0,0 +1,111 @@ +'\" te +.\" This manual page is derived from the DAT/uDAPL 1.2 specification. +.\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH dat_psp_free 3DAT "16 Jul 2004" "SunOS 5.11" "Direct Access Transport Library Functions" +.SH NAME +dat_psp_free \- destroy an instance of the Public Service Point +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ldat\fR [ \fIlibrary\fR\&.\|.\|. ] +#include <\fBdat/udat.h\fR> + +DAT_RETURN + dat_psp_free ( + IN DAT_PSP_HANDLE psp_handle + ) +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIpsp_handle\fR\fR +.ad +.RS 14n +.rt +Handle for an instance of the Public Service Point. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBdat_psp_free()\fR function destroys a specified instance of the Public +Service Point. +.sp +.LP +Any incoming Connection Requests for the Connection Qualifier on the destroyed +Service Point it had been listening on are automatically rejected by the +Provider with the return analogous to the no listening Service Point. +.sp +.LP +The behavior of the Connection Requests in progress is undefined and left to an +implementation. But it must be consistent. This means that either a Connection +Requested Event has been generated for the Event Dispatcher associated with the +Service Point, including the creation of the Connection Request instance, or +the Connection Request is rejected by the Provider without any local +notification. +.sp +.LP +This operation shall have no effect on previously generated Connection +Requested Events. This includes Connection Request instances and, potentially, +Endpoint instances created by the Provider. +.sp +.LP +The behavior of this operation with creation of a Service Point on the same +Connection Qualifier at the same time is not defined. Consumers are advised to +avoid this scenario. +.sp +.LP +Use of the handle of the destroyed Public Service Point in any consequent +operation fails. +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBDAT_SUCCESS\fR\fR +.ad +.RS 22n +.rt +The operation was successful. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_HANDLE\fR\fR +.ad +.RS 22n +.rt +The \fIpsp_handle\fR parameter is invalid. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard: uDAPL, 1.1, 1.2 +_ +MT-LevelUnsafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBlibdat\fR(3LIB), \fBattributes\fR(5) diff --git a/usr/src/man/man3dat/dat_psp_query.3dat b/usr/src/man/man3dat/dat_psp_query.3dat new file mode 100644 index 0000000000..e7838eb87c --- /dev/null +++ b/usr/src/man/man3dat/dat_psp_query.3dat @@ -0,0 +1,127 @@ +'\" te +.\" This manual page is derived from the DAT/uDAPL 1.2 specification. +.\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH dat_psp_query 3DAT "16 Jul 2004" "SunOS 5.11" "Direct Access Transport Library Functions" +.SH NAME +dat_psp_query \- provide parameters of the Public Service Point +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ldat\fR [ \fIlibrary\fR\&.\|.\|. ] +#include <\fBdat/udat.h\fR> + +DAT_RETURN + dat_psp_query ( + IN DAT_PSP_HANDLE psp_handle, + IN DAT_PSP_PARAM_MASK psp_param_mask, + OUT DAT_PSP_PARAM *psp_param + ) +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIpsp_handle\fR\fR +.ad +.RS 18n +.rt +Handle for an instance of Public Service Point. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIpsp_param_mask\fR\fR +.ad +.RS 18n +.rt +Mask for PSP parameters. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIpsp_param\fR\fR +.ad +.RS 18n +.rt +Pointer to a Consumer-allocated structure that Provider fills for +Consumer-requested parameters. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBdat_psp_query()\fR function provides to the Consumer parameters of the +Public Service Point. Consumer passes in a pointer to the Consumer allocated +structures for PSP parameters that Provider fills. +.sp +.LP +The \fIpsp_param_mask\fR parameter allows Consumers to specify which parameters +they would like to query. The Provider will return values for +\fIpsp_param_mask\fR requested parameters. The Provider may return the value +for any of the other parameters. +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBDAT_SUCCESS\fR\fR +.ad +.RS 25n +.rt +The operation was successful. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_HANDLE\fR\fR +.ad +.RS 25n +.rt +The \fIpsp_handle\fR parameter is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_PARAMETER\fR\fR +.ad +.RS 25n +.rt +The \fIpsp_param_mask\fR parameter is invalid. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard: uDAPL, 1.1, 1.2 +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBlibdat\fR(3LIB), \fBattributes\fR(5) diff --git a/usr/src/man/man3dat/dat_pz_create.3dat b/usr/src/man/man3dat/dat_pz_create.3dat new file mode 100644 index 0000000000..71688b695d --- /dev/null +++ b/usr/src/man/man3dat/dat_pz_create.3dat @@ -0,0 +1,120 @@ +'\" te +.\" This manual page is derived from the DAT/uDAPL 1.2 specification. +.\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH dat_pz_create 3DAT "16 Jul 2004" "SunOS 5.11" "Direct Access Transport Library Functions" +.SH NAME +dat_pz_create \- create an instance of the Protection Zone +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ldat\fR [ \fIlibrary\fR\&.\|.\|. ] +#include <\fBdat/udat.h\fR> + +DAT_RETURN + dat_pz_create ( + IN DAT_IA_HANDLE ia_handle, + OUT DAT_PZ_HANDLE *pz_handle + ) +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIia_handle\fR\fR +.ad +.RS 13n +.rt +Handle for an open instance of the IA. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIpz_handle\fR\fR +.ad +.RS 13n +.rt +Handle for the created instance of Protection Zone. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBdat_pz_create()\fR function creates an instance of the Protection Zone. +The Protection Zone provides Consumers a mechanism for association Endpoints +with LMRs and RMRs to provide protection for local and remote memory accesses +by DTOs. +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBDAT_SUCCESS\fR\fR +.ad +.RS 30n +.rt +The operation was successful. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INSUFFICIENT_RESOURCES\fR\fR +.ad +.RS 30n +.rt +The operation failed due to resource limitations. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_PARAMETER\fR\fR +.ad +.RS 30n +.rt +Invalid parameter. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_HANDLE\fR\fR +.ad +.RS 30n +.rt +The \fIia_handle\fR parameter is invalid. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard: uDAPL, 1.1, 1.2 +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBlibdat\fR(3LIB), \fBattributes\fR(5) diff --git a/usr/src/man/man3dat/dat_pz_free.3dat b/usr/src/man/man3dat/dat_pz_free.3dat new file mode 100644 index 0000000000..fc491d4f26 --- /dev/null +++ b/usr/src/man/man3dat/dat_pz_free.3dat @@ -0,0 +1,101 @@ +'\" te +.\" This manual page is derived from the DAT/uDAPL 1.2 specification. +.\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH dat_pz_free 3DAT "16 Jul 2004" "SunOS 5.11" "Direct Access Transport Library Functions" +.SH NAME +dat_pz_free \- destroy an instance of the Protection Zone +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ldat\fR [ \fIlibrary\fR\&.\|.\|. ] +#include <\fBdat/udat.h\fR> + +DAT_RETURN + dat_pz_free ( + IN DAT_PZ_HANDLE pz_handle + ) +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIpz_handle\fR\fR +.ad +.RS 13n +.rt +Handle for an instance of Protection Zone to be destroyed. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBdat_pz_free()\fR function destroys an instance of the Protection Zone. +The Protection Zone cannot be destroyed if it is in use by an Endpoint, LMR, or +RMR. +.sp +.LP +Use of the handle of the destroyed Protection Zone in any subsequent operation +except for \fBdat_pz_free()\fR fails. +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBDAT_SUCCESS\fR\fR +.ad +.RS 22n +.rt +The operation was successful. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_STATE\fR\fR +.ad +.RS 22n +.rt +Parameter in an invalid state. The Protection Zone was in use by Endpoint, LMR, +or RMR instances. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_HANDLE\fR\fR +.ad +.RS 22n +.rt +The \fIpz_handle\fR parameter is invalid. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard: uDAPL, 1.1, 1.2 +_ +MT-LevelUnsafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBlibdat\fR(3LIB), \fBattributes\fR(5) diff --git a/usr/src/man/man3dat/dat_pz_query.3dat b/usr/src/man/man3dat/dat_pz_query.3dat new file mode 100644 index 0000000000..94be1a2b0a --- /dev/null +++ b/usr/src/man/man3dat/dat_pz_query.3dat @@ -0,0 +1,126 @@ +'\" te +.\" This manual page is derived from the DAT/uDAPL 1.2 specification. +.\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH dat_pz_query 3DAT "16 Jul 2004" "SunOS 5.11" "Direct Access Transport Library Functions" +.SH NAME +dat_pz_query \- provides parameters of the Protection Zone +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ldat\fR [ \fIlibrary\fR\&.\|.\|. ] +#include <\fBdat/udat.h\fR> + +DAT_RETURN + dat_pz_query ( + IN DAT_PZ_HANDLE pz_handle, + IN DAT_PZ_PARAM_MASK pz_param_mask, + OUT DAT_PZ_PARAM *pz_param + ) +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIpz_handle:\fR\fR +.ad +.RS 18n +.rt +Handle for the created instance of the Protection Zone. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIpz_param_mask:\fR\fR +.ad +.RS 18n +.rt +Mask for Protection Zone parameters. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIpz_param:\fR\fR +.ad +.RS 18n +.rt +Pointer to a Consumer-allocated structure that the Provider fills with +Protection Zone parameters. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBdat_pz_query()\fR function provides the Consumer parameters of the +Protection Zone. The Consumer passes in a pointer to the Consumer-allocated +structures for Protection Zone parameters that the Provider fills. +.sp +.LP +The \fIpz_param_mask\fR parameter allows Consumers to specify which parameters +to query. The Provider returns values for \fIpz_param_mask\fR requested +parameters. The Provider can return values for any other parameters. +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBDAT_SUCCESS\fR\fR +.ad +.RS 25n +.rt +The operation was successful. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_PARAMETER\fR\fR +.ad +.RS 25n +.rt +The \fIpz_param_mask\fR parameter is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_HANDLE\fR\fR +.ad +.RS 25n +.rt +The \fIpz_handle\fR parameter is invalid. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard: uDAPL, 1.1, 1.2 +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBlibdat\fR(3LIB), \fBattributes\fR(5) diff --git a/usr/src/man/man3dat/dat_registry_add_provider.3dat b/usr/src/man/man3dat/dat_registry_add_provider.3dat new file mode 100644 index 0000000000..5019f73a3c --- /dev/null +++ b/usr/src/man/man3dat/dat_registry_add_provider.3dat @@ -0,0 +1,130 @@ +'\" te +.\" This manual page is derived from the DAT/uDAPL 1.2 specification. +.\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH dat_registry_add_provider 3DAT "16 Jul 2004" "SunOS 5.11" "Direct Access Transport Library Functions" +.SH NAME +dat_registry_add_provider \- declare the Provider with the Dynamic Registry +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ldat\fR [ \fIlibrary\fR\&.\|.\|. ] +#include <\fBdat/udat.h\fR> + +DAT_RETURN + dat_registry_add_provider ( + IN const DAT_PROVIDER *provider, + IN const DAT_PROVIDER_INFO *provider_info + ) +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIprovider\fR\fR +.ad +.RS 17n +.rt +Self-description of a Provider. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIprovider_info\fR\fR +.ad +.RS 17n +.rt +Attributes of the Provider. +.RE + +.SH DESCRIPTION +.sp +.LP +The Provider declares itself with the Dynamic Registry. Note that the caller +can choose to register itself multiple times, for example once for each port. +The choice of what to virtualize is up to the Provider. Each registration +provides an Interface Adapter to DAT. Each Provider must have a unique name. +.sp +.LP +The same IA Name cannot be added multiple times. An attempt to register the +same IA Name again results in an error with the return value +\fBDAT_PROVIDER_ALREADY_REGISTERED\fR. +.sp +.LP +The contents of provider_info must be the same as those the Consumer uses in +the call to \fBdat_ia_open\fR(3DAT) directly, or the ones provided indirectly +defined by the header files with which the Consumer compiled. +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBDAT_SUCCESS\fR\fR +.ad +.sp .6 +.RS 4n +The operation was successful. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INSUFFICIENT_RESOURCES\fR\fR +.ad +.sp .6 +.RS 4n +The maximum number of Providers was already registered. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_PARAMETER\fR\fR +.ad +.sp .6 +.RS 4n +Invalid parameter. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_PROVIDER_ALREADY_REGISTERED\fR\fR +.ad +.sp .6 +.RS 4n +Invalid or nonunique name. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard: uDAPL, 1.1, 1.2 +_ +MT-Level +.TE + +.SH SEE ALSO +.sp +.LP +\fBdat_ia_open\fR(3DAT), \fBlibdat\fR(3LIB), \fBattributes\fR(5) diff --git a/usr/src/man/man3dat/dat_registry_list_providers.3dat b/usr/src/man/man3dat/dat_registry_list_providers.3dat new file mode 100644 index 0000000000..3b01c38793 --- /dev/null +++ b/usr/src/man/man3dat/dat_registry_list_providers.3dat @@ -0,0 +1,168 @@ +'\" te +.\" This manual page is derived from the DAT/uDAPL 1.2 specification. +.\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH dat_registry_list_providers 3DAT "16 Jul 2004" "SunOS 5.11" "Direct Access Transport Library Functions" +.SH NAME +dat_registry_list_providers \- obtain a list of available pProviders from the +Static Registry +.SH SYNOPSIS +.LP +.nf +typedef struct dat_provider_info { + char ia_name[DAT_NAME_MAX_LENGTH]; + DAT_UINT32 dapl_version_major; + DAT_UINT32 dapl_version_minor; + DAT_BOOLEAN is_thread_safe; + } DAT_PROVIDER_INFO; + +cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ldat\fR [ \fIlibrary\fR\&.\|.\|. ] +#include <\fBdat/udat.h\fR> + +DAT_RETURN + dat_registry_list_providers ( + IN DAT_COUNT max_to_return, + OUT DAT_COUNT *number_entries, + OUT DAT_PROVIDER_INFO *(dat_provider_list[]) + ) +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fImax_to_return\fR\fR +.ad +.RS 21n +.rt +Maximum number of entries that can be returned to the Consumer in the +\fIdat_provider_list\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fInumber_entries\fR\fR +.ad +.RS 21n +.rt +The actual number of entries returned to the Consumer in the +\fIdat_provider_list\fR if successful or the number of Providers available. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdat_provider_list\fR\fR +.ad +.RS 21n +.rt +Points to an array of \fBDAT_PROVIDER_INFO\fR pointers supplied by the +Consumer. Each Provider's information will be copied to the destination +specified. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBdat_registry_list_providers()\fR function allows the Consumer to obtain +a list of available Providers from the Static Registry. The information +provided is the Interface Adapter name, the uDAPL/kDAPL API version supported, +and whether the provided version is thread-safe. The Consumer can examine the +attributes to determine which (if any) Interface Adapters it wants to open. +This operation has no effect on the Registry itself. +.sp +.LP +The Registry can open an IA using a Provider whose \fIdapl_version_minor\fR is +larger than the one the Consumer requests if no Provider entry matches exactly. +Therefore, Consumers should expect that an IA can be opened successfully as +long as at least one Provider entry returned by +\fBdat_registry_list_providers()\fR matches the \fIia_name\fR, +\fIdapl_version_major\fR, and \fIis_thread_safe\fR fields exactly, and has a +\fIdapl_version_minor\fR that is equal to or greater than the version +requested. +.sp +.LP +If the operation is successful, the returned value is \fBDAT_SUCCESS\fR and +\fInumber_entries\fR indicates the number of entries filled by the registry in +\fIdat_provider_list\fR. +.sp +.LP +If the operation is not successful, then \fInumber_entries\fR returns the +number of entries in the registry. Consumers can use this return to allocate +\fIdat_provider_list\fR large enough for the registry entries. This number is +just a snapshot at the time of the call and may be changed by the time of the +next call. If the operation is not successful, then the content of +\fIdat_provider_list\fR is not defined. +.sp +.LP +If \fIdat_provider_list\fR is too small, including pointing to \fINULL\fR for +the registry entries, then the operation fails with the return +\fBDAT_INVALID_PARAMETER\fR. +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBDAT_SUCCESS\fR\fR +.ad +.RS 25n +.rt +The operation was successful. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_PARAMETER\fR\fR +.ad +.RS 25n +.rt +Invalid parameter. For example, \fIdat_provider_list\fR is too small or +\fINULL\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INTERNAL_ERROR\fR\fR +.ad +.RS 25n +.rt +Internal error. The DAT static registry is missing. +.RE + +.SH USAGE +.sp +.LP +\fBDAT_NAME_MAX_LENGTH\fR includes the null character for string termination. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard: uDAPL, 1.1, 1.2 +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBlibdat\fR(3LIB), \fBattributes\fR(5) diff --git a/usr/src/man/man3dat/dat_registry_remove_provider.3dat b/usr/src/man/man3dat/dat_registry_remove_provider.3dat new file mode 100644 index 0000000000..3a1c742a93 --- /dev/null +++ b/usr/src/man/man3dat/dat_registry_remove_provider.3dat @@ -0,0 +1,114 @@ +'\" te +.\" This manual page is derived from the DAT/uDAPL 1.2 specification. +.\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH dat_registry_remove_provider 3DAT "16 Jul 2004" "SunOS 5.11" "Direct Access Transport Library Functions" +.SH NAME +dat_registry_remove_provider \- unregister the Provider from the Dynamic +Registry +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ldat\fR [ \fIlibrary\fR\&.\|.\|. ] +#include <\fBdat/udat.h\fR> + +DAT_RETURN + dat_registry_remove_provider ( + IN DAT_PROVIDER *provider + IN const DAT_PROVIDER_INFO *provider_info + ) +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIprovider\fR\fR +.ad +.RS 17n +.rt +Self-description of a Provider. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIprovider_info\fR\fR +.ad +.RS 17n +.rt +Attributes of the Provider. +.RE + +.SH DESCRIPTION +.sp +.LP +The Provider removes itself from the Dynamic Registry. It is the Provider's +responsibility to complete its sessions. Removal of the registration only +prevents new sessions. +.sp +.LP +The Provider cannot be removed while it is in use. An attempt to remove the +Provider while it is in use results in an error with the return code +\fBDAT_PROVIDER_IN_USE\fR. +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBDAT_SUCCESS\fR\fR +.ad +.RS 25n +.rt +The operation was successful. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_PARAMETER\fR\fR +.ad +.RS 25n +.rt +Invalid parameter. The Provider was not found. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_PROVIDER_IN_USE\fR\fR +.ad +.RS 25n +.rt +The Provider was in use. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard: uDAPL, 1.1, 1.2 +_ +MT-Level +.TE + +.SH SEE ALSO +.sp +.LP +\fBlibdat\fR(3LIB), \fBattributes\fR(5) diff --git a/usr/src/man/man3dat/dat_rmr_bind.3dat b/usr/src/man/man3dat/dat_rmr_bind.3dat new file mode 100644 index 0000000000..6bd6ee3102 --- /dev/null +++ b/usr/src/man/man3dat/dat_rmr_bind.3dat @@ -0,0 +1,435 @@ +'\" te +.\" This manual page is derived from the DAT/uDAPL 1.2 specification. +.\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH dat_rmr_bind 3DAT "16 Jul 2004" "SunOS 5.11" "Direct Access Transport Library Functions" +.SH NAME +dat_rmr_bind \- bind the RMR to the specified memory region within an LMR +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ldat\fR [ \fIlibrary\fR\&.\|.\|. ] +#include <\fBdat/udat.h\fR> + +DAT_RETURN + dat_rmr_bind( + IN DAT_RMR_HANDLE rmr_handle, + IN DAT_LMR_TRIPLET *lmr_triplet, + IN DAT_MEM_PRIV_FLAGS mem_privileges, + IN DAT_EP_HANDLE ep_handle, + IN DAT_RMR_COOKIE user_cookie, + IN DAT_COMPLETION_FLAGS completion_flags, + OUT DAT_RMR_CONTEXT *rmr_context + ) +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIrmr_handle\fR\fR +.ad +.RS 20n +.rt +Handle for an RMR instance. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIlmr_triplet\fR\fR +.ad +.RS 20n +.rt +A pointer to an \fIlmr_triplet\fR that defines the memory region of the LMR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fImem_privileges\fR\fR +.ad +.RS 20n +.rt +Consumer-requested memory access privileges for the registered remote memory +region. The Default value is \fBDAT_MEM_PRIV_NONE_FLAG\fR. The constant value +\fBDAT_MEM_PRIV_ALL_FLAG\fR = 0x33, which specifies both Read and Write +privileges, is also defined. Memory privilege definitions are as follows: +.sp +.ne 2 +.mk +.na +\fBRemote Read\fR +.ad +.RS 16n +.rt +\fBDAT_MEM_PRIV_REMOTE_READ_FLAG\fR +.sp +.ne 2 +.mk +.na +\fB0x02\fR +.ad +.RS 8n +.rt +Remote read access requested. +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fBRemote Write\fR +.ad +.RS 16n +.rt +\fBDAT_MEM_PRIV_REMOTE_WRITE_FLAG\fR +.sp +.ne 2 +.mk +.na +\fB0x20\fR +.ad +.RS 8n +.rt +Remote write access requested. +.RE + +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIep_handle\fR\fR +.ad +.RS 20n +.rt +Endpoint to which \fBdat_rmr_bind()\fR is posted. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIuser_cookie\fR\fR +.ad +.RS 20n +.rt +User-provided cookie that is returned to a Consumer at the completion of the +\fBdat_rmr_bind()\fR. Can be \fINULL\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcompletion_flags\fR\fR +.ad +.RS 20n +.rt +Flags for RMR Bind. The default \fBDAT_COMPLETION_DEFAULT_FLAG\fR is 0. Flag +definitions are as follows: +.sp +.ne 2 +.mk +.na +\fBCompletion Suppression\fR +.ad +.RS 30n +.rt +\fBDAT_COMPLETION_SUPPRESS_FLAG\fR +.sp +.ne 2 +.mk +.na +\fB0x01\fR +.ad +.RS 8n +.rt +Suppress successful Completion. +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fBNotification of Completion\fR +.ad +.RS 30n +.rt +\fB\fR\fBDAT_COMPLETION_UNSIGNALLED_FLAG\fR +.sp +.ne 2 +.mk +.na +\fB0x04\fR +.ad +.RS 8n +.rt +Non-notification completion. Local Endpoint must be configured for Notification +Suppression. +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fBBarrier Fence\fR +.ad +.RS 30n +.rt +\fB\fR\fBDAT_COMPLETION_BARRIER_FENCE_FLAG\fR +.sp +.ne 2 +.mk +.na +\fB0x08\fR +.ad +.RS 8n +.rt +Request for Barrier Fence. +.RE + +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIrmr_context\fR\fR +.ad +.RS 20n +.rt +New \fIrmr_context\fR for the bound RMR suitable to be shared with a remote +host. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBdat_rmr_bind()\fR function binds the RMR to the specified memory region +within an LMR and provides the new \fIrmr_context\fR value. The +\fBdat_rmr_bind()\fR operation is a lightweight asynchronous operation that +generates a new \fIrmr_context\fR. The Consumer is notified of the completion +of this operation through a \fIrmr_bind\fR Completion event on the +\fIrequest_evd_handle\fR of the specified Endpoint \fIep_handle\fR. +.sp +.LP +The return value of \fIrmr_context\fR can be transferred by local Consumer to a +Consumer on a remote host to be used for an RDMA DTO. The use of +\fIrmr_context\fR by a remote host for an RDMA DTO prior to the completion of +the \fBdat_rmr_bind()\fR can result in an error and a broken connection. The +local Consumer can ensure that the remote Consumer does not have +\fIrmr_context\fR before \fBdat_rmr_bind()\fR is completed. One way is to +"wait" for the completion \fBdat_rmr_bind()\fR on the \fIrmr_bind\fR Event +Dispatcher of the specified Endpoint \fIep_handle\fR. Another way is to send +\fIrmr_context\fR in a Send DTO over the connection of the Endpoint +\fIep_handle\fR. The barrier-fencing behavior of the \fBdat_rmr_bind()\fR with +respect to Send and RDMA DTOs ensures that a Send DTO does not start until +\fBdat_rmr_bind()\fR completed. +.sp +.LP +The \fBdat_rmr_bind()\fR function automatically fences all Send, RDMA Read, and +RDMA Write DTOs and \fBdat_rmr_bind()\fR operations submitted on the Endpoint +\fIep_handle\fR after the \fBdat_rmr_bind()\fR. Therefore, none of these +operations starts until \fBdat_rmr_bind()\fR is completed. +.sp +.LP +If the RMR Bind fails after \fBdat_rmr_bind()\fR returns, connection of +\fIep_handle\fR is broken. The Endpoint transitions into a +\fBDAT_EP_STATE_DISCONNECTED\fR state and the \fBDAT_CONNECTION_EVENT_BROKEN\fR +event is delivered to the \fIconnect_evd_handle\fR of the Endpoint. +.sp +.LP +The \fBdat_rmr_bind()\fR function employs fencing to ensure that operations +sending the RMR Context on the same Endpoint as the bind specified cannot +result in an error from the peer side using the delivered RMR Context too soon. +One method, used by InfiniBand, is to ensure that none of these operations +start on the Endpoint until after the bind is completed. Other transports can +employ different methods to achieve the same goal. +.sp +.LP +Any RDMA DTO that uses the previous value of \fIrmr_context\fR after the +\fBdat_rmr_bind()\fR is completed fail and report a protection violation. +.sp +.LP +By default, \fBdat_rmr_bind()\fR generates notification completions. +.sp +.LP +The \fImem_privileges\fR parameter allows Consumers to restrict the type of +remote accesses to the registered RMR by RDMA DTOs. Providers whose underlying +Transports require that privileges of the requested RMR and the associated LMR +match, that is +.RS +4 +.TP +.ie t \(bu +.el o +Set RMR's \fBDAT_MEM_PRIV_REMOTE_READ_FLAG\fR requires that LMR's +\fBDAT_MEM_PRIV_LOCAL_READ_FLAG\fR is also set, +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Set RMR's \fBDAT_MEM_PRIV_REMOTE_WRITE_FLAG\fR requires that LMR's +\fBDAT_MEM_PRIV_LOCAL_WRITE_FLAG\fR is also set, +.RE +.sp +.LP +or the operation fails and returns \fBDAT_PRIVILEGES_VIOLATION\fR. +.sp +.LP +In the \fIlmr_triplet\fR, the value of \fIlength\fR of zero means that the +Consumer does not want to associate an RMR with any memory region within the +LMR and the return value of \fIrmr_context\fR for that case is undefined. +.sp +.LP +The completion of the posted RMR Bind is reported to the Consumer +asynchronously through a DTO Completion event based on the specified +\fIcompletion_flags\fR value. The value of +\fBDAT_COMPLETION_UNSIGNALLED_FLAG\fR is only valid if the Endpoint Request +Completion Flags \fBDAT_COMPLETION_UNSIGNALLED_FLAG\fR. Otherwise, +\fBDAT_INVALID_PARAMETER\fR is returned. +.sp +.LP +The \fIuser_cookie\fR parameter allows Consumers to have unique identifiers for +each \fBdat_rmr_bind()\fR. These identifiers are completely under user control +and are opaque to the Provider. The Consumer is not required to ensure the +uniqueness of the \fIuser_cookie\fR value. The \fIuser_cookie\fR is returned to +the Consumer in the \fIrmr_bind\fR Completion event for this operation. +.sp +.LP +The operation is valid for the Endpoint in the \fBDAT_EP_STATE_CONNECTED\fR and +\fBDAT_EP_STATE_DISCONNECTED\fR states. If the operation returns successfully +for the Endpoint in \fBDAT_EP_STATE_DISCONNECTED\fR state, the posted RMR Bind +is immediately flushed to \fIrequest_evd_handle\fR. +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBDAT_SUCCESS\fR\fR +.ad +.RS 30n +.rt +The operation was successful. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INSUFFICIENT_RESOURCES\fR\fR +.ad +.RS 30n +.rt +The operation failed due to resource limitations. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_PARAMETER\fR\fR +.ad +.RS 30n +.rt +Invalid parameter. For example, the \fItarget_address\fR or +\fIsegment_length\fR exceeded the limits of the existing LMR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_HANDLE\fR\fR +.ad +.RS 30n +.rt +Invalid DAT handle. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_STATE\fR\fR +.ad +.RS 30n +.rt +Parameter in an invalid state. Endpoint was not in the a +\fBDAT_EP_STATE_CONNECTED\fR or \fBDAT_EP_STATE_DISCONNECTED\fR state. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_MODEL_NOT_SUPPORTED\fR\fR +.ad +.RS 30n +.rt +The requested Model was not supported by the Provider. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_PRIVILEGES_VIOLATION\fR\fR +.ad +.RS 30n +.rt +Privileges violation for local or remote memory access. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_PROTECTION_VIOLATION\fR\fR +.ad +.RS 30n +.rt +Protection violation for local or remote memory access. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard: uDAPL, 1.1, 1.2 +_ +MT-LevelUnsafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBlibdat\fR(3LIB), \fBattributes\fR(5) diff --git a/usr/src/man/man3dat/dat_rmr_create.3dat b/usr/src/man/man3dat/dat_rmr_create.3dat new file mode 100644 index 0000000000..8d986be714 --- /dev/null +++ b/usr/src/man/man3dat/dat_rmr_create.3dat @@ -0,0 +1,117 @@ +'\" te +.\" This manual page is derived from the DAT/uDAPL 1.2 specification. +.\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH dat_rmr_create 3DAT "16 Jul 2004" "SunOS 5.11" "Direct Access Transport Library Functions" +.SH NAME +dat_rmr_create \- create an RMR for the specified Protection Zone +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ldat\fR [ \fIlibrary\fR\&.\|.\|. ] +#include <\fBdat/udat.h\fR> + +DAT_RETURN + dat_rmr_create( + IN DAT_PZ_HANDLE pz_handle, + OUT DAT_RMR_HANDLE *rmr_handle + ) +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIpz_handle\fR\fR +.ad +.RS 14n +.rt +Handle for an instance of the Protection Zone. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIrmr_handle\fR\fR +.ad +.RS 14n +.rt +Handle for the created instance of an RMR. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBdat_rmr_create()\fR function creates an RMR for the specified Protection +Zone. This operation is relatively heavy. The created RMR can be bound to a +memory region within the LMR through a lightweight \fBdat_rmr_bind\fR(3DAT) +operation that generates \fIrmr_context\fR. +.sp +.LP +If the operation fails (does not return \fBDAT_SUCCESS\fR), the return values +of \fIrmr_handle\fR are undefined and Consumers should not use them. +.sp +.LP +The \fIpz_handle\fR parameter provide Consumers a way to restrict access to an +RMR by authorized connection only. +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBDAT_SUCCESS\fR\fR +.ad +.RS 30n +.rt +The operation was successful. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INSUFFICIENT_RESOURCES\fR\fR +.ad +.RS 30n +.rt +The operation failed due to resource limitations. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_HANDLE\fR\fR +.ad +.RS 30n +.rt +The \fIpz_handle\fR parameter is invalid. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard: uDAPL, 1.1, 1.2 +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBdat_rmr_bind\fR(3DAT) , \fBlibdat\fR(3LIB), \fBattributes\fR(5) diff --git a/usr/src/man/man3dat/dat_rmr_free.3dat b/usr/src/man/man3dat/dat_rmr_free.3dat new file mode 100644 index 0000000000..a4c420dece --- /dev/null +++ b/usr/src/man/man3dat/dat_rmr_free.3dat @@ -0,0 +1,100 @@ +'\" te +.\" This manual page is derived from the DAT/uDAPL 1.2 specification. +.\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH dat_rmr_free 3DAT "16 Jul 2004" "SunOS 5.11" "Direct Access Transport Library Functions" +.SH NAME +dat_rmr_free \- destroy an instance of the RMR +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ldat\fR [ \fIlibrary\fR\&.\|.\|. ] +#include <\fBdat/udat.h\fR> + +DAT_RETURN + dat_rmr_free ( + IN DAT_RMR_HANDLE rmr_handle + ) +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIrmr_handle\fR\fR +.ad +.RS 14n +.rt +Handle for an instance of the RMR to be destroyed. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBdat_rmr_free()\fR function destroys an instance of the RMR. +.sp +.LP +Use of the handle of the destroyed RMR in any subsequent operation except for +the \fBdat_rmr_free()\fR fails. Any remote RDMA operation that uses the +destroyed RMR \fIrmr_context\fR, whose Transport-specific request arrived to +the local host after the \fBdat_rmr_free()\fR has completed, fails and reports +a protection violation. Remote RDMA operation that uses the destroyed RMR +\fIrmr_context\fR, whose Transport-specific request arrived to the local host +prior to the \fBdat_rmr_free()\fR return, might or might not complete +successfully. If it fails, \fBDAT_DTO_ERR_REMOTE_ACCESS\fR is reported in +\fBDAT_DTO_COMPLETION_STATUS\fR for the remote RDMA DTO and the connection is +broken. +.sp +.LP +The \fBdat_rmr_free()\fR function is allowed on either bound or unbound RMR. If +RMR is bound, \fBdat_rmr_free()\fR unbinds (free HCA TPT and other resources +and whatever else binds with length of 0 should do), and then free RMR. +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBDAT_SUCCESS\fR\fR +.ad +.RS 22n +.rt +The operation was successful. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_HANDLE\fR\fR +.ad +.RS 22n +.rt +The \fIrmr_handle\fR handle is invalid. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard: uDAPL, 1.1, 1.2 +_ +MT-LevelUnsafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBlibdat\fR(3LIB), \fBattributes\fR(5) diff --git a/usr/src/man/man3dat/dat_rmr_query.3dat b/usr/src/man/man3dat/dat_rmr_query.3dat new file mode 100644 index 0000000000..aebcd431e6 --- /dev/null +++ b/usr/src/man/man3dat/dat_rmr_query.3dat @@ -0,0 +1,131 @@ +'\" te +.\" This manual page is derived from the DAT/uDAPL 1.2 specification. +.\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH dat_rmr_query 3DAT "16 Jul 2004" "SunOS 5.11" "Direct Access Transport Library Functions" +.SH NAME +dat_rmr_query \- provide RMR parameters +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ldat\fR [ \fIlibrary\fR\&.\|.\|. ] +#include <\fBdat/udat.h\fR> + +DAT_RETURN + dat_rmr_query ( + IN DAT_RMR_HANDLE rmr_handle, + IN DAT_RMR_PARAM_MASK rmr_param_mask, + OUT DAT_RMR_PARAM *rmr_param + ) +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIrmr_handle\fR\fR +.ad +.RS 18n +.rt +Handle for an instance of the RMR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIrmr_param_mask\fR\fR +.ad +.RS 18n +.rt +Mask for RMR parameters. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIrmr_param\fR\fR +.ad +.RS 18n +.rt +Pointer to a Consumer-allocated structure that the Provider fills with RMR +parameters. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBdat_rmr_query()\fR function provides RMR parameters to the Consumer. The +Consumer passes in a pointer to the Consumer-allocated structures for RMR +parameters that the Provider fills. +.sp +.LP +The \fIrmr_param_mask\fR parameter allows Consumers to specify which parameters +to query. The Provider returns values for \fIrmr_param_mask\fR requested +parameters. The Provider can return values for any other parameters. +.sp +.LP +Not all parameters can have a value at all times. For example, +\fIlmr_handle\fR, \fItarget_address\fR, \fIsegment_length\fR, +\fImem_privileges\fR, and \fIrmr_context\fR are not defined for an unbound RMR. +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBDAT_SUCCESS\fR\fR +.ad +.RS 25n +.rt +The operation was successful. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_PARAMETER\fR\fR +.ad +.RS 25n +.rt +The \fIrmr_param_mask\fR parameter is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_HANDLE\fR\fR +.ad +.RS 25n +.rt +The \fImr_handle\fR parameter is invalid. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard: uDAPL, 1.1, 1.2 +_ +MT-LevelUnsafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBlibdat\fR(3LIB), \fBattributes\fR(5) diff --git a/usr/src/man/man3dat/dat_rsp_create.3dat b/usr/src/man/man3dat/dat_rsp_create.3dat new file mode 100644 index 0000000000..5322c446d8 --- /dev/null +++ b/usr/src/man/man3dat/dat_rsp_create.3dat @@ -0,0 +1,260 @@ +'\" te +.\" This manual page is derived from the DAT/uDAPL 1.2 specification. +.\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH dat_rsp_create 3DAT "16 Jul 2004" "SunOS 5.11" "Direct Access Transport Library Functions" +.SH NAME +dat_rsp_create \- create a Reserved Service Point +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ldat\fR [ \fIlibrary\fR\&.\|.\|. ] +#include <\fBdat/udat.h\fR> + +DAT_RETURN + dat_rsp_create ( + IN DAT_IA_HANDLE ia_handle, + IN DAT_CONN_QUAL conn_qual, + IN DAT_EP_HANDLE ep_handle, + IN DAT_EVD_HANDLE evd_handle, + OUT DAT_RSP_HANDLE *rsp_handle + ) +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIia_handle\fR\fR +.ad +.RS 14n +.rt +Handle for an instance of DAT IA. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIconn_qual\fR\fR +.ad +.RS 14n +.rt +Connection Qualifier of the IA the Reserved Service Point listens to. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIep_handle\fR\fR +.ad +.RS 14n +.rt +Handle for the Endpoint associated with the Reserved Service Point that is the +only Endpoint that can accept a Connection Request on this Service Point. The +value \fBDAT_HANDLE_NULL\fR requests the Provider to associate a +Provider-created Endpoint with this Service Point. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIevd_handle\fR\fR +.ad +.RS 14n +.rt +The Event Dispatcher to which an event of Connection Request arrival is +generated. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIrsp_handle\fR\fR +.ad +.RS 14n +.rt +Handle to an opaque Reserved Service Point. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBdat_rsp_create()\fR function creates a Reserved Service Point with the +specified Endpoint that generates, at most, one Connection Request that is +delivered to the specified Event Dispatcher in a Notification event. +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBDAT_SUCCESS\fR\fR +.ad +.RS 30n +.rt +The operation was successful. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INSUFFICIENT_RESOURCES\fR\fR +.ad +.RS 30n +.rt +The operation failed due to resource limitations. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_HANDLE\fR\fR +.ad +.RS 30n +.rt +The \fIia_handle\fR, \fIevd_handle\fR, or \fIep_handle\fR parameter is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_PARAMETER\fR\fR +.ad +.RS 30n +.rt +The \fIconn_qual\fR parameter is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_STATE\fR\fR +.ad +.RS 30n +.rt +Parameter in an invalid state. For example, an Endpoint was not in the Idle +state. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_CONN_QUAL_IN_USE\fR\fR +.ad +.RS 30n +.rt +Specified Connection Qualifier is in use. +.RE + +.SH USAGE +.sp +.LP +The usage of a Reserve Service Point is as follows: +.RS +4 +.TP +.ie t \(bu +.el o +The DAT Consumer creates a Local Endpoint and configures it appropriately. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +The DAT Consumer creates a Reserved Service Point specifying the Local +Endpoint. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +The Reserved Service Point performs the following: +.RS +4 +.TP +.ie t \(bu +.el o +Collects native transport information reflecting a received Connection Request. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Creates a Pending Connection Request. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Creates a Connection Request Notice (event) that includes the Pending +Connection Request (which includes, among others, Reserved Service Point +Connection Qualifier, its Local Endpoint, and information about remote +Endpoint). +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Delivers the Connection Request Notice to the Consumer-specified target (CNO) +\fIevd_handle\fR. The Local Endpoint is transitioned from Reserved to Passive +Connection Pending state. +.RE +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Upon receiving a connection request, or at some time subsequent to that, the +DAT Consumer must either \fBaccept()\fR or \fBreject()\fR the Pending +Connection Request. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +If accepted, the original Local Endpoint is now in a \fBConnected\fR state and +fully usable for this connection, pending only native transport mandated RTU +messages. This includes binding it to the IA port if that was not done +previously. The Consumer is notified that the Endpoint is in a \fBConnected\fR +state by a Connection Established Event on the Endpoint +\fIconnect_evd_handle\fR. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +If rejected, the Local Endpoint point transitions into \fBUnconnected\fR state. +The DAT Consumer can elect to destroy it or reuse it for other purposes. +.RE +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard: uDAPL, 1.1, 1.2 +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBlibdat\fR(3LIB), \fBattributes\fR(5) diff --git a/usr/src/man/man3dat/dat_rsp_free.3dat b/usr/src/man/man3dat/dat_rsp_free.3dat new file mode 100644 index 0000000000..021e0c29ed --- /dev/null +++ b/usr/src/man/man3dat/dat_rsp_free.3dat @@ -0,0 +1,116 @@ +'\" te +.\" This manual page is derived from the DAT/uDAPL 1.2 specification. +.\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH dat_rsp_free 3DAT "16 Jul 2004" "SunOS 5.11" "Direct Access Transport Library Functions" +.SH NAME +dat_rsp_free \- destroy an instance of the Reserved Service Point +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ldat\fR [ \fIlibrary\fR\&.\|.\|. ] +#include <\fBdat/udat.h\fR> + +DAT_RETURN + dat_rsp_free ( + IN DAT_RSP_HANDLE rsp_handle + ) +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIrsp_handle\fR\fR +.ad +.RS 14n +.rt +Handle for an instance of the Reserved Service Point. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBdat_rsp_free()\fR function destroys a specified instance of the Reserved +Service Point. +.sp +.LP +Any incoming Connection Requests for the Connection Qualifier on the destroyed +Service Point was listening on are automatically rejected by the Provider with +the return analogous to the no listening Service Point. +.sp +.LP +The behavior of the Connection Requests in progress is undefined and left to an +implementation, but it must be consistent. This means that either a Connection +Requested Event was generated for the Event Dispatcher associated with the +Service Point, including the creation of the Connection Request instance, or +the Connection Request is rejected by the Provider without any local +notification. +.sp +.LP +This operation has no effect on previously generated Connection Request Event +and Connection Request. +.sp +.LP +The behavior of this operation with creation of a Service Point on the same +Connection Qualifier at the same time is not defined. Consumers are advised to +avoid this scenario. +.sp +.LP +For the Reserved Service Point, the Consumer-provided Endpoint reverts to +Consumer control. Consumers shall be aware that due to a race condition, this +Reserved Service Point might have generated a Connection Request Event and +passed the associated Endpoint to a Consumer in it. +.sp +.LP +Use of the handle of the destroyed Service Point in any consequent operation +fails. +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBDAT_SUCCESS\fR\fR +.ad +.RS 22n +.rt +The operation was successful. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_HANDLE\fR\fR +.ad +.RS 22n +.rt +The \fIrsp_handle\fR parameter is invalid. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard: uDAPL, 1.1, 1.2 +_ +MT-LevelUnsafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBlibdat\fR(3LIB), \fBattributes\fR(5) diff --git a/usr/src/man/man3dat/dat_rsp_query.3dat b/usr/src/man/man3dat/dat_rsp_query.3dat new file mode 100644 index 0000000000..8c0aa7ca87 --- /dev/null +++ b/usr/src/man/man3dat/dat_rsp_query.3dat @@ -0,0 +1,126 @@ +'\" te +.\" This manual page is derived from the DAT/uDAPL 1.2 specification. +.\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH dat_rsp_query 3DAT "16 Jul 2004" "SunOS 5.11" "Direct Access Transport Library Functions" +.SH NAME +dat_rsp_query \- provide parameters of the Reserved Service Point +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ldat\fR [ \fIlibrary\fR\&.\|.\|. ] +#include <\fBdat/udat.h\fR> + +DAT_RETURN + dat_rsp_query ( + IN DAT_RSP_HANDLE rsp_handle, + IN DAT_RSP_PARAM_MASK rsp_param_mask, + OUT DAT_RSP_PARAM *rsp_param + ) +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIrsp_handle\fR\fR +.ad +.RS 18n +.rt +Handle for an instance of Reserved Service Point +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIrsp_param_mask\fR\fR +.ad +.RS 18n +.rt +Mask for RSP parameters. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIrsp_param\fR\fR +.ad +.RS 18n +.rt +Pointer to a Consumer-allocated structure that the Provider fills for +Consumer-requested parameters. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBdat_rsp_query()\fR function provides to the Consumer parameters of the +Reserved Service Point. The Consumer passes in a pointer to the +Consumer-allocated structures for RSP parameters that the Provider fills. +.sp +.LP +The \fIrsp_param_mask\fR parameter allows Consumers to specify which parameters +to query. The Provider returns values for \fIrsp_param_mask\fR requested +parameters. The Provider can return values for any other parameters. +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBDAT_SUCCESS\fR\fR +.ad +.RS 25n +.rt +The operation was successful. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_HANDLE\fR\fR +.ad +.RS 25n +.rt +The \fIrsp_handle\fR parameter is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_PARAMETER\fR\fR +.ad +.RS 25n +.rt +The \fIrsp_param_mask\fR parameter is invalid. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard: uDAPL, 1.1, 1.2 +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBlibdat\fR(3LIB), \fBattributes\fR(5) diff --git a/usr/src/man/man3dat/dat_set_consumer_context.3dat b/usr/src/man/man3dat/dat_set_consumer_context.3dat new file mode 100644 index 0000000000..ce18cd7be0 --- /dev/null +++ b/usr/src/man/man3dat/dat_set_consumer_context.3dat @@ -0,0 +1,122 @@ +'\" te +.\" This manual page is derived from the DAT/uDAPL 1.2 specification. +.\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH dat_set_consumer_context 3DAT "16 Jul 2004" "SunOS 5.11" "Direct Access Transport Library Functions" +.SH NAME +dat_set_consumer_context \- set Consumer context +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ldat\fR [ \fIlibrary\fR\&.\|.\|. ] +#include <\fBdat/udat.h\fR> + +DAT_RETURN + dat_set_consumer_context ( + IN DAT_HANDLE \fIdat_handle\fR, + IN DAT_CONTEXT \fIcontext\fR + ) +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIdat_handle\fR\fR +.ad +.RS 14n +.rt +Handle for a DAT Object associated with \fIcontext\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcontext\fR\fR +.ad +.RS 14n +.rt +Consumer context to be stored within the associated \fIdat_handle\fR. The +Consumer context is opaque to the uDAPL Provider. \fINULL\fR represents no +context. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBdat_set_consumer_context()\fR function associates a Consumer context +with the specified \fIdat_handle\fR. The \fIdat_handle\fR can be one of the +following handle types: \fBDAT_IA_HANDLE\fR, \fBDAT_EP_HANDLE\fR, +\fBDAT_EVD_HANDLE\fR, \fBDAT_CR_HANDLE\fR, \fBDAT_RSP_HANDLE\fR, +\fBDAT_PSP_HANDLE\fR, \fBDAT_PZ_HANDLE\fR, \fBDAT_LMR_HANDLE\fR, +\fBDAT_RMR_HANDLE\fR, or \fBDAT_CNO_HANDLE\fR. +.sp +.LP +Only a single Consumer context is provided for any \fIdat_handle\fR. If there +is a previous Consumer context associated with the specified handle, the new +context replaces the old one. The Consumer can disassociate the existing +context by providing a NULL pointer for the \fIcontext\fR. The Provider makes +no assumptions about the contents of \fIcontext\fR; no check is made on its +value. Furthermore, the Provider makes no attempt to provide any +synchronization for access or modification of the \fIcontext\fR. +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBDAT_SUCCESS\fR\fR +.ad +.RS 25n +.rt +The operation was successful. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_PARAMETER\fR\fR +.ad +.RS 25n +.rt +The \fIcontext\fR parameter is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_HANDLE\fR\fR +.ad +.RS 25n +.rt +The \fIdat_handle\fR parameter is invalid. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard: uDAPL, 1.1, 1.2 +_ +MT-LevelUnsafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBdat_get_consumer_context\fR(3DAT), \fBlibdat\fR(3LIB), \fBattributes\fR(5) diff --git a/usr/src/man/man3dat/dat_srq_create.3dat b/usr/src/man/man3dat/dat_srq_create.3dat new file mode 100644 index 0000000000..0000207c55 --- /dev/null +++ b/usr/src/man/man3dat/dat_srq_create.3dat @@ -0,0 +1,232 @@ +'\" te +.\" This manual page is derived from the DAT/uDAPL 1.2 specification. +.\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH dat_srq_create 3DAT "11 Sep 2006" "SunOS 5.11" "Direct Access Transport Library Functions" +.SH NAME +dat_srq_create \- create an instance of a shared receive queue +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ldat\fR [ \fIlibrary\fR\&.\|.\|. ] +#include <\fBdat/udat.h\fR> + +DAT_RETURN + dat_srq_create ( + IN DAT_IA_HANDLE ia_handle, + IN DAT_PZ_HANDLE pz_handle, + IN DAT_SRQ_ATTR *srq_attr, + OUT DAT_SRQ_HANDLE *srq_handle + ) +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIia_handle\fR\fR +.ad +.RS 14n +.rt +A handle for an open instance of the IA to which the created SRQ belongs. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIpz_handle\fR\fR +.ad +.RS 14n +.rt +A handle for an instance of the Protection Zone. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIsrq_attr\fR\fR +.ad +.RS 14n +.rt +A pointer to a structure that contains Consumer-requested SRQ attributes. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIsrq_handle\fR\fR +.ad +.RS 14n +.rt +A handle for the created instance of a Shared Receive Queue. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBdat_srq_create()\fR function creates an instance of a Shared Receive +Queue (SRQ) that is provided to the Consumer as \fIsrq_handle\fR. If the value +of \fBDAT_RETURN\fR is not \fBDAT_SUCCESS\fR, the value of \fIsrq_handle\fR is +not defined. +.sp +.LP +The created SRQ is unattached to any Endpoints. +.sp +.LP +The Protection Zone \fIpz_handle\fR allows Consumers to control what local +memory can be used for the Recv DTO buffers posted to the SRQ. Only memory +referred to by LMRs of the posted Recv buffers that match the SRQ Protection +Zone can be accessed by the SRQ. +.sp +.LP +The \fIsrq_attributes\fR argument specifies the initial attributes of the +created SRQ. If the operation is successful, the created SRQ will have the +queue size at least \fImax_recv_dtos\fR and the number of entries on the posted +Recv scatter list of at lease \fImax_recv_iov\fR. The created SRQ can have the +queue size and support number of entries on post Recv buffers larger than +requested. Consumer can query SRQ to find out the actual supported queue size +and maximum Recv IOV. +.sp +.LP +The Consumer must set \fIlow_watermark\fR to \fBDAT_SRQ_LW_DEFAULT\fR to ensure +that an asynchronous event will not be generated immediately, since there are +no buffers in the created SRQ. The Consumer should set the Maximum Receive DTO +attribute and the Maximum number of elements in IOV for posted buffers as +needed. +.sp +.LP +When an associated EP tries to get a buffer from SRQ and there are no buffers +available, the behavior of the EP is the same as when there are no buffers on +the EP Recv Work Queue. +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBDAT_SUCCESS\fR\fR +.ad +.RS 30n +.rt +The operation was successful. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INSUFFICIENT_RESOURCES\fR\fR +.ad +.RS 30n +.rt +The operation failed due to resource limitations. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_HANDLE\fR\fR +.ad +.RS 30n +.rt +Either \fIia_handle\fR or \fIpz_handle\fR is an invalid DAT handle. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_PARAMETER\fR\fR +.ad +.RS 30n +.rt +One of the parameters is invalid. Either one of the requested SRQ attributes +was invalid or a combination of attributes is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_MODEL_NOT_SUPPORTED\fR\fR +.ad +.RS 30n +.rt +The requested Model was not supported by the Provider. +.RE + +.SH USAGE +.sp +.LP +SRQ is created by the Consumer prior to creation of the EPs that will be using +it. Some Providers might restrict whether multiple EPs that share a SRQ can +have different Protection Zones. Check the \fIsrq_ep_pz_difference_support\fR +Provider attribute. The EPs that use SRQ might or might not use the same +\fIrecv_evd\fR. +.sp +.LP +Since a Recv buffer of SRQ can be used by any EP that is using SRQ, the +Consumer should ensure that the posted Recv buffers are large enough to receive +an incoming message on any of the EPs. +.sp +.LP +If Consumers do not want to receive an asynchronous event when the number of +buffers in SRQ falls below the Low Watermark, they should leave its value as +\fBDAT_SRQ_LW_DEFAULT\fR. If Consumers do want to receive a notification, they +can set the value to the desired one by calling \fBdat_srq_set_lw\fR(3DAT). +.sp +.LP +SRQ allows the Consumer to use fewer Recv buffers then posting the maximum +number of buffers for each connection. If the Consumer can upper bound the +number of incoming messages over all connections whose local EP is using SRQ, +then instead of posting this maximum for each connection the Consumer can post +them for all connections on SRQ. For example, the maximum utilized link +bandwidth divided over the message size can be used for an upper bound. +.sp +.LP +Depending on the underlying Transport, one or more messages can arrive +simultaneously on an EP that is using SRQ. Thus, the same EP can have multiple +Recv buffers in its possession without these buffers being on SRQ or +\fIrecv_evd\fR. +.sp +.LP +Since Recv buffers can be used by multiple connections of the local EPs that +are using SRQ, the completion order of the Recv buffers is no longer guaranteed +even when they use of the same \fIrecv_evd\fR. For each connection the Recv +buffers completion order is guaranteed to be in the order of the posted +matching Sends to the other end of the connection. There is no ordering +guarantee that Receive buffers will be returned in the order they were posted +even if there is only a single connection (Endpoint) associated with the SRQ. +There is no ordering guarantee between different connections or between +different \fIrecv_evd\fRs. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard: uDAPL, 1.2 +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBdat_srq_free\fR(3DAT), \fBdat_srq_post_recv\fR(3DAT), +\fBdat_srq_query\fR(3DAT), \fBdat_srq_resize\fR(3DAT), +\fBdat_srq_set_lw\fR(3DAT), \fBlibdat\fR(3LIB), \fBattributes\fR(5) diff --git a/usr/src/man/man3dat/dat_srq_free.3dat b/usr/src/man/man3dat/dat_srq_free.3dat new file mode 100644 index 0000000000..25e5aee829 --- /dev/null +++ b/usr/src/man/man3dat/dat_srq_free.3dat @@ -0,0 +1,108 @@ +'\" te +.\" This manual page is derived from the DAT/uDAPL 1.2 specification. +.\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH dat_srq_free 3DAT "16 Jul 2004" "SunOS 5.11" "Direct Access Transport Library Functions" +.SH NAME +dat_srq_free \- destroy an instance of the shared receive queue +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ldat\fR [ \fIlibrary\fR\&.\|.\|. ] +#include <\fBdat/udat.h\fR> + +DAT_RETURN + dat_srq_free ( + IN DAT_SRQ_HANDLE srq_handle + ) +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIsrq_handle\fR\fR +.ad +.RS 14n +.rt +A handle for an instance of SRQ to be destroyed. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBdat_srq_free()\fR function destroys an instance of the SRQ. The SRQ +cannot be destroyed if it is in use by an EP. +.sp +.LP +It is illegal to use the destroyed handle in any consequent operation. +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBDAT_SUCCESS\fR\fR +.ad +.RS 22n +.rt +The operation was successful. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_HANDLE\fR\fR +.ad +.RS 22n +.rt +The \fIsrq_handle\fR argument is an invalid DAT handle. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_SRQ_IN_USE\fR\fR +.ad +.RS 22n +.rt +The Shared Receive Queue can not be destroyed because it is in still associated +with an EP instance. +.RE + +.SH USAGE +.sp +.LP +If the Provider detects the use of a deleted object handle, it should return +\fBDAT_INVALID_HANDLE\fR. The Provider should avoid assigning the used handle +as long as possible. Once reassigned the handle is no longer a handle of a +destroyed object. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard: uDAPL, 1.2 +_ +MT-LevelUnsafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBdat_srq_create\fR(3DAT), \fBdat_srq_post_recv\fR(3DAT), +\fBdat_srq_query\fR(3DAT), \fBdat_srq_resize\fR(3DAT), +\fBdat_srq_set_lw\fR(3DAT), \fBlibdat\fR(3LIB), \fBattributes\fR(5) diff --git a/usr/src/man/man3dat/dat_srq_post_recv.3dat b/usr/src/man/man3dat/dat_srq_post_recv.3dat new file mode 100644 index 0000000000..0ecd07bf06 --- /dev/null +++ b/usr/src/man/man3dat/dat_srq_post_recv.3dat @@ -0,0 +1,280 @@ +'\" te +.\" This manual page is derived from the DAT/uDAPL 1.2 specification. +.\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH dat_srq_post_recv 3DAT "16 Jul 2004" "SunOS 5.11" "Direct Access Transport Library Functions" +.SH NAME +dat_srq_post_recv \- add receive buffers to shared receive queue +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ldat\fR [ \fIlibrary\fR\&.\|.\|. ] +#include <\fBdat/udat.h\fR> + +DAT_RETURN + dat_srq_post_recv ( + IN DAT_SRQ_HANDLE srq_handle, + IN DAT_COUNT num_segments, + IN DAT_LMR_TRIPLET *local_iov, + IN DAT_DTO_COOKIE user_cookie + ) +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIsrq_handle\fR\fR +.ad +.RS 16n +.rt +A handle for an instance of the SRQ. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fInum_segments\fR\fR +.ad +.RS 16n +.rt +The number of \fIlmr_triplets\fR in \fIlocal_iov\fR. Can be 0 for receiving a +zero-size message. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIlocal_iov\fR\fR +.ad +.RS 16n +.rt +An I/O Vector that specifies the local buffer to be filled. Can be \fINULL\fR +for receiving a zero-size message. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIuser_cookie\fR\fR +.ad +.RS 16n +.rt +A user-provided cookie that is returned to the Consumer at the completion of +the Receive DTO. Can be \fINULL\fR. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBdat_srq_post_recv()\fR function posts the receive buffer that can be +used for the incoming message into the \fIlocal_iov\fR by any connected EP that +uses SRQ. +.sp +.LP +The \fInum_segments\fR argument specifies the number of segments in the +\fIlocal_iov\fR. The \fIlocal_iov\fR segments are filled in the I/O Vector +order until the whole message is received. This ensures that all the front +segments of the \fIlocal_iov\fR I/O Vector are completely filled, only one +segment is partially filled, if needed, and all segments that follow it are not +filled at all. The actual order of segment fillings is left to the +implementation. +.sp +.LP +The \fIuser_cookie\fR argument allows Consumers to have unique identifiers for +each DTO. These identifiers are completely under user control and are opaque to +the Provider. There is no requirement on the Consumer that the value +\fIuser_cookie\fR should be unique for each DTO. The \fIuser_cookie\fR is +returned to the Consumer in the Completion event for the posted Receive. +.sp +.LP +The completion of the posted Receive is reported to the Consumer asynchronously +through a DTO Completion event based on the configuration of the EP that +dequeues the posted buffer and the specified \fIcompletion_flags\fR value for +Solicited Wait for the matching Send. If EP Recv Completion Flag is +\fBDAT_COMPLETION_UNSIGNALLED_FLAG\fR, which is the default value for SRQ EP, +then all posted Recvs will generate completions with Signal Notifications. +.sp +.LP +A Consumer should not modify the \fIlocal_iov\fR or its content until the DTO +is completed. When a Consumer does not adhere to this rule, the behavior of the +Provider and the underlying Transport is not defined. Providers that allow +Consumers to get ownership of the \fIlocal_iov\fR but not the memory it +specified back after the \fBdat_srq_post_recv()\fR returns should document this +behavior and also specify its support in Provider attributes. This behavior +allows Consumer full control of the \fIlocal_iov\fR content after +\fBdat_srq_post_recv()\fR returns. Because this behavior is not guaranteed by +all Providers, portable Consumers shall not rely on this behavior. Consumers +shall not rely on the Provider copying \fIlocal_iov\fR information. +.sp +.LP +The \fBDAT_SUCCESS\fR return of the \fBdat_srq_post_recv()\fR is at least the +equivalent of posting a Receive operation directly by native Transport. +Providers shall avoid resource allocation as part of \fBdat_srq_post_recv()\fR +to ensure that this operation is nonblocking. +.sp +.LP +The completion of the Receive posted to the SRQ is equivalent to what happened +to the Receive posted to the Endpoint for the Endpoint that dequeued the +Receive buffer from the Shared Receive queue. +.sp +.LP +The posted Recv DTO will complete with signal, equivalently to the completion +of Recv posted directly to the Endpoint that dequeued the Recv buffer from SRQ +with \fBDAT_COMPLETION_UNSIGNALLED_FLAG\fR value not set for it. +.sp +.LP +The posted Recv DTOs will complete in the order of Send postings to the other +endpoint of each connection whose local EP uses SRQ. There is no ordering among +different connections regardless if they share SRQ and \fIrecv_evd\fR or not. +.sp +.LP +If the reported status of the Completion DTO event corresponding to the posted +RDMA Read DTO is not \fBDAT_DTO_SUCCESS\fR, the content of the \fIlocal_iov\fR +is not defined and the \fItransfered_length\fR in the DTO Completion event is +not defined. +.sp +.LP +The operation is valid for all states of the Shared Receive Queue. +.sp +.LP +The \fBdat_srq_post_recv()\fR function is asynchronous, nonblocking, and its +thread safety is Provider-dependent. +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBDAT_SUCCESS\fR\fR +.ad +.RS 30n +.rt +The operation was successful. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_HANDLE\fR\fR +.ad +.RS 30n +.rt +The \fIsrq_handle\fR argument is an invalid DAT handle. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INSUFFICIENT_RESOURCES\fR\fR +.ad +.RS 30n +.rt +The operation failed due to resource limitations. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_PARAMETER\fR\fR +.ad +.RS 30n +.rt +Invalid parameter. For example, one of the IOV segments pointed to a memory +outside its LMR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_PROTECTION_VIOLATION\fR\fR +.ad +.RS 30n +.rt +Protection violation for local or remote memory access. +.sp +Protection Zone mismatch between an LMR of one of the \fIlocal_iov\fR segments +and the SRQ. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_PRIVILEGES_VIOLATION\fR\fR +.ad +.RS 30n +.rt +Privileges violation for local or remote memory access. One of the LMRs used +in local_iov was either invalid or did not have the local write privileges. +.RE + +.SH USAGE +.sp +.LP +For the best Recv operation performance, the Consumer should align each buffer +segment of \fIlocal_iov\fR to the Optimal Buffer Alignment attribute of the +Provider. For portable applications, the Consumer should align each buffer +segment of \fIlocal_iov\fR to the \fBDAT_OPTIMAL_ALIGNMENT\fR. +.sp +.LP +Since any of the Endpoints that use the SRQ can dequeue the posted buffer from +SRQ, Consumers should post a buffer large enough to handle incoming message on +any of these Endpoint connections. +.sp +.LP +The buffer posted to SRQ does not have a DTO completion flag value. Posting +Recv buffer to SRQ is semantically equivalent to posting to EP with +\fBDAT_COMPLETION_UNSIGNALLED_FLAG\fR is not set. The configuration of the Recv +Completion flag of an Endpoint that dequeues the posted buffer defines how DTO +completion is generated. If the Endpoint Recv Completion flag is +\fBDAT_COMPLETION_SOLICITED_WAIT_FLAG\fR then matching Send DTO completion flag +value for Solicited Wait determines if the completion will be Signalled or not. +If the Endpoint Recv Completion flag is not +\fBDAT_COMPLETION_SOLICITED_WAIT_FLAG\fR, the posted Recv completion will be +generated with Signal. If the Endpoint Recv Completion flag is +\fBDAT_COMPLETION_EVD_THRESHOLD_FLAG\fR, the posted Recv completion will be +generated with Signal and \fIdat_evd_wait\fR threshold value controls if the +waiter will be unblocked or not. +.sp +.LP +Only the Endpoint that is in Connected or Disconnect Pending states can dequeue +buffers from SRQ. When an Endpoint is transitioned into Disconnected state, all +the buffers that it dequeued from SRQ are queued on the Endpoint +\fIrecv_evd\fR. All the buffers that the Endpoint has not completed by the time +of transition into Disconnected state and that have not completed message +reception will be flushed. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard: uDAPL, 1.2 +_ +MT-LevelUnsafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBdat_srq_create\fR(3DAT), \fBdat_srq_free\fR(3DAT), +\fBdat_srq_query\fR(3DAT), \fBdat_srq_resize\fR(3DAT), +\fBdat_srq_set_lw\fR(3DAT), \fBlibdat\fR(3LIB), \fBattributes\fR(5) diff --git a/usr/src/man/man3dat/dat_srq_query.3dat b/usr/src/man/man3dat/dat_srq_query.3dat new file mode 100644 index 0000000000..49055acedd --- /dev/null +++ b/usr/src/man/man3dat/dat_srq_query.3dat @@ -0,0 +1,195 @@ +'\" te +.\" This manual page is derived from the DAT/uDAPL 1.2 specification. +.\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH dat_srq_query 3DAT "16 Jul 2004" "SunOS 5.11" "Direct Access Transport Library Functions" +.SH NAME +dat_srq_query \- provide parameters of the shared receive queue +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ldat\fR [ \fIlibrary\fR\&.\|.\|. ] +#include <\fBdat/udat.h\fR> + +DAT_RETURN + dat_srq_query ( + IN DAT_SRQ_HANDLE srq_handle, + IN DAT_SRQ_PARAM_MASK srq_param_mask, + OUT DAT_SRQ_PARAM *srq_param + ) +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIsrq_handle\fR\fR +.ad +.RS 18n +.rt +A handle for an instance of the SRQ. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIsrq_param_mask\fR\fR +.ad +.RS 18n +.rt +The mask for SRQ parameters. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIsrq_param\fR\fR +.ad +.RS 18n +.rt +A pointer to a Consumer-allocated structure that the Provider fills with SRQ +parameters. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBdat_srq_query()\fR function provides to the Consumer SRQ parameters. The +Consumer passes a pointer to the Consumer-allocated structures for SRQ +parameters that the Provider fills. +.sp +.LP +The \fIsrq_param_mask\fR argument allows Consumers to specify which parameters +to query. The Provider returns values for the requested \fIsrq_param_mask\fR +parameters. The Provider can return values for any other parameters. +.sp +.LP +In addition to the elements in SRQ attribute, \fBdat_srq_query()\fR provides +additional information in the \fBsrq_param\fR structure if Consumer requests it +with \fIsrq_param_mask\fR settings. The two that are related to entry counts on +SRQ are the number of Receive buffers (\fIavailable_dto_count\fR) available for +EPs to dequeue and the number of occupied SRQ entries +(\fIoutstanding_dto_count\fR) not available for new Recv buffer postings. +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBDAT_SUCCESS\fR\fR +.ad +.RS 25n +.rt +The operation was successful. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_PARAMETER\fR\fR +.ad +.RS 25n +.rt +The \fIsrq_param_mask\fR argument is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_HANDLE\fR\fR +.ad +.RS 25n +.rt +The \fIsrq_handle\fR argument is an invalid DAT handle. +.RE + +.SH USAGE +.sp +.LP +The Provider might not be able to provide the number of outstanding Recv of SRQ +or available Recvs of SRQ. The Provider attribute indicates if the Provider +does not support the query for one or these values. Even when the Provider +supports the query for one or both of these values, it might not be able to +provide this value at this moment. In either case, the return value for the +attribute that cannot be provided will be \fBDAT_VALUE_UNKNOWN\fR. +.sp +.LP +Example: Consumer created SRQ with 10 entries and associated 1 EP with it. 3 +Recv buffers have been posted to it. The query will report: +.sp +.in +2 +.nf +max_recv_dtos=10, +available_dto_count=3, +outstanding_dto_count=3. +.fi +.in -2 +.sp + +.sp +.LP +After a Send message arrival the query will report: +.sp +.in +2 +.nf +max_recv_dtos=10, +available_dto_count=2, +outstanding_dto_count=3. +.fi +.in -2 +.sp + +.sp +.LP +After Consumer dequeues Recv completion the query will report: +.sp +.in +2 +.nf +max_recv_dtos=10, +available_dto_count=2, +outstanding_dto_count=2. +.fi +.in -2 +.sp + +.sp +.LP +In general, each EP associated with SRQ can have multiple buffers in progress +of receiving messages as well completed Recv on EVDs. The watermark setting +helps to control how many Recv buffers posted to SRQ an Endpoint can own. +.sp +.LP +If the Provider cannot support the query for the number of outstanding Recv of +SRQ or available Recvs of SRQ, the value return for that attribute should be +\fBDAT_VALUE_UNKNOWN\fR. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard: uDAPL, 1.2 +_ +MT-LevelUnsafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBdat_srq_create\fR(3DAT), \fBdat_srq_free\fR(3DAT), +\fBdat_srq_post_recv\fR(3DAT), \fBdat_srq_resize\fR(3DAT), +\fBdat_srq_set_lw\fR(3DAT), \fBlibdat\fR(3LIB), \fBattributes\fR(5) diff --git a/usr/src/man/man3dat/dat_srq_resize.3dat b/usr/src/man/man3dat/dat_srq_resize.3dat new file mode 100644 index 0000000000..dd6d10ef99 --- /dev/null +++ b/usr/src/man/man3dat/dat_srq_resize.3dat @@ -0,0 +1,163 @@ +'\" te +.\" This manual page is derived from the DAT/uDAPL 1.2 specification. +.\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH dat_srq_resize 3DAT "16 Jul 2004" "SunOS 5.11" "Direct Access Transport Library Functions" +.SH NAME +dat_srq_resize \- modify the size of the shared receive queue +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ldat\fR [ \fIlibrary\fR\&.\|.\|. ] +#include <\fBdat/udat.h\fR> + +DAT_RETURN + dat_srq_resize ( + IN DAT_SRQ_HANDLE srq_handle, + IN DAT_COUNT srq_max_recv_dto + ) +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIsrq_handle\fR\fR +.ad +.RS 20n +.rt +A handle for an instance of the SRQ. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIsrq_max_recv_dto\fR\fR +.ad +.RS 20n +.rt +The new maximum number of Recv DTOs that Shared Receive Queue must hold. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBdat_srq_resize()\fR function modifies the size of the queue of SRQ. +.sp +.LP +Resizing of Shared Receive Queue should not cause any incoming messages on any +of the EPs that use the SRQ to be lost. If the number of outstanding Recv +buffers on the SRQ is larger then the requested \fIsrq_max_recv_dto\fR, the +operation returns \fBDAT_INVALID_STATE\fR and do not change SRQ. This includes +not just the buffers on the SRQ but all outstanding Receive buffers that had +been posted to the SRQ and whose completions have not reaped yet. Thus, the +outstanding buffers include the buffers on SRQ, the buffers posted to SRQ at +are at SRQ associated EPs, and the buffers posted to SRQ for which completions +have been generated but not yet reaped by Consumer from recv_evds of the EPs +that use the SRQ. +.sp +.LP +If the requested \fIsrq_max_recv_dto\fR is below the SRQ low watermark, the +operation returns \fBDAT_INVALID_STATE\fR and does not change SRQ. +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBDAT_SUCCESS\fR\fR +.ad +.RS 30n +.rt +The operation was successful. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_HANDLE\fR\fR +.ad +.RS 30n +.rt +The \fIsrq_handle\fR argument is an invalid DAT handle. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_PARAMETER\fR\fR +.ad +.RS 30n +.rt +The \fIsrq_max_recv_dto\fR argument is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INSUFFICIENT_RESOURCES\fR\fR +.ad +.RS 30n +.rt +The operation failed due to resource limitations. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_STATE\fR\fR +.ad +.RS 30n +.rt +Invalid state. Either the number of entries on the SRQ exceeds the requested +SRQ queue length or the requested SRQ queue length is smaller than the SRQ low +watermark. +.RE + +.SH USAGE +.sp +.LP +The \fBdat_srq_resize()\fR function is required not to lose any buffers. Thus, +it cannot shrink below the outstanding number of Recv buffers on SRQ. There is +no requirement to shrink the SRQ to return \fBDAT_SUCCESS\fR. +.sp +.LP +The quality of the implementation determines how closely to the +Consumer-requested value the Provider shrinks the SRQ. For example, the +Provider can shrink the SRQ to the Consumer-requested value and if the +requested value is smaller than the outstanding buffers on SRQ, return +\fBDAT_INVALID_STATE\fR; or the Provider can shrink to some value larger than +that requested by the Consumer but below current SRQ size; or the Provider does +not change the SRQ size and still returns \fBDAT_SUCCESS\fR. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard: uDAPL, 1.2 +_ +MT-LevelUnsafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBdat_srq_create\fR(3DAT), \fBdat_srq_free\fR(3DAT), +\fBdat_srq_post_recv\fR(3DAT), \fBdat_srq_query\fR(3DAT), +\fBdat_srq_set_lw\fR(3DAT), \fBlibdat\fR(3LIB), \fBattributes\fR(5) diff --git a/usr/src/man/man3dat/dat_srq_set_lw.3dat b/usr/src/man/man3dat/dat_srq_set_lw.3dat new file mode 100644 index 0000000000..c9778e83b3 --- /dev/null +++ b/usr/src/man/man3dat/dat_srq_set_lw.3dat @@ -0,0 +1,146 @@ +'\" te +.\" This manual page is derived from the DAT/uDAPL 1.2 specification. +.\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH dat_srq_set_lw 3DAT "16 Jul 2004" "SunOS 5.11" "Direct Access Transport Library Functions" +.SH NAME +dat_srq_set_lw \- set low watermark on shared receive queue +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ldat\fR [ \fIlibrary\fR\&.\|.\|. ] +#include <\fBdat/udat.h\fR> + +DAT_RETURN + dat_srq_set_lw ( + IN DAT_SRQ_HANDLE srq_handle, + IN DAT_COUNT low_watermark + ) +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIsrq_handle\fR\fR +.ad +.RS 17n +.rt +A handle for an instance of a Shared Receive Queue. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIlow_watermark\fR\fR +.ad +.RS 17n +.rt +The low watermark for the number of Recv buffers on SRQ. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBdat_srq_set_lw()\fR function sets the low watermark value for the SRQ +and arms the SRQ for generating an asynchronous event for the low watermark. An +asynchronous event will be generated when the number of buffers on the SRQ is +below the low watermark for the first time. This can occur during the current +call or when an associated EP takes a buffer from the SRQ. +.sp +.LP +The asynchronous event will be generated only once per setting of the low +watermark. Once an event is generated, no new asynchronous events for the +number of buffers inthe SRQ below the specified value will be generated until +the SRQ is again set for the Low Watermark. If the Consumer is again interested +in the event, the Consumer should set the low watermark again. +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBDAT_SUCCESS\fR\fR +.ad +.RS 27n +.rt +The operation was successful. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_HANDLE\fR\fR +.ad +.RS 27n +.rt +The \fIsrq_handle\fR argument is an invalid DAT handle. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_PARAMETER\fR\fR +.ad +.RS 27n +.rt +Invalid parameter; the value of \fIlow_watermark\fR is exceeds the value of +\fImax_recv_dtos\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_MODEL_NOT_SUPPORTED\fR\fR +.ad +.RS 27n +.rt +The requested Model was not supported by the Provider. The Provider does not +support SRQ Low Watermark. +.RE + +.SH USAGE +.sp +.LP +Upon receiving the asynchronous event for the SRQ low watermark, the Consumer +can replenish Recv buffers on the SRQ or take any other action that is +appropriate. +.sp +.LP +Regardless of whether an asynchronous event for the low watermark has been +generated, this operation will set the generation of an asynchronous event with +the Consumer-provided low watermark value. If the new low watermark value is +below the current number of free Receive DTOs posted to the SRQ, an +asynchronous event will be generated immediately. Otherwise the old low +watermark value is simply replaced with the new one. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard: uDAPL, 1.2 +_ +MT-LevelUnsafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBdat_srq_create\fR(3DAT), \fBdat_srq_free\fR(3DAT), +\fBdat_srq_post_recv\fR(3DAT), \fBdat_srq_query\fR(3DAT), +\fBdat_srq_resize\fR(3DAT), \fBlibdat\fR(3LIB), \fBattributes\fR(5) diff --git a/usr/src/man/man3dat/dat_strerror.3dat b/usr/src/man/man3dat/dat_strerror.3dat new file mode 100644 index 0000000000..cb37d5af1b --- /dev/null +++ b/usr/src/man/man3dat/dat_strerror.3dat @@ -0,0 +1,106 @@ +'\" te +.\" This manual page is derived from the DAT/uDAPL 1.2 specification. +.\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH dat_strerror 3DAT "16 Jul 2004" "SunOS 5.11" "Direct Access Transport Library Functions" +.SH NAME +dat_strerror \- convert a DAT return code into human readable strings +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ldat\fR [ \fIlibrary\fR\&.\|.\|. ] +#include <\fBdat/udat.h\fR> + +DAT_RETURN + dat_strerror( + IN DAT_RETURN return, + OUT const char **major_message, + OUT const char **minor_message + ) +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIreturn\fR\fR +.ad +.RS 11n +.rt +DAT function return value. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fImessage\fR\fR +.ad +.RS 11n +.rt +A pointer to a character string for the return. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBdat_strerror()\fR function converts a DAT return code into human +readable strings. The \fImajor_message\fR is a string-converted +\fBDAT_TYPE_STATUS\fR, while \fIminor_message\fR is a string-converted +\fBDAT_SUBTYPE_STATUS\fR. If the return of this function is not +\fBDAT_SUCCESS\fR, the values of \fImajor_message\fR and \fIminor_message\fR +are not defined. +.sp +.LP +If an undefined \fBDAT_RETURN\fR value was passed as the return parameter, the +operation fails with \fBDAT_INVALID_PARAMETER\fR returned. The operation +succeeds when \fBDAT_SUCCESS\fR is passed in as the return parameter. +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBDAT_SUCCESS\fR\fR +.ad +.RS 25n +.rt +The operation was successful. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAT_INVALID_PARAMETER\fR\fR +.ad +.RS 25n +.rt +Invalid parameter. The \fIreturn\fR value is invalid. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard: uDAPL, 1.1, 1.2 +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBlibdat\fR(3LIB), \fBattributes\fR(5) |